Rastreio dos volumes

Lê a linha do tempo de rastreio dos Correios de um pedido e força a atualização do rastreio de um volume.

Depois de postado, cada volume é rastreado nos Correios (o sistema SRO) por uma rotina automática. Estas rotas mostram o resultado e permitem pedir uma atualização na hora.

Eventos de rastreio

Devolve, por volume do seller, os eventos de rastreio dos Correios, do mais recente para o mais antigo. Pedido alheio ou sem Correios devolve lista vazia.

GET/api/v1/vendor/shipping/correios/orders/{orderId}/tracking-eventsSeller

Linha do tempo de rastreio de um pedido do seller

Parâmetros de caminho

orderIduuidobrigatório

Id do pedido.

Exemplo de requisição: eventos

bash

curl "$BASE_URL/api/v1/vendor/shipping/correios/orders/b4d2f0a8-6c1e-4b3d-9a7f-2e5c8d1b0a96/tracking-events" \
  -H "Authorization: Bearer $TOKEN"

Resposta: eventos

200Eventos

json

{
  "items": [
    {
      "volume_id": "4e5d6c7b-8a9f-4e1d-b2c3-a4b5c6d7e8f9",
      "package_index": 1,
      "service_code": "03298",
      "volume_state": "open",
      "tracking_code": "AA123456789BR",
      "tracking_state": "in_transit",
      "last_polled_at": "2026-10-11T16:00:00Z",
      "events": [
        {
          "tracking_code": "AA123456789BR",
          "event_type": "in_transit",
          "raw_code": "DO",
          "raw_type": "01",
          "description": "Objeto em transferência - por favor aguarde",
          "location": "São Paulo / SP",
          "occurred_at": "2026-10-11T15:40:00Z"
        }
      ]
    }
  ],
  "total_events": 1
}

Campos da resposta

itemsarray

Um item por volume.

volume_iduuid

Volume.

package_indexinteger

Posição no pedido.

service_codestring

Serviço Correios.

volume_statestring

Estado do volume.

tracking_codestring

Rastreio da emissão atual.

tracking_statestring

Estado do rastreio.

last_polled_atstring | null

Última consulta aos Correios.

eventsarray

Eventos: tracking_code, event_type, raw_code, raw_type (códigos dos Correios), description (texto em português), location e occurred_at.

total_eventsinteger

Total de eventos em todos os volumes.

Erros: eventos

Status	Quando	Corpo de exemplo
400	`orderId` não é UUID.	`{"error":"Identificador de pedido inválido."}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O módulo `correios-shipping` está desligado na loja.	`{"error":"module_disabled","module":"correios-shipping"}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário não tem o privilégio necessário (qualquer privilégio de pedidos).	`{"error":"insufficient vendor privileges","privilege_required_any":["..."]}`
503	Falha ao consultar.	`{"error":"Não foi possível consultar o histórico de rastreamento."}`

Atualizar o rastreio

Consulta os Correios agora para um volume seu e grava os eventos novos, em vez de esperar a rotina automática. Limitado a uma chamada por minuto por volume. O corpo é vazio.

POST/api/v1/vendor/shipping/correios/volumes/{volumeId}/tracking/refreshSeller

Atualiza o rastreio de um volume

Parâmetros de caminho

volumeIduuidobrigatório

Id do volume.

Exemplo de requisição: atualizar

bash

curl -X POST "$BASE_URL/api/v1/vendor/shipping/correios/volumes/4e5d6c7b-8a9f-4e1d-b2c3-a4b5c6d7e8f9/tracking/refresh" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta: atualizar

200Atualizado

json

{
  "volume_id": "4e5d6c7b-8a9f-4e1d-b2c3-a4b5c6d7e8f9",
  "tracking_code": "AA123456789BR",
  "status": "refreshed",
  "inserted_events": 2,
  "tracking_state": "in_transit",
  "logistics_state": "shipped"
}

Campos da resposta

volume_id, tracking_codestring

Volume e rastreio consultados.

statusstring

refreshednot_trackingprovider_unavailable

refreshed (consultou), not_tracking (volume já entregue, encerrado ou aguardando postagem) ou provider_unavailable (os Correios não responderam; a rotina automática continua tentando).

inserted_eventsinteger

Quantos eventos novos entraram.

tracking_state, logistics_statestring

Estados após a consulta.

messagestring

Texto explicativo em not_tracking e provider_unavailable.

Erros: atualizar

Status	Quando	Corpo de exemplo
404	Volume inexistente ou de outro seller.	`{"error":"Volume Correios não encontrado."}`
409	O volume ainda não tem rastreio, ou o rastreamento Correios está desligado na loja.	`{"error":"Este volume ainda não tem código de rastreio."}`
429	Menos de um minuto desde a última atualização deste volume. O cabeçalho `Retry-After` e o campo `retry_after` dizem quantos segundos esperar.	`{"error":"Aguarde antes de atualizar o rastreio deste volume de novo.","retry_after":42}`
503	Não foi possível atualizar agora.	`{"error":"Não foi possível atualizar o rastreio agora."}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O módulo `correios-shipping` está desligado na loja.	`{"error":"module_disabled","module":"correios-shipping"}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário não tem o privilégio necessário (vendor_orders, vendor_manage_orders, vendor_manage_fulfillments).	`{"error":"insufficient vendor privileges","privilege_required_any":["..."]}`

Veja também

API atual/Referência completa/Correios

Rastreio dos volumes

Lê a linha do tempo de rastreio dos Correios de um pedido e força a atualização do rastreio de um volume.

Depois de postado, cada volume é rastreado nos Correios (o sistema SRO) por uma rotina automática. Estas rotas mostram o resultado e permitem pedir uma atualização na hora.

Eventos de rastreio

Devolve, por volume do seller, os eventos de rastreio dos Correios, do mais recente para o mais antigo. Pedido alheio ou sem Correios devolve lista vazia.

GET/api/v1/vendor/shipping/correios/orders/{orderId}/tracking-eventsSeller

Linha do tempo de rastreio de um pedido do seller

Parâmetros de caminho

orderIduuidobrigatório

Id do pedido.

Exemplo de requisição: eventos

bash

curl "$BASE_URL/api/v1/vendor/shipping/correios/orders/b4d2f0a8-6c1e-4b3d-9a7f-2e5c8d1b0a96/tracking-events" \
  -H "Authorization: Bearer $TOKEN"

Resposta: eventos

200Eventos

json

{
  "items": [
    {
      "volume_id": "4e5d6c7b-8a9f-4e1d-b2c3-a4b5c6d7e8f9",
      "package_index": 1,
      "service_code": "03298",
      "volume_state": "open",
      "tracking_code": "AA123456789BR",
      "tracking_state": "in_transit",
      "last_polled_at": "2026-10-11T16:00:00Z",
      "events": [
        {
          "tracking_code": "AA123456789BR",
          "event_type": "in_transit",
          "raw_code": "DO",
          "raw_type": "01",
          "description": "Objeto em transferência - por favor aguarde",
          "location": "São Paulo / SP",
          "occurred_at": "2026-10-11T15:40:00Z"
        }
      ]
    }
  ],
  "total_events": 1
}

Campos da resposta

itemsarray

Um item por volume.

volume_iduuid

Volume.

package_indexinteger

Posição no pedido.

service_codestring

Serviço Correios.

volume_statestring

Estado do volume.

tracking_codestring

Rastreio da emissão atual.

tracking_statestring

Estado do rastreio.

last_polled_atstring | null

Última consulta aos Correios.

eventsarray

Eventos: tracking_code, event_type, raw_code, raw_type (códigos dos Correios), description (texto em português), location e occurred_at.

total_eventsinteger

Total de eventos em todos os volumes.

Erros: eventos

Status	Quando	Corpo de exemplo
400	`orderId` não é UUID.	`{"error":"Identificador de pedido inválido."}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O módulo `correios-shipping` está desligado na loja.	`{"error":"module_disabled","module":"correios-shipping"}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário não tem o privilégio necessário (qualquer privilégio de pedidos).	`{"error":"insufficient vendor privileges","privilege_required_any":["..."]}`
503	Falha ao consultar.	`{"error":"Não foi possível consultar o histórico de rastreamento."}`

Atualizar o rastreio

Consulta os Correios agora para um volume seu e grava os eventos novos, em vez de esperar a rotina automática. Limitado a uma chamada por minuto por volume. O corpo é vazio.

POST/api/v1/vendor/shipping/correios/volumes/{volumeId}/tracking/refreshSeller

Atualiza o rastreio de um volume

Parâmetros de caminho

volumeIduuidobrigatório

Id do volume.

Exemplo de requisição: atualizar

bash

curl -X POST "$BASE_URL/api/v1/vendor/shipping/correios/volumes/4e5d6c7b-8a9f-4e1d-b2c3-a4b5c6d7e8f9/tracking/refresh" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta: atualizar

200Atualizado

json

{
  "volume_id": "4e5d6c7b-8a9f-4e1d-b2c3-a4b5c6d7e8f9",
  "tracking_code": "AA123456789BR",
  "status": "refreshed",
  "inserted_events": 2,
  "tracking_state": "in_transit",
  "logistics_state": "shipped"
}

Campos da resposta

volume_id, tracking_codestring

Volume e rastreio consultados.

statusstring

refreshednot_trackingprovider_unavailable

refreshed (consultou), not_tracking (volume já entregue, encerrado ou aguardando postagem) ou provider_unavailable (os Correios não responderam; a rotina automática continua tentando).

inserted_eventsinteger

Quantos eventos novos entraram.

tracking_state, logistics_statestring

Estados após a consulta.

messagestring

Texto explicativo em not_tracking e provider_unavailable.

Erros: atualizar

Status	Quando	Corpo de exemplo
404	Volume inexistente ou de outro seller.	`{"error":"Volume Correios não encontrado."}`
409	O volume ainda não tem rastreio, ou o rastreamento Correios está desligado na loja.	`{"error":"Este volume ainda não tem código de rastreio."}`
429	Menos de um minuto desde a última atualização deste volume. O cabeçalho `Retry-After` e o campo `retry_after` dizem quantos segundos esperar.	`{"error":"Aguarde antes de atualizar o rastreio deste volume de novo.","retry_after":42}`
503	Não foi possível atualizar agora.	`{"error":"Não foi possível atualizar o rastreio agora."}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O módulo `correios-shipping` está desligado na loja.	`{"error":"module_disabled","module":"correios-shipping"}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário não tem o privilégio necessário (vendor_orders, vendor_manage_orders, vendor_manage_fulfillments).	`{"error":"insufficient vendor privileges","privilege_required_any":["..."]}`