VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Pedidos e conta do cliente

Acompanhar o envio

Etapas, rastreio dos Correios, remessas e sub-pedidos de um pedido.

Depois que o pedido é pago, o cliente quer saber onde ele está. A plataforma tem quatro visões, cada uma para um nível de detalhe: as etapas e a linha do tempo do pedido (tracking), o rastreio dos Correios volume a volume (correios/tracking), as remessas do pedido (fulfillment) e os sub-pedidos de cada seller (sub-orders). Uma loja pode usar só algumas delas, porque três dependem de módulos.

RotaQuando usarMódulo
GET .../trackingBarra de progresso (stepper) e histórico público do pedidoorder-status-flow
GET .../correios/trackingEventos de rastreio de cada volume enviado pelos Correioscorreios-shipping
GET .../fulfillmentCartões de remessa com código de rastreio e transportadorafulfillment
GET .../sub-ordersQuem vai enviar cada parte de um pedido multi-sellernenhum
GET/api/v1/storefront/orders/{id}/trackingCliente

Etapas, transporte e linha do tempo do pedido

Parâmetros de caminho

iduuidobrigatório
Id do pedido. Um texto que não é UUID responde 404 order not found.

Parâmetros de consulta

langstring
Idioma dos rótulos de status (pt-BR, en). Sem ele vale o cabeçalho Accept-Language.
bash
curl "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/tracking?lang=pt-BR" \
  -H "Authorization: Bearer $TOKEN"
200Acompanhamento do pedido
json
{
  "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
  "order_number": "PEDIDO-20261011-0009",
  "purchase_order_number": null,
  "customer_name": "Maria Souza",
  "created_at": "2026-10-11T20:55:25Z",
  "updated_at": "2026-10-12T14:10:00Z",
  "current_status": { "code": "shipped", "letter": "S", "label": "Enviado", "color": "#3b82f6", "stage": "" },
  "steps": [
    { "code": "pending", "letter": "O", "label": "Pendente", "completed_at": "2026-10-11T20:55:25Z", "state": "done" },
    { "code": "processing", "letter": "P", "label": "Processando", "completed_at": "2026-10-12T09:00:00Z", "state": "done" },
    { "code": "shipped", "letter": "S", "label": "Enviado", "completed_at": "2026-10-12T14:10:00Z", "state": "current" },
    { "code": "delivered", "letter": "C", "label": "Entregue", "completed_at": null, "state": "upcoming" }
  ],
  "tracking": {
    "carrier": "Transportadora Exemplo",
    "tracking_code": "AB123456789BR",
    "tracking_url": "https://rastreio.example.com/AB123456789BR",
    "estimated_delivery_at": "2026-10-20T00:00:00Z"
  },
  "shipments": [
    {
      "id": "7c0f3a52-5b6e-4a41-8f3c-2d1b9a0e4c11",
      "carrier": "Transportadora Exemplo",
      "tracking_code": "AB123456789BR",
      "tracking_url": "https://rastreio.example.com/AB123456789BR",
      "estimated_delivery_at": "2026-10-20T00:00:00Z",
      "public_note": null,
      "shipped_at": "2026-10-12T14:10:00Z",
      "created_at": "2026-10-12T14:09:00Z",
      "updated_at": "2026-10-12T14:10:00Z"
    }
  ],
  "timeline": [
    { "type": "status_change", "at": "2026-10-12T14:10:00Z", "status": { "code": "shipped", "letter": "S", "label": "Enviado" }, "origin": "vendor" }
  ]
}

Campos da resposta

current_statusobject
Status atual: code, letter, label (já no idioma pedido), color e stage.
stepsarray
Etapas do stepper, em ordem. state é done, current ou upcoming. completed_at é a primeira vez que o pedido chegou à etapa e é null nas futuras (e numa etapa que foi pulada).
trackingobject
Dados de transporte do pedido: carrier, tracking_code, tracking_url e estimated_delivery_at. Todos podem ser null: um pedido pode ser despachado sem nenhum deles.
shipmentsarray
Uma entrada por remessa, com os mesmos campos de tracking mais id, public_note (recado da loja ao cliente), shipped_at, created_at e updated_at.
timelinearray
Linha do tempo pública, do ponto de vista do cliente: type, at, status, origin (admin, vendor, customer ou system), public_note e, em evento de remessa, shipment_id e tracking. Nomes de quem mudou o status não aparecem para o cliente.
purchase_order_numberstring
Número da ordem de compra do cliente, quando o pedido veio de uma (B2B). customer_company e customer_cnpj completam o bloco do comprador.

Erros

StatusQuandoCorpo
401Sem token, ou token inválido ou expirado{"error":"missing authorization header"} / {"error":"invalid or expired token"}
403Módulo order-status-flow desligado na loja{"error":"module_disabled","module":"order-status-flow"}
404O id não existe ou o pedido não é seu (a API nunca diz qual dos dois){"error":"order not found"}
500Falha ao montar o acompanhamento{"error":"failed to load order tracking","detail":"..."}
GET/api/v1/storefront/orders/{id}/correios/trackingCliente

Rastreio dos Correios, volume a volume

Para lojas que enviam pelos Correios, devolve cada volume (pacote) do pedido com os eventos de rastreio (Objeto postado, Em trânsito, Entregue...). Se o pedido foi dividido entre sellers, vem um bloco por pedido. A rota só lê dados já sincronizados: ela não consulta os Correios na hora. Só aceita usuários do tipo cliente.

Parâmetros de caminho

iduuidobrigatório
Id do pedido.

Parâmetros de consulta

langstring
Idioma dos rótulos. Sem ele vale Accept-Language.
bash
curl "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/correios/tracking" \
  -H "Authorization: Bearer $TOKEN"
200Rastreio por volume
json
{
  "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
  "order_number": "PEDIDO-20261011-0009",
  "summary_scope": "order",
  "current_status": { "code": "shipped", "letter": "S", "label": "Enviado" },
  "summary": { "state": "in_transit", "total_volumes": 1, "delivered_volumes": 0, "returned_volumes": 0, "canceled_volumes": 0 },
  "orders": [
    {
      "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
      "order_number": "PEDIDO-20261011-0009",
      "vendor_name": "Loja Exemplo",
      "current_status": { "code": "shipped", "letter": "S", "label": "Enviado" },
      "summary": { "state": "in_transit", "total_volumes": 1, "delivered_volumes": 0, "returned_volumes": 0, "canceled_volumes": 0 },
      "volumes": [
        {
          "id": "f2a1c4e8-1d3b-4f7a-9c0e-5b8d2a6e7f10",
          "package_index": 1,
          "service_code": "03298",
          "state": "in_transit",
          "current_posting": {
            "id": "b1e7d9a3-6c2f-4e58-a0d4-3f9c8b7a1e22",
            "kind": "forward",
            "revision": 1,
            "tracking_code": "AB123456789BR",
            "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objeto=AB123456789BR",
            "state": "in_transit",
            "is_current": true,
            "is_trackable": true,
            "shipped_at": "2026-10-12T14:10:00Z",
            "events": [
              { "event_type": "in_transit", "description": "Objeto em trânsito", "location": "São Paulo, SP", "occurred_at": "2026-10-13T08:20:00Z" }
            ]
          },
          "history": []
        }
      ]
    }
  ]
}

Campos da resposta

summaryobject
Resumo agregado: state (por exemplo in_transit, delivered, not_applicable) e as contagens total_volumes, delivered_volumes, returned_volumes, canceled_volumes. summary_scope diz se o resumo cobre order inteiro ou só a parte do seller.
ordersarray
Um item por pedido (o pai e/ou cada sub-pedido), com vendor_id, vendor_name, current_status, summary e volumes.
orders[].volumes[]object
Um pacote: package_index, service_code (serviço dos Correios), state, current_posting (a postagem em vigor) e history (postagens anteriores, quando houve reenvio).
current_posting.events[]object
Evento de rastreio: event_type, description, location e occurred_at (RFC 3339). raw_code e raw_type trazem o código original do transportador, quando existem.
StatusQuandoCorpo
401Sem token, ou token inválido ou expirado{"error":"missing authorization header"} / {"error":"invalid or expired token"}
403Usuário que não é cliente (por exemplo token de aplicativo){"error":"customer_required"}
403Módulo correios-shipping desligado na loja{"error":"module_disabled","module":"correios-shipping"}
404O id não existe ou o pedido não é seu (a API nunca diz qual dos dois){"error":"order not found"}
500Falha ao ler o rastreio{"error":"order_tracking_unavailable"}
GET/api/v1/storefront/orders/{id}/fulfillmentCliente

Remessas (fulfillment) do pedido

Lista as remessas do pedido: quem separa e envia (vendor ou marketplace), em que etapa está (pending, picking, packed, shipped, delivered ou returned) e o código de rastreio. Une as remessas criadas pela tela de fulfillment da loja e as criadas pelo botão "Criar envio" do pedido, então a lista é completa mesmo que a loja use só um dos dois caminhos.

Parâmetros de caminho

iduuidobrigatório
Id do pedido. Aqui vale só o dono direto (customer_id).
bash
curl "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/fulfillment" \
  -H "Authorization: Bearer $TOKEN"
200Remessas do pedido
json
{
  "fulfillments": [
    {
      "id": "42f4e4b1-5d78-4ce5-bf0e-355f927168ef",
      "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
      "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "vendor_name": "Loja Exemplo",
      "fulfilled_by": "vendor",
      "status": "shipped",
      "tracking_number": "AB123456789BR",
      "tracking_url": "https://rastreio.example.com/AB123456789BR",
      "carrier": "Transportadora Exemplo",
      "shipped_at": "2026-10-12T14:10:00Z",
      "is_partial": false,
      "created_at": "2026-10-11T20:55:25Z",
      "updated_at": "2026-10-12T14:10:00Z"
    }
  ]
}

Campos da resposta

fulfillmentsarray

Remessas. Pode vir null quando não há nenhuma.

fulfilled_bystring
vendormarketplace
Quem separa e envia: vendor (o seller) ou marketplace (a loja).
statusstring
pendingpickingpackedshippeddeliveredreturned
Etapa da remessa.
tracking_numberstring
Código de rastreio, quando já existe. tracking_url e carrier completam.
picked_atstring
Marcas de tempo de cada etapa (picked_at, packed_at, shipped_at, delivered_at, returned_at), RFC 3339, presentes só quando a etapa ocorreu.
is_partialboolean
true quando a remessa cobre só parte dos itens; items lista quais.
fee_totalinteger
Tarifas de fulfillment da loja em centavos (fee_count linhas em fees). Informação da loja, não é cobrada do cliente.
StatusQuandoCorpo
401Sem token, ou token inválido ou expirado{"error":"missing authorization header"} / {"error":"invalid or expired token"}
403Módulo fulfillment desligado na loja{"error":"module_disabled","module":"fulfillment"}
404O id não existe ou o pedido não é seu (a API nunca diz qual dos dois){"error":"order not found"}
500Falha ao ler as remessas{"error":"failed to get fulfillment","detail":"..."}
GET/api/v1/storefront/orders/{id}/sub-ordersCliente

Sub-pedidos de um pedido multi-seller

Quando a compra mistura produtos de mais de um seller, cada seller separa e envia a sua parte. Esta rota lista essas partes (os sub-pedidos) com o seller, o status, os totais e o código de rastreio de cada uma. Num pedido de um seller só, a lista vem vazia (count: 0).

Parâmetros de caminho

iduuidobrigatório
Id do pedido pai.
bash
curl "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/sub-orders" \
  -H "Authorization: Bearer $TOKEN"
200Sub-pedidos
json
{
  "parent_order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
  "count": 1,
  "sub_orders": [
    {
      "id": "9a3e5b71-2d4c-4f08-b6a1-7c0d8e2f3a45",
      "order_number": "PEDIDO-20261011-0009-V1",
      "parent_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
      "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "vendor_name": "Loja Exemplo",
      "vendor_slug": "loja-exemplo",
      "customer_id": "264a70c1-9c69-458d-ac73-838543f87da2",
      "status": "S",
      "subtotal": 4990,
      "shipping_total": 1000,
      "tax_total": 0,
      "discount_total": 724,
      "total": 5266,
      "currency": "BRL",
      "payment_method": "pix",
      "payment_status": "captured",
      "sub_order_index": 1,
      "shipping_method_name": "Entrega Padrão",
      "min_delivery_days": 10,
      "max_delivery_days": 10,
      "tracking_number": "AB123456789BR",
      "shipped_at": "2026-10-12T14:10:00Z",
      "item_count": 1,
      "created_at": "2026-10-11T20:55:25Z",
      "updated_at": "2026-10-12T14:10:00Z"
    }
  ]
}

Campos da resposta

parent_order_iduuid
O pedido pai que você consultou.
countinteger
Quantidade de sub-pedidos.
sub_ordersarray
Cada sub-pedido, com valores em centavos. status é a letra do status daquela parte; ela evolui por conta do seller. sub_order_index é a posição (1, 2...) e o número termina em -V1, -V2. shipped_at e delivered_at aparecem quando ocorreram.
StatusQuandoCorpo
401Sem token, ou token inválido ou expirado{"error":"missing authorization header"} / {"error":"invalid or expired token"}
404O id não existe ou o pedido não é seu (a API nunca diz qual dos dois){"error":"order not found"}
500Falha ao ler os sub-pedidos{"error":"failed to get sub-orders","detail":"..."}
Qual rota para qual tela

Tela de detalhe do pedido: tracking (stepper) quando o módulo está ligado; senão use status/status_history de Consultar pedido. Tela "onde está meu pacote": correios/tracking para Correios, fulfillment para as demais transportadoras. Pedido com vários sellers: abra sub-orders e, para cada um, o rastreio.

Veja também

  • Consultar pedido
  • Status de pedido
  • Devoluções e contestações
  • Sub-pedidos (administração)
Anterior
Nota fiscal (NF-e)
Próxima
Retomar pagamento
Nesta página
  • Erros
  • Veja também