Entrega

Workflow standard com delivery_method=shipping: a venda comum, que termina com um pacote saindo da loja e chegando na casa do cliente. É o caminho da grande maioria dos pedidos — e a base sobre a qual os outros workflows se encaixam.

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

Todo pedido nasce com dois eixos definidos na criação — você não escolhe nenhum deles depois:

• workflow_type é o perfil comercial. Sem natureza especial (fabricação, espera de estoque, campanha), o pedido é standard.
• delivery_method é o eixo de fulfillment: shipping (envio) ou pickup (retirada presencial).

Este guia cobre a combinação mais comum: standard + shipping. Se o cliente escolheu retirar na loja, o começo é igual, mas o caminho bifurca depois de preparing — veja Pedidos: retirada.

{
  "order_number": "ORD-000123",   // identificador público do pedido
  "workflow_type": "standard",    // ← perfil padrão
  "delivery_method": "shipping",  // ← termina com envio
  "status": "paid",               // pagamento confirmado, sua vez
  "shipping": {…}                 // frete escolhido no checkout
}

Os valores possíveis dos dois eixos (e de todos os outros enums do pedido) vêm de GET/api/v1/sellers/orders/enums. Para os status já agrupados por workflow, use a rota pública GET/api/global/enums/order/status.

O caminho

Sua fila de entrada é a listagem filtrada por pedidos pagos:

GET /api/v1/sellers/orders?status=paid,preparing&sort=-created_at

E o avanço, como sempre, é o par possible-statuses + rota única:

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

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

Etapa a etapa

O tracking_code em shipped é opcional (string, máx 100), mas alimenta a tela de acompanhamento do cliente e a rota GET/api/v1/sellers/orders/{id}/tracking — informe sempre que tiver.

Pontos de atenção

O gate fiscal trava o despacho

Mercadoria não sai sem documento fiscal. As transições para ready_to_ship e shippedrecusam com 422 (campo fiscal no erro) se o pedido não tiver uma NF-e ou Declaração de Conteúdo emitida:

{
  "errors": {
    "fiscal": ["É necessário emitir uma NF-e ou Declaração de Conteúdo antes de despachar o pedido."]
  }
}

Por isso a ordem prática dentro de preparing é: emitir documento → gerar etiqueta → marcar ready_to_ship. O passo a passo da emissão está em Pedidos: fiscal.

A máquina de estados aceita pular de paid direto para ready_to_ship, mas na prática o atalho raramente serve: a emissão fiscal só abre a partir de preparing, e sem documento o gate barra a transição. Passe por preparing.

Partes do fluxo podem andar sozinhas

Não assuma que você é o único a mover o pedido — releia possible-statuses antes de cada ação em vez de confiar num estado em cache:

• paid → preparing automático: lojas com preparação automática habilitada pela plataforma têm esse passo dado pelo sistema assim que o pagamento confirma.
• ready_to_ship → shipped automático: quando o shipment é rastreado pela plataforma e entra em trânsito, o pedido é marcado como enviado sem você chamar nada.
• shipped → delivered automático: idem quando a transportadora confirma a entrega.

Cada mudança fica registrada em GET /orders/{id}/events, com author_type dizendo quem fez (você, o sistema, o admin).

Quem pode confirmar delivered

Depende de quem opera a entrega:

Prazos viram ocorrências

Pedido pago tem SLA: documento fiscal e preparação têm prazos configurados pela plataforma, e estourar gera ocorrência ligada ao pedido. Não deixe pedidos parados em paid.

Cancelamento

A janela do seller é curta: só enquanto o pedido não entrou em preparação. Em paid você ainda pode:

{
  "status": "cancelled",
  "data": { "reason": "Sem estoque para entregar no prazo." }
}

A partir de preparing (inclusive), o cancelamento é exclusivo da operação da plataforma — a API recusa com 422 e o possible-statusesjá nem lista a opção cancel para você. Se precisar cancelar um pedido em preparação ou despachado, abra o caso com o suporte da plataforma.

delivered é terminal: depois dele, o caminho para desfazer a venda é a devolução, não o cancelamento.

Emissão fiscal

A elegibilidade abre em preparing e segue valendo em ready_to_ship, shipped e delivered. Em paid a API fiscal recusa com 422 ("o pedido precisa estar em preparação"). Ou seja:

Emitiu tarde demais? Sem problema — dá para registrar a NF-e mesmo com o pedido já delivered (caso clássico: corrigir documento depois da entrega). O fluxo completo de emissão, polling e download está em Pedidos: fiscal.

Para onde ir agora