Retirada na loja

Pedidos com delivery_method=pickup: o cliente paga online (ou no balcão) e vai buscar pessoalmente. Sem transportadora, sem rastreio — no lugar disso, um código de confirmação que o cliente apresenta na hora de retirar.

Pré-requisitos: leia primeiro Pedidos: visão geral. Os conceitos de possible-statuses, rota única /status e workflow_type valem aqui também.

Quando um pedido cai aqui

Retirada é um eixo de fulfillment, não um perfil comercial: o que manda é o campo delivery_method=pickup, definido na criação do pedido. Qualquer workflow_type pode terminar em retirada — um pedido de industrialização, por exemplo, passa pela fábrica e depois fica pronto para o cliente buscar. Em pedidos antigos você ainda encontra workflow_type=in_store_pickup; trate igual.

{
  "order_number": "ORD-000456",      // identificador público do pedido
  "delivery_method": "pickup",       // ← é por aqui que você reconhece
  "workflow_type": "in_store_pickup",
  "status": "ready_for_pickup",
  "pickup_address": {…},             // onde o cliente retira (quando definido)
  "picked_up_at": null               // preenche quando o cliente buscar
}

O que muda na prática: o pedido nunca passa por ready_to_ship/shipped. O possible-statuses já cuida disso — em pedidos de retirada, os status de envio nem aparecem como opção (e vice-versa: pedidos de envio nunca veem os status de retirada).

O caminho

A bifurcação em relação ao fluxo de entrega acontece em preparing: onde o pedido de envio iria para ready_to_ship, o de retirada vai para ready_for_pickup. Antes disso, o começo é idêntico.

Você pode encontrar um status reserved no catálogo de enums. Ignore-o ao integrar: nenhuma transição parte de paid para ele — o caminho real é paid → preparing → ready_for_pickup.

Etapa a etapa

Tudo pela dupla de sempre:

GET/api/v1/sellers/orders/{id}/possible-statuses

POST/api/v1/sellers/orders/{id}/status

O código de confirmação

É a peça central da retirada — e a parte mais incompreendida.

Quem tem o código é o cliente, não você. Um código numérico de 4 dígitos é gerado na criação do pedido e entregue só ao comprador (ele vê no acompanhamento do pedido dele). A API nunca devolve esse código para a loja — nem no detalhe do pedido, nem no metadata. É de propósito: o código prova que quem está no balcão é o comprador. Sua integração não consulta o código; ela digita o que o cliente apresentar.

POST /api/v1/sellers/orders/ORD-000456/status
Content-Type: application/json

{ "status": "picked_up", "data": { "confirmation_code": "4821" } }

O confirmation_code é obrigatório nessa transição (o payload_schema do possible-statuses marca required). O que pode dar errado:

Confirmou, acabou. O picked_up encadeia delivered automaticamente no mesmo request (o ato de digitar o código é a entrega física). Não chame delivered depois — a resposta já volta com o pedido entregue, e picked_up_at preenchido.

Expiração da retirada

O pedido tem um prazo para ser retirado (por padrão, 3 dias a partir da criação). Vencido o prazo:

• Uma tentativa de confirmação tardia move o pedido para pickup_expired em vez de aceitar a retirada — mesmo com o código certo.
• Você também pode marcar manualmente: { "status": "pickup_expired" }.
• Em seguida o sistema cancela sozinho (pickup_expired → cancelled), disparando o pipeline completo: estorno ao cliente, liberação do estoque reservado, e-mail. Você não precisa (nem deve) chamar cancelled por conta própria.

Na timeline (GET /orders/{id}/events) o cancelamento aparece com motivo "Retirada expirada" e autoria do sistema. Cliente desistiu mas o prazo ainda não venceu? Aí é um cancelamento comum — ver abaixo.

Cancelamento

Mesma regra dos outros fluxos: o seller só cancela antes da preparação. Em paid, mande { "status": "cancelled" } com um reason opcional. De preparing em diante, o possible-statuses esconde a opção e a API recusa — cancelamento vira assunto da operação da plataforma.

A exceção prática é a expiração: pickup_expired → cancelled acontece sozinho, sem depender de ninguém.

Emissão fiscal

A janela abre em preparing e segue aberta em ready_for_pickup e picked_up (e delivered). Retirada presencial não dispensa documento: a transição preparing → ready_for_pickup tem o mesmo gate fiscal do envio e recusa com 422 (campo fiscal) se não houver NF-e ou Declaração de Conteúdo emitida.

Ordem prática: separar → emitir documento (fiscal) → ready_for_pickup → aguardar o cliente. Etiqueta de transporte não se aplica — não há shipment de transportadora para gerar.

Para onde ir agora