Visão geral

Como sua loja recebe pedidos, avança pelos estados do ciclo de vida, e onde estão as outras peças do quebra-cabeça (fiscal, etiquetas, devoluções, industrialização).

Este guia é o mapa. Cada tema tem um guide próprio com o passo a passo aprofundado:

• Industrialização, para o workflow production.
• Fiscal: NF-e, Declaração de Conteúdo, XML.
• Logística: shipments e etiquetas.
• Devoluções: RMA encaminhada ao seller.

Conceitos

O objeto que GET /orders/{id} devolve, de relance — campos principais (vários trazem um par *_label em pt-BR para exibir):

{
  "order_number": "ORD-000123",      // ← identificador público do pedido
  "checkout_group_id": "01K8PB1QA…", // agrupa pedidos do mesmo checkout
  "store": {…},                      // loja responsável
  "customer": {…},                   // comprador
  "type": "standard",                // tipo do pedido (+ type_label)
  "channel": "marketplace",          // canal de venda (+ channel_label)
  "workflow_type": "standard",       // ← workflow: standard | production (industrialização)
  "status": "paid",                  // ← estado atual (+ status_label, status_color)
  "totals": {…},                     // produtos, frete, descontos, total
  "items": [{…}],                    // linhas do pedido
  "applied_benefits": [{…}],         // cupons/descontos aplicados
  "invoices": [{…}],                 // documentos fiscais (ver Fiscal)
  "shipping": {…},                   // transportadora e frete (ver Logística)
  "delivery_method": "shipping",     // shipping | pickup (+ delivery_method_label)
  "is_production_order": false,      // true quando workflow_type=production
  "payment_method": "pix",           // forma de pagamento (+ payment_method_label)
  "payment_url": "https://…",        // link de pagamento (canais direct/store_seller; null fora de waiting_payment)
  "payment_link_target": "store",    // onde o link abre: platform | store
  "created_at": "2026-04-26T14:32:11Z",
  "updated_at": "2026-04-26T14:35:42Z"
}

Campos que não se aplicam ao pedido vêm null (ex.: picked_up_at sem retirada, payment_expires_at após o pagamento). Trate a ausência como "não se aplica", não como erro.

Fluxos de pedido

Cada pedido segue um workflow — o trilho de estados entre o pagamento e a conclusão, definido pelo workflow_type. O dia a dia da loja muda conforme o trilho, e cada um tem um guia próprio com o passo a passo:

• Entrega: o fluxo padrão, com envio por transportadora.
• Retirada: cliente paga online e busca no balcão.
• Sob encomenda: pré-venda e espera por reposição de estoque.
• Industrialização: produto que passa pela fábrica antes de embalar.

Como pensar num pedido

Um pedido é o estado de uma compra, desde o pagamento confirmado até a entrega (ou cancelamento). Quem dirige o estado é o seller, chamando a API conforme o pedido caminha.

Três ideias fixam tudo:

1. order_number é o identificador. Em toda rota onde aparece {id}, é o order_number (ex.: ORD-000123). É público, estável e visível ao cliente.

2. Toda transição passa por uma única rota.POST /orders/{id}/status muda o estado, e o que muda de uma transição para outra é só o valor de status (mais um data, quando o estado pedir). Você não vai encontrar um endpoint para cada ação — nada de /cancel, /ship ou /deliver por conta própria. Isso é de propósito: em vez de te obrigar a conhecer dezenas de rotas, juntamos tudo numa só. Você aprende uma rota e conduz o pedido do início ao fim com ela.

3. Você não precisa decorar o que pode chamar. A rota GET /orders/{id}/possible-statuses já devolve, para o estado atual do pedido, quais transições são válidas e qual o payload de cada uma (payload_schema). Se você só lê essa rota e age sobre o que ela devolve, não tem como mandar um status inválido.

O ciclo padrão (workflow_type=standard)

Esse é o caminho da maioria dos pedidos. Outros workflow_type (production, in_store_pickup, pre_order, backorder, collective) inserem etapas antes ou dentro desse fluxo, mas no fim caem no mesmo delivered.

Conceitos que aparecem em vários lugares

workflow_type define o "perfil" do pedido e o conjunto de transições aceitas. Os valores possíveis são standard, production, in_store_pickup, pre_order, backorder e collective. Você não escolhe o workflow: ele é definido no momento da criação do pedido, pela natureza do produto (sob encomenda, retirada na loja, pré-venda etc.).

Operações assíncronas. Algumas ações disparam jobs em background e retornam 202 Accepted imediatamente. Isso acontece em três lugares: emissão de Declaração de Conteúdo, registro de NF-e com XML (gera DANFE em background) e geração de etiquetas. Em todos, o padrão é: dispara, faz polling, consome o resultado.

Downloads via S3 assinado. PDFs (DANFE, declaração, etiqueta) não são servidos pela API. Ela devolve uma URL S3 com assinatura, válida por 15 minutos. Se expirar, você chama a rota de download de novo, que gera uma nova URL.

Anatomia de um pedido

Quando você busca um pedido com GET /orders/{id}, recebe um objeto grande. Não precisa entender campo a campo de uma vez — agrupando por função, ele fica simples. A listagem (GET /orders) traz um subconjunto enxuto desses campos; o detalhe traz tudo.

Duas convenções valem para o objeto inteiro:

Campos *_label e *_color já vêm prontos. Todo enum do pedido (status, canal, tipo, workflow, pagamento) chega com o valor cru e o rótulo em pt-BR — e cor, onde faz sentido. Você nunca precisa traduzir esses valores no front: use o _label direto. Os valores possíveis (para popular filtros e badges) vêm da rota /enums.

Campos são condicionais. Vários campos só aparecem no contexto em que fazem sentido — payment_expires_at só quando o pedido aguarda pagamento, pickup_address só em retirada na loja, e assim por diante. Trate a ausência de um campo como "não se aplica a este pedido", não como erro.

Encontrando pedidos

Tem duas formas: listar com filtros (visão operacional) ou olhar números agregados (visão gerencial).

Listagem com filtros

GET/api/v1/sellers/orders

Esta é a rota que o painel do seller chama no dia a dia. Sem filtros, devolve todos os pedidos da loja (paginados, mais novo primeiro).

Quando você está montando uma fila de trabalho, normalmente combina um filtro de status (paid, preparing, shipped...) com um filtro de data (date_from, date_to). Os filtros mais usados:

limit controla a paginação (default 20). A resposta vem em data[] com meta para paginação. Os campos completos do pedido na listagem são um subconjunto enxuto; para o detalhe completo use a rota individual abaixo.

Valores aceitos nos filtros (status, channel, type, workflow, métodos de pagamento…) não precisam ser hardcodados. A rota GET /api/v1/sellers/orders/enums devolve todos os enums do pedido (value + label pt-BR, com color onde faz sentido) num só request — use para popular dropdowns e badges. Para os status agrupados por workflow, há também a rota pública GET /api/global/enums/order/status.

Visão agregada

GET/api/v1/sellers/orders/summary

KPIs fixos do dia atual: quantos pedidos chegaram, receita, ticket médio, contadores por status (preparing, ready_to_ship, shipped, delivered_today) e por canal. Independe dos filtros da listagem: é sempre o panorama global da loja. Use para cabeçalho de dashboard.

GET/api/v1/sellers/orders/dashboard

Estatísticas consolidadas num período configurável (days, default 30): gráfico de evolução diária (vendidos, pendentes, cancelados), totais do período, comparativo com o período anterior de mesma duração, e lista dos pedidos mais recentes. Use para tela de "Visão geral" do seller.

Pedido individual

GET/api/v1/sellers/orders/{id}

Payload completo: itens, cliente, snapshot de endereço, totais, splits financeiros (resumo), fiscais (invoices[]), anotações, metadata de envio (carrier, opção escolhida). É o que a tela de detalhe do pedido consome.

Avançando o pedido

Esta é a parte central. O fluxo correto, sempre, é:

Próximos passos válidos

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

Devolve, para o status atual do pedido, as transições válidas. Cada item de next_actions traz:

• action: slug semântico (ex.: mark-preparing, cancel, start-production).
• target_status: o valor a enviar em status na rota única.
• label: texto pronto para botão/UI.
• payload_schema: JSONSchema do data aceito. null quando a transição não exige payload.

Exemplo (pedido em paid, workflow standard):

{
  "data": {
    "current_status": "paid",
    "workflow_type": "standard",
    "next_actions": [
      {
        "action": "mark-preparing",
        "target_status": "preparing",
        "label": "Iniciar preparação",
        "payload_schema": null
      },
      {
        "action": "cancel",
        "target_status": "cancelled",
        "label": "Cancelar pedido",
        "payload_schema": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "maxLength": 500
            }
          }
        }
      }
    ]
  }
}

Padrão de UI recomendado: renderize um botão por next_action, com label = next_action.label. Quando clicado, monte data a partir do payload_schema (se houver) e chame a rota única.

A rota única de status

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

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

{ "status": "preparing" }

Cenários comuns:

// iniciar preparação (workflow standard)
{
  "status": "preparing"
}

// marcar enviado com rastreio
{
  "status": "shipped",
  "data": {
    "tracking_code": "BR123456789BR"
  }
}

// cancelar com motivo
{
  "status": "cancelled",
  "data": {
    "reason": "Cliente solicitou cancelamento."
  }
}

O que pode dar errado:

Referência rápida: payloads por status

Você normalmente não precisa desta tabela, porque possible-statuses já entrega o payload_schema por transição. Está aqui só para debug rápido.

Cancelamento

Cancelar costuma ser a primeira coisa que as pessoas procuram como rota própria — e ela não existe de propósito. Não há DELETE /orders/{id} nem /cancel: cancelar é uma transição de status como qualquer outra, igual a marcar enviado ou entregue. Você usa a mesma rota de sempre, mandando status: cancelled — mas só enquanto o pedido não entrou em preparação/produção. A partir daí, o cancelamento sai das suas mãos: é a operação da plataforma que cancela. E há estados sem saída nenhuma: delivered, cancelled, completed e payment_expired (já pickup_expired não é terminal — ele ainda transiciona para cancelled).

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

reason é opcional, fica no histórico (GET /orders/{id}/events) e pode aparecer para o cliente. O possible-statuses indica quando essa ação está disponível para o estado atual.

Acompanhando o pedido

Três rotas auxiliares que não mudam estado, só leem dados para telas/relatórios.

Tracking de entrega

GET/api/v1/sellers/orders/{id}/tracking

Visão consolidada de rastreio: status atual, tracking_code, tracking_url pública (se disponível), estimated_delivery_at, delivered_at, picked_up_at. É o "onde está meu pedido", perfeito para uma tela simples de acompanhamento.

Histórico granular (eventos)

GET/api/v1/sellers/orders/{id}/events

Linha do tempo completa do pedido: cada mudança de status, anotação ou ação fiscal vira um evento. Cada evento traz quem fez (author_type, author_name) e contexto (metadata). É o que você quer para uma timeline detalhada ou para auditoria.

Financeiro

GET/api/v1/sellers/orders/{id}/financial

Splits de receita (quem recebe quanto: seller, marketplace, sales agent), audit de comissão por item, e benefícios aplicados (cupons, descontos, regras absorvidas pelo marketplace). Use para tela de "extrato do pedido" ou para conferir o repasse esperado.

Anotações internas

PUT/api/v1/sellers/orders/{id}/notes

notes é texto livre da loja sobre o pedido, não aparece para o cliente. Útil para deixar lembretes ("ligar antes de despachar", "embalagem para presente", "cliente vai retirar quarta"). Envia o texto inteiro a cada chamada (não é append) ou null para limpar.

Outros workflows resumidos

A maior parte dos pedidos é standard, mas a loja pode receber outros tipos. Aqui um resumo; cada um tem peculiaridades que merecem leitura aprofundada.

production: sob encomenda

Pedido que passa pela fábrica antes de embalar: tecido, móveis sob medida, brindes personalizados. Em vez de pular para preparing, o seller informa início, eventual espera por insumos, fabricação e conclusão. Quando a produção termina, o pedido entra no trilho padrão (preparing → ready_to_ship → ...).

→ Detalhe completo em Pedidos: industrialização.

in_store_pickup: retirada na loja

Cliente paga online e vai buscar no balcão. O pedido segue o trilho normal até preparing — é ali que o caminho bifurca, porque delivery_method=pickup: em vez de ready_to_ship, o próximo passo é ready_for_pickup. Quando o cliente aparece, o seller confirma com um código de retirada. Ao confirmar picked_up, o pedido vira delivered automaticamente; não chame delivered em seguida.

pre_order e backorder

Espelhados. Um aguarda o produto chegar ao estoque pela primeira vez (pre_order → available), o outro aguarda reposição (backorder → restocked). Quando o seller libera, o pedido entra no fluxo padrão a partir de paid.

collective: compra coletiva

Pedido vinculado a uma campanha de compra coletiva. Fica em awaiting_campaign_conclusion até a campanha encerrar; o sistema decide automaticamente se o pedido prossegue ou é cancelado. O seller só atua a partir de preparing em diante; não há transições manuais antes disso.

Para onde ir agora