API legada/Referência completa/Pedidos: rotas sem versão e app do seller

Rastreio por token de app

Consulta o acompanhamento dos pedidos de um seller ou comprador por CNPJ, o acompanhamento de um pedido e o resumo de rastreio, com token de app.

Um sistema externo (um portal de cliente, um WMS, uma ferramenta de logística) muitas vezes só precisa saber em que ponto está um pedido. Estas três rotas deixam esse sistema consultar o rastreio sem ter um usuário administrador: ele usa um token de app (começa com vat_live_ ou vat_test_), emitido no portal de desenvolvedores da loja, com o escopo read_orders. A visão é a mesma que a loja mostra ao cliente, sem o nome de quem mudou o status. O conceito de token de app está em Pedidos por token de app.

GET/api/admin/order-trackingAutenticada

Acompanhamento dos pedidos de um seller ou comprador, por CNPJ (token de app)

Lista o acompanhamento dos pedidos de um seller ou de um comprador, identificado pelo CNPJ. Cada consulta fica registrada no log de atividades, com a origem app_token.

Parâmetros de consulta

party_typestringobrigatório

sellercustomer

De quem são os pedidos. 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/admin/order-tracking/{id}Autenticada

Acompanhamento de um pedido (token de app)

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ê. O nome de quem mudou o status (actor) não aparece para token de app; só a origem (origin).

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Parâmetros de consulta

audiencestringpadrão: customer

customervendor

Qual visão devolver.

langstring

Idioma dos rótulos.

GET/api/admin/orders/{id}/trackingAutenticada

Resumo plano do rastreio de um pedido (token de app)

Resumo do rastreio da primeira remessa do pedido: código, transportadora, status da remessa e link de rastreio. Não depende do recurso de acompanhamento. Se o pedido não tem remessa, responde 404.

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Exemplo de requisição

bash

curl "$BASE_URL/api/admin/order-tracking?party_type=customer&cnpj=11222333000181&per_page=20" \
  -H "Authorization: Bearer $APP_TOKEN"

curl "$BASE_URL/api/admin/order-tracking/$ORDER_ID?audience=customer" \
  -H "Authorization: Bearer $APP_TOKEN"

curl "$BASE_URL/api/admin/orders/$ORDER_ID/tracking" \
  -H "Authorization: Bearer $APP_TOKEN"

Resposta

200Lista de acompanhamentos

json

{
  "items": [
    {
      "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",
      "current_status": { "code": "shipped", "letter": "S", "label": "Enviado", "color": "#8b5cf6", "stage": "main" },
      "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"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "party": { "type": "customer", "cnpj": "11222333000181" }
}

200Acompanhamento de um pedido (resumo)

json

{
  "order_id": "2b4bd680-b717-4295-a2be-8b5c6771a4d0",
  "order_number": "PEDIDO-20261011-0001-V1",
  "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" }
  ],
  "timeline": [
    { "type": "order_created", "at": "2026-10-11T20:14:40Z" },
    { "type": "status_changed", "at": "2026-10-11T20:16:39Z", "status": { "code": "shipped", "letter": "S", "label": "Enviado" }, "origin": "admin" }
  ]
}

200Resumo de rastreio

json

{
  "tracking_code": "BR123456789BR",
  "carrier": "Correios",
  "status": "shipped",
  "url": "https://rastreamento.correios.com.br/app/index.php?objeto=BR123456789BR"
}

Campos da resposta

itemsarray

(Lista) Um acompanhamento por pedido, com os campos do detalhe. Acompanha total, page, per_page e party (type, cnpj).

order_iduuid

Pedido.

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 foi pulada).

trackingobject

Dados de transporte: carrier, tracking_code, tracking_url, estimated_delivery_at. Todos podem ser nulos.

shipmentsarray

(Detalhe) Remessas com 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, sem o nome da pessoa.

tracking_codestring

(Resumo) Código de rastreio da primeira remessa. Vazio se ainda não foi informado.

carrierstring

(Resumo) Transportadora da primeira remessa. Vazio se ainda não há.

statusstring

(Resumo) Status da remessa.

urlstring

(Resumo) Link de rastreio na transportadora. Vazio para transportadora desconhecida ou sem código.

Os campos completos de items[] e do detalhe (purchase_order_number, customer_name, customer_company, shipments[] e outros) estão em Rastreio da transportadora.

Erros

Status	Quando	Corpo
400	`{id}` igual a `0` ou negativo no caminho	`{"error":"invalid id parameter"}`
401	Sem token, ou com um JWT de usuário	`{"error":"app_token_required"}`
401	Token de app inválido, expirado ou revogado	`{"error":"invalid or expired app access token"}`
429	O token excedeu o limite de chamadas	`{"error":"rate_limit_exceeded"}`
403	Token sem o escopo `read_orders`	`{"error":"missing_scope","required":"read_orders"}`
403	Recurso de acompanhamento desligado na loja (`order-tracking`)	`{"error":"module_disabled","module":"order-status-flow"}`
404	Pedido inexistente (`order-tracking/{id}`)	`{"error":"order not found"}`
404	Pedido sem remessa (`orders/{id}/tracking`)	`{"error":"no shipments for this order"}`
422	Consulta inválida em `order-tracking`	`{"error":"validation_failed","issues":[{"field":"party_type","code":"required"},{"field":"cnpj","code":"invalid"}]}`
422	`{id}` de `order-tracking/{id}` que não é UUID	`{"error":"validation_failed","issues":[{"field":"id","code":"invalid"}]}`
500	Falha interna, ou `{id}` que não é UUID em `orders/{id}/tracking`	`{"error":"failed to fetch shipments"}`

Veja também

Rastreio por token de app

Consulta o acompanhamento dos pedidos de um seller ou comprador por CNPJ, o acompanhamento de um pedido e o resumo de rastreio, com token de app.

GET/api/admin/order-trackingAutenticada

Acompanhamento dos pedidos de um seller ou comprador, por CNPJ (token de app)

Lista o acompanhamento dos pedidos de um seller ou de um comprador, identificado pelo CNPJ. Cada consulta fica registrada no log de atividades, com a origem app_token.

Parâmetros de consulta

party_typestringobrigatório

sellercustomer

De quem são os pedidos. 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/admin/order-tracking/{id}Autenticada

Acompanhamento de um pedido (token de app)

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Parâmetros de consulta

audiencestringpadrão: customer

customervendor

Qual visão devolver.

langstring

Idioma dos rótulos.

GET/api/admin/orders/{id}/trackingAutenticada

Resumo plano do rastreio de um pedido (token de app)

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Exemplo de requisição

bash

curl "$BASE_URL/api/admin/order-tracking?party_type=customer&cnpj=11222333000181&per_page=20" \
  -H "Authorization: Bearer $APP_TOKEN"

curl "$BASE_URL/api/admin/order-tracking/$ORDER_ID?audience=customer" \
  -H "Authorization: Bearer $APP_TOKEN"

curl "$BASE_URL/api/admin/orders/$ORDER_ID/tracking" \
  -H "Authorization: Bearer $APP_TOKEN"

Resposta

200Lista de acompanhamentos

json

{
  "items": [
    {
      "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",
      "current_status": { "code": "shipped", "letter": "S", "label": "Enviado", "color": "#8b5cf6", "stage": "main" },
      "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"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "party": { "type": "customer", "cnpj": "11222333000181" }
}

200Acompanhamento de um pedido (resumo)

json

{
  "order_id": "2b4bd680-b717-4295-a2be-8b5c6771a4d0",
  "order_number": "PEDIDO-20261011-0001-V1",
  "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" }
  ],
  "timeline": [
    { "type": "order_created", "at": "2026-10-11T20:14:40Z" },
    { "type": "status_changed", "at": "2026-10-11T20:16:39Z", "status": { "code": "shipped", "letter": "S", "label": "Enviado" }, "origin": "admin" }
  ]
}

200Resumo de rastreio

json

{
  "tracking_code": "BR123456789BR",
  "carrier": "Correios",
  "status": "shipped",
  "url": "https://rastreamento.correios.com.br/app/index.php?objeto=BR123456789BR"
}

Campos da resposta

itemsarray

(Lista) Um acompanhamento por pedido, com os campos do detalhe. Acompanha total, page, per_page e party (type, cnpj).

order_iduuid

Pedido.

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 foi pulada).

trackingobject

Dados de transporte: carrier, tracking_code, tracking_url, estimated_delivery_at. Todos podem ser nulos.

shipmentsarray

(Detalhe) Remessas com dados de rastreio e public_note.

timelinearray

tracking_codestring

(Resumo) Código de rastreio da primeira remessa. Vazio se ainda não foi informado.

carrierstring

(Resumo) Transportadora da primeira remessa. Vazio se ainda não há.

statusstring

(Resumo) Status da remessa.

urlstring

(Resumo) Link de rastreio na transportadora. Vazio para transportadora desconhecida ou sem código.

Os campos completos de items[] e do detalhe (purchase_order_number, customer_name, customer_company, shipments[] e outros) estão em Rastreio da transportadora.

Erros

Status	Quando	Corpo
400	`{id}` igual a `0` ou negativo no caminho	`{"error":"invalid id parameter"}`
401	Sem token, ou com um JWT de usuário	`{"error":"app_token_required"}`
401	Token de app inválido, expirado ou revogado	`{"error":"invalid or expired app access token"}`
429	O token excedeu o limite de chamadas	`{"error":"rate_limit_exceeded"}`
403	Token sem o escopo `read_orders`	`{"error":"missing_scope","required":"read_orders"}`
403	Recurso de acompanhamento desligado na loja (`order-tracking`)	`{"error":"module_disabled","module":"order-status-flow"}`
404	Pedido inexistente (`order-tracking/{id}`)	`{"error":"order not found"}`
404	Pedido sem remessa (`orders/{id}/tracking`)	`{"error":"no shipments for this order"}`
422	Consulta inválida em `order-tracking`	`{"error":"validation_failed","issues":[{"field":"party_type","code":"required"},{"field":"cnpj","code":"invalid"}]}`
422	`{id}` de `order-tracking/{id}` que não é UUID	`{"error":"validation_failed","issues":[{"field":"id","code":"invalid"}]}`
500	Falha interna, ou `{id}` que não é UUID em `orders/{id}/tracking`	`{"error":"failed to fetch shipments"}`