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

Acompanhamento do pedido

Mostra ao seller o acompanhamento dos pedidos dele, com as etapas, o status atual, as remessas e a linha do tempo que o cliente vê.

O acompanhamento (order tracking) é a visão do pedido como o cliente a enxerga: etapas concluídas, status atual, remessas com rastreio e previsão, e os avisos públicos. O seller usa estas rotas para conferir o que o cliente está vendo e para responder "onde está meu pedido?". Elas são somente leitura; os dados mudam quando o seller muda o status ou atualiza o rastreio.

Depende de um recurso da loja

As duas rotas pertencem ao módulo opcional order-status-flow (fluxo de status e acompanhamento de pedidos). Quando a loja não o ligou, respondem 403 com {"error":"module_disabled","module":"order-status-flow"}.

Listar o acompanhamento

GET/api/v1/vendor/order-trackingSeller

Lista o acompanhamento dos pedidos do seller

Devolve o acompanhamento dos pedidos do seller. Diferente da consulta do administrador, não exige party_type: o seller já é identificado pelo token, e o CNPJ do cliente é um filtro opcional. Exige um privilégio de pedidos do seller.

Parâmetros de consulta

cnpjstring
CNPJ do cliente comprador, com ou sem pontuação, para filtrar os pedidos de uma empresa. Precisa ser 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.

Exemplo de requisição: listar

bash
curl "$BASE_URL/api/v1/vendor/order-tracking?status=shipped&per_page=20&lang=pt-BR" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Acompanhamento dos pedidos
json
{
  "items": [
    {
      "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
      "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": "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": [],
      "timeline": [
        { "type": "order_created", "at": "2026-10-11T20:14:40Z" }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Campos da resposta

itemsarray
Um acompanhamento por pedido, no formato descrito mais abaixo.
totalinteger
Total de pedidos que casam com o filtro.
pageinteger
Página devolvida.
per_pageinteger
Tamanho da página aplicado.

Acompanhamento de um pedido

GET/api/v1/vendor/order-tracking/{id}Seller

Acompanhamento de um pedido do seller

Acompanhamento de um pedido do seller, com a visão do seller (que inclui o nome de quem mudou cada status). Exige um privilégio de pedidos do seller e respeita a carteira do representante.

Parâmetros de caminho

iduuidobrigatório
Id do sub-pedido do seller.

Parâmetros de consulta

langstring
Idioma dos rótulos de status (pt-BR, en). Se omitido, usa o cabeçalho Accept-Language.

Resposta: detalhar

200Acompanhamento de um pedido
json
{
  "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
  "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-11T21:02:10Z",
  "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": "vendor", "actor": { "name": "Ana Lima" } },
    { "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" }
  ]
}

Campos da resposta (cada acompanhamento)

order_iduuid
Pedido.
order_numberstring
Número do pedido.
purchase_order_numberstring | null
Número da ordem de compra do cliente, quando o pedido nasceu de uma.
customer_namestring
Nome do comprador.
customer_companystring | null
Empresa do comprador.
customer_cnpjstring | null
CNPJ do comprador, só números.
created_atstring (RFC 3339)
Criação do pedido.
updated_atstring (RFC 3339)
Última alteração.
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. Na visão do seller, as mudanças de status feitas pela loja ou pelo seller trazem actor.name, o nome da pessoa.

Erros

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"missing authorization header"}
403O token não é de um usuário seller, ou ele não tem privilégio de pedidos.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_view_orders", "..."]}
403O módulo de acompanhamento está desligado na loja.{"error":"module_disabled","module":"order-status-flow"}
403No detalhe: o pedido é de outro seller, é o pai, ou está fora da carteira do representante.{"error":"you do not have access to this order"}
404No detalhe: o pedido não existe.{"error":"order not found"}
422Consulta inválida na lista. field é cnpj, order_id, date_from ou date_to; code é invalid.{"error":"validation_failed","issues":[{"field":"cnpj","code":"invalid"}]}
500Falha interna. Um id que não é UUID no detalhe também chega como 500.{"error":"failed to load order tracking","detail":"..."}
Rótulos no idioma do cliente

Use lang para pedir os rótulos de status em pt-BR ou en. Sem ele, vale o Accept-Language da requisição.

Quem mudou o status só aparece no painel

O nome em actor vai apenas para usuários do painel (administrador e seller). A loja do cliente e as integrações por token de app recebem só a origem (origin).

Veja também

  • Remessas e rastreio
  • Mudar o status do pedido
  • Visão geral
Anterior
Remessas e rastreio
Próxima
Cancelamentos pedidos pelo cliente
Nesta página
  • Listar o acompanhamento
  • Exemplo de requisição: listar
  • Resposta: listar
  • Acompanhamento de um pedido
  • Resposta: detalhar
  • Erros
  • Veja também