API atual/Referência completa/Monitoramento de entregas

Exceções de remessa

Lista as remessas paradas ou com problema reportado pela transportadora e arquiva uma exceção já tratada.

O rastreamento automático consulta as transportadoras e marca como exceção a remessa que a transportadora reportou com problema (endereço não localizado, extravio) e como parada (stale) a que ficou sem movimento por tempo demais. A fila reúne as duas para a equipe agir: ligar para a transportadora, avisar o cliente, reenviar.

Listar exceções

GET/api/v1/admin/shipping/exceptionsAdmin

Lista a fila de exceções de remessa

Exige view_shipping ou manage_shipping.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1. Cada página tem 50 itens.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shipping/exceptions" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Fila retornada

json

{
  "exceptions": [
    {
      "shipment_id": "3a4c2f1d-8b6e-4c7a-9f10-5d2e7b9a1c33",
      "order_number": "PEDIDO-20261005-0011",
      "tracking_code": "BR123456789CD",
      "tracking_state": "exception",
      "last_event_type": "delivery_failed",
      "age_hours": 53.4
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50,
  "total_pages": 1
}

Campos da resposta

exceptionsarray

Remessas da página. null quando a fila está vazia.

shipment_iduuid

Id da remessa.

order_numberstring

Número do pedido.

tracking_codestring

Código de rastreio. Vazio se a remessa não tem.

tracking_statestring

exceptionstale

exception ou stale.

last_event_typestring

Tipo do último evento de rastreio. Vazio se não há.

age_hoursnumber

Horas desde a última consulta ao rastreio (ou, se nunca houve, desde a criação da remessa).

totalinteger

Total na fila, em todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Sempre 50.

total_pagesinteger

Quantidade de páginas.

Resolver uma exceção

Depois de tratar o caso, resolva a exceção para tirá-la da fila. A remessa passa a constar como entregue no rastreamento (tracking_state: delivered). Isso é só um arquivamento: o status do pedido, a expedição e a transportadora não são alterados.

POST/api/v1/admin/shipping/exceptions/{shipmentId}/resolveAdmin

Resolve uma exceção de remessa

Exige manage_shipping. Sem corpo.

Parâmetros de caminho

shipmentIduuidobrigatório

Id da remessa (campo shipment_id da fila).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/shipping/exceptions/$SHIPMENT_ID/resolve" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Exceção resolvida

json

{
  "ok": true
}

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio exigido	`{"error":"insufficient privileges","privilege_required_any":["manage_shipping"]}`
500	`shipmentId` que não é UUID; falha interna	`{"error":"resolve_failed","detail":"o valor \"abc\" não é um uuid válido..."}` / `{"error":"exceptions_failed","detail":"..."}`

Veja também

Exceções de remessa

Lista as remessas paradas ou com problema reportado pela transportadora e arquiva uma exceção já tratada.

Listar exceções

GET/api/v1/admin/shipping/exceptionsAdmin

Lista a fila de exceções de remessa

Exige view_shipping ou manage_shipping.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1. Cada página tem 50 itens.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shipping/exceptions" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Fila retornada

json

{
  "exceptions": [
    {
      "shipment_id": "3a4c2f1d-8b6e-4c7a-9f10-5d2e7b9a1c33",
      "order_number": "PEDIDO-20261005-0011",
      "tracking_code": "BR123456789CD",
      "tracking_state": "exception",
      "last_event_type": "delivery_failed",
      "age_hours": 53.4
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50,
  "total_pages": 1
}

Campos da resposta

exceptionsarray

Remessas da página. null quando a fila está vazia.

shipment_iduuid

Id da remessa.

order_numberstring

Número do pedido.

tracking_codestring

Código de rastreio. Vazio se a remessa não tem.

tracking_statestring

exceptionstale

exception ou stale.

last_event_typestring

Tipo do último evento de rastreio. Vazio se não há.

age_hoursnumber

Horas desde a última consulta ao rastreio (ou, se nunca houve, desde a criação da remessa).

totalinteger

Total na fila, em todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Sempre 50.

total_pagesinteger

Quantidade de páginas.

Resolver uma exceção

POST/api/v1/admin/shipping/exceptions/{shipmentId}/resolveAdmin

Resolve uma exceção de remessa

Exige manage_shipping. Sem corpo.

Parâmetros de caminho

shipmentIduuidobrigatório

Id da remessa (campo shipment_id da fila).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/shipping/exceptions/$SHIPMENT_ID/resolve" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Exceção resolvida

json

{
  "ok": true
}

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio exigido	`{"error":"insufficient privileges","privilege_required_any":["manage_shipping"]}`
500	`shipmentId` que não é UUID; falha interna	`{"error":"resolve_failed","detail":"o valor \"abc\" não é um uuid válido..."}` / `{"error":"exceptions_failed","detail":"..."}`