Visão geral

Este guia é a visão geral de como sua loja lida com pedidos pela API: ler os dados de um pedido, encontrar e filtrar pedidos, avançar o ciclo de vida pela rota única de status e acompanhar cada etapa (rastreio, histórico, financeiro).

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

• Industrialização, para o workflow production.
• Compra coletiva, para o workflow collective.
• 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
  "sold_by": {…},                    // ← loja que vendeu (+ is_substore) — ver Pedidos de sublojas
  "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:11-03:00",
  "updated_at": "2026-04-26T14:35:42-03:00"
}

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.
• Compra coletiva: pedido represado até a campanha encerrar.

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 individual 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. 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.

Para agir sobre vários pedidos de uma vez existe POST /orders/bulk/transition, com uma allow-list de 10 ações e limite de 200 pedidos por chamada.

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. Trate a ausência de um campo como "não se aplica a este pedido", não como erro.

Precisão de preço: price_scale

Cada item de items[] carrega um price_scale (2 ou 3), que diz com quantas casas decimais o preço unitário daquele item foi vendido.

Ele é um snapshot: é gravado no momento em que o item entra no carrinho e herdado pelo pedido, e não é recalculado depois. Se o SKU mudar de configuração (passar de 3 casas para 2, por exemplo), os pedidos antigos continuam preservando a precisão com que foram vendidos.

Duas regras fecham o desenho:

• Preço unitário: pode ter 3 casas, conforme o price_scale do item.
• Subtotal da linha e todos os totais do pedido (totals.products, totals.shipping, totals.discounts, totals.order): sempre 2 casas, arredondados para cima.

Formate o preço unitário usando o price_scaledo próprio item, nunca a configuração atual do produto. Ler a configuração do SKU em vez do snapshot faz um pedido antigo aparecer com precisão diferente da que foi cobrada do cliente.

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, 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: rótulo do status alvo em pt-BR ("Preparando", "Cancelado"). Não é frase de ação pronta.
• 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": "Preparando",
        "payload_schema": null
      },
      {
        "action": "cancel",
        "target_status": "cancelled",
        "label": "Cancelado",
        "payload_schema": {
          "type": "object",
          "required": ["reason"],
          "properties": {
            "reason": {
              "type": "string",
              "minLength": 10,
              "maxLength": 500
            }
          }
        }
      }
    ]
  }
}

label é o rótulo do status alvo em pt-BR ("Preparando", "Cancelado"), não uma frase de ação pronta como "Iniciar preparação". Monte o texto do botão combinando action com seu próprio dicionário de UI, se quiser algo mais natural.

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 (obrigatório, mínimo 10 caracteres)
{
  "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

Não existe rota própria de cancelamento. 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 é obrigatório (mínimo 10 caracteres), 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, delivered_at, picked_up_at (em retiradas) e o array shipments[], com o rastreio de cada envio (tracking_code, tracking_url, estimated_delivery_at, passos). É o "onde está meu pedido", perfeito para uma tela simples de acompanhamento.

Os campos tracking_code, tracking_url e estimated_delivery_at no nível do pedido (fora de shipments[]) sempre vêm null: não há rastreio consolidado no próprio pedido. Use os campos equivalentes dentro de cada item de shipments[].

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 represado em awaiting_campaign_conclusion até a campanha encerrar; quando isso acontece, um job agendado libera o pedido sempre para preparing (não existe cancelamento automático por meta não atingida). O seller também pode intervir manualmente antes do fim da campanha, liberando cedo ou cancelando.

→ Detalhe completo em Pedidos: compra coletiva.

Para onde ir agora