VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Guia rápido/Pedidos

Rastreio da transportadora

Consulta o acompanhamento do pedido para o cliente, os eventos reais da transportadora e as transportadoras disponíveis.

Depois que o pedido foi enviado, três perguntas aparecem no atendimento: "onde está meu pedido?", "quais pedidos deste cliente estão a caminho?" e "quais transportadoras posso escolher?". As rotas desta página respondem a cada uma:

  • Eventos da transportadora de um pedido (/orders/{id}/tracking-events): a linha do tempo real do pacote (postado, em trânsito, saiu para entrega...), alimentada pela própria transportadora.
  • Acompanhamento do pedido (/order-tracking): a visão que o cliente enxerga (etapas, status atual, remessas, previsão e observações públicas), por pedido ou por CNPJ de comprador/seller.
  • Transportadoras (/shipment-carriers): a lista das transportadoras ativas da loja, para escolher na criação de uma remessa.
Duas destas rotas dependem de um recurso da loja

/order-tracking, /order-tracking/{id} e /shipment-carriers pertencem ao recurso opcional de acompanhamento de pedidos (fluxo de status). Quando a loja não o ativou, respondem 403 {"error":"module_disabled","module":"order-status-flow"}. A rota /orders/{id}/tracking-events não depende dele.

GET/api/v1/admin/orders/{id}/tracking-eventsAdmin

Eventos de rastreio da transportadora de um pedido

Devolve o último estado conhecido do rastreio do pedido: transportadora, código, os eventos recebidos e os itens. Se o pedido ainda não tem remessa com código, events vem vazio e found continua true. Exige acesso a envios: o privilégio view_shipping ou manage_shipping.

Path parameters

iduuidobrigatório
Id do pedido.
GET/api/v1/admin/order-trackingAdmin

Rastreio dos pedidos de um seller ou cliente (por CNPJ)

Lista o acompanhamento dos pedidos de um seller ou de um comprador, identificado pelo CNPJ. É a rota para um sistema externo perguntar "como estão os pedidos desta empresa". Cada consulta fica registrada no log de atividades. Exige view_orders ou manage_orders, e o recurso de acompanhamento ativo.

Query parameters

party_typestringobrigatório
sellercustomer
De quem são os pedidos: do seller (quem vende) ou do comprador (quem compra). Para customer, devolve só o pedido que o comprador vê (o pai, nunca os filhos).
cnpjstringobrigatório
CNPJ da parte, com ou sem pontuação. Precisa ser um CNPJ válido (dígitos verificadores).
order_iduuid
Restringe a um pedido.
order_numberstring
Restringe ao número do pedido.
statusstring
Restringe a um status (código ou letra do cadastro da loja).
date_fromstring
Data inicial, AAAA-MM-DD ou RFC 3339.
date_tostring
Data final, AAAA-MM-DD ou RFC 3339.
pageintegerpadrão: 1
Página.
per_pageintegerpadrão: 20
Itens por página, no máximo 100.
langstring
Idioma dos rótulos de status (pt-BR, en). Se omitido, usa o cabeçalho Accept-Language.
GET/api/v1/admin/order-tracking/{id}Admin

Rastreio de um pedido

Acompanhamento de um pedido, com as etapas, o status atual, as remessas e a linha do tempo. Por padrão mostra o que o cliente vê; com audience=vendor, o que o seller vê.

Path parameters

iduuidobrigatório
Id do pedido.

Query parameters

audiencestringpadrão: customer
customervendor
Qual visão devolver.
langstring
Idioma dos rótulos.
GET/api/v1/admin/shipment-carriersAdmin

Transportadoras disponíveis para criar uma remessa

Lista as transportadoras ativas da loja (cadastro de Logística, Transportadoras). Serve para preencher o campo carrier ao criar uma remessa. Exige view_orders ou manage_orders.

Exemplo de requisição

Resposta

200Eventos da transportadora
200Acompanhamento de um pedido
200Transportadoras

Campos da resposta (tracking-events)

foundboolean
true quando o pedido existe. Um pedido sem remessa devolve true com events vazio.
order_numberstring
Número do pedido.
carrierstring
Transportadora da remessa. Vazio se ainda não há.
tracking_codestring
Código de rastreio. Vazio se ainda não há.
recipient_first_namestring
Primeiro nome de quem recebe.
eventsarray
Eventos recebidos da transportadora, cada um com event_type, description, location e occurred_at (RFC 3339).
itemsarray
Itens do pedido (product_name, product_image, quantity), sem preços.
destination_citystring
Cidade de entrega.
destination_statestring
UF de entrega.

Campos da resposta (order-tracking)

itemsarray
(Lista) Um acompanhamento por pedido, no formato abaixo. Acompanha total, page, per_page e party (type, cnpj).
order_iduuid
Pedido.
purchase_order_numberstring
Número da ordem de compra do cliente, quando o pedido nasceu de uma.
customer_namestring
Nome do comprador.
customer_companystring
Empresa do comprador.
customer_cnpjstring
CNPJ do comprador.
current_statusobject
Status atual: code, letter, label (no idioma pedido), color e stage.
stepsarray
Etapas do pedido, em ordem. state é done, current ou upcoming; completed_at é a primeira vez que o pedido chegou à etapa (nulo se não chegou ou se a etapa foi pulada).
trackingobject
Dados de transporte do pedido: carrier, tracking_code, tracking_url, estimated_delivery_at. Todos podem ser nulos.
shipmentsarray
Remessas com seus dados de rastreio e public_note.
timelinearray
Eventos públicos. type é order_created, status_changed, shipment_created ou tracking_updated. origin (admin, vendor, customer, system) diz quem fez a mudança. O nome da pessoa (actor) só aparece para usuários do painel, nunca para integração por token de app.

Erros

StatusQuandoCorpo
401Sem credenciais ou token expirado{"error":"invalid or expired token"}
403Sem permissão; ou recurso de acompanhamento desligado{"error":"insufficient privileges", ...} ou {"error":"module_disabled","module":"order-status-flow"}
404Pedido inexistente{"error":"order_not_found"} (tracking-events) ou {"error":"order not found"} (order-tracking)
422Consulta inválida em order-tracking{"error":"validation_failed","issues":[{"field":"party_type","code":"required"},{"field":"cnpj","code":"invalid"}]}
500Falha interna{"error":"tracking_failed","detail":"..."}
Eventos da transportadora dependem do código de rastreio

tracking-events só tem o que contar depois que a remessa recebe um código de rastreio e a transportadora devolve eventos. Grave o código na remessa logo que despachar; sem ele o pedido fica sem eventos.

Veja também

  • Remessas e rastreio
  • Histórico do pedido
  • Fluxo de status personalizado
Anterior
Remessas e rastreio
Próxima
Reembolsos
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
# Eventos reais da transportadora
curl "$BASE_URL/api/v1/admin/orders/$ORDER_ID/tracking-events" \
  -H "Authorization: Bearer $TOKEN"

# Pedidos de um comprador, por CNPJ
curl "$BASE_URL/api/v1/admin/order-tracking?party_type=customer&cnpj=11222333000181&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

# Acompanhamento de um pedido (visão do seller)
curl "$BASE_URL/api/v1/admin/order-tracking/$ORDER_ID?audience=vendor" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "found": true,
  "order_number": "PEDIDO-20261011-0001-V1",
  "carrier": "Correios",
  "tracking_code": "BR123456789BR",
  "recipient_first_name": "Maria",
  "events": [
    {
      "event_type": "in_transit",
      "description": "Objeto em trânsito, por favor aguarde",
      "location": "São Paulo, SP",
      "occurred_at": "2026-10-12T09:41:00Z"
    }
  ],
  "items": [
    { "product_name": "Notebook Vintage Vermelho", "product_image": "/uploads/produto.png", "quantity": 1 }
  ],
  "destination_city": "São Paulo",
  "destination_state": "SP"
}
json
{
  "order_id": "2b4bd680-b717-4295-a2be-8b5c6771a4d0",
  "order_number": "PEDIDO-20261011-0001-V1",
  "purchase_order_number": null,
  "customer_name": "Maria Souza",
  "customer_company": "Souza Comércio Ltda",
  "customer_cnpj": "11222333000181",
  "created_at": "2026-10-11T20:14:40Z",
  "updated_at": "2026-10-11T20:16:39Z",
  "current_status": { "code": "shipped", "letter": "S", "label": "Enviado", "color": "#8b5cf6", "stage": "main" },
  "steps": [
    { "code": "pending", "letter": "O", "label": "Pendente", "completed_at": "2026-10-11T20:14:40Z", "state": "done" },
    { "code": "processing", "letter": "P", "label": "Processando", "completed_at": "2026-10-11T20:16:33Z", "state": "done" },
    { "code": "shipped", "letter": "S", "label": "Enviado", "completed_at": "2026-10-11T20:16:39Z", "state": "current" },
    { "code": "delivered", "letter": "C", "label": "Entregue", "completed_at": null, "state": "upcoming" }
  ],
  "tracking": {
    "carrier": "Correios",
    "tracking_code": "BR123456789BR",
    "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objeto=BR123456789BR",
    "estimated_delivery_at": "2026-10-20T03:00:00Z"
  },
  "shipments": [
    {
      "id": "45171534-2fbd-46ca-973a-132149a564da",
      "carrier": "Correios",
      "tracking_code": "BR123456789BR",
      "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objeto=BR123456789BR",
      "estimated_delivery_at": "2026-10-20T03:00:00Z",
      "public_note": "Saiu do centro de distribuição",
      "shipped_at": "2026-10-11T20:16:39Z",
      "created_at": "2026-10-11T20:16:39Z",
      "updated_at": "2026-10-11T21:02:10Z"
    }
  ],
  "timeline": [
    { "type": "order_created", "at": "2026-10-11T20:14:40Z" },
    { "type": "status_changed", "at": "2026-10-11T20:16:33Z", "status": { "code": "processing", "letter": "P", "label": "Processando" }, "origin": "admin" },
    { "type": "shipment_created", "at": "2026-10-11T20:16:39Z", "shipment_id": "45171534-2fbd-46ca-973a-132149a564da" },
    { "type": "tracking_updated", "at": "2026-10-11T21:02:10Z", "public_note": "Saiu do centro de distribuição", "shipment_id": "45171534-2fbd-46ca-973a-132149a564da" }
  ]
}
json
{
  "carriers": [
    {
      "id": "dcd17e6e-f428-4c84-bdb9-14800393ed51",
      "name": "Correios SEDEX",
      "code": "correios_sedex",
      "tracking_url_template": "https://rastreamento.correios.com.br/app/index.php?objetos={tracking}",
      "logo_url": "/carriers/correios.svg",
      "is_active": true,
      "position": 2
    }
  ],
  "total": 1
}