API REST
Rastrear objetos
Rastrear objetos pelos códigos
POST/v1/tracking
Retorna o histórico de eventos e o status atual de cada código. Exige chave secreta (mk_); chame do backend, não do frontend (sem CORS).
Capacidade: Rastreamento, disponível pela API REST do Meu Ecommerce.
Autenticação
Chave secreta mk_…, somente no backend.
Corpo da requisição
| Campo | Tipo | Obrigatório no objeto | Descrição |
|---|---|---|---|
codes | array | Sim | Códigos de rastreio dos Correios (até 50 por chamada). Mín. 1 itens. Máx. 50 itens. |
Exemplo
{
"codes": [
"AA123456789BR"
]
}Resposta de sucesso
Resultados de rastreio.
| Campo | Tipo | Obrigatório no objeto | Descrição |
|---|---|---|---|
results | array | Sim | — |
results[].code | string | Sim | — |
results[].found | boolean | Sim | — |
results[].delivered | boolean | Sim | — |
results[].lastStatus | object | Não | — |
results[].lastStatus.code | string | Sim | — |
results[].lastStatus.type | string | Não | — |
results[].lastStatus.timestamp | string | Não | — |
results[].lastStatus.description | string | Sim | — |
results[].lastStatus.origin | string | Não | — |
results[].lastStatus.destination | string | Não | — |
results[].events | array | Sim | — |
results[].events[].code | string | Sim | — |
results[].events[].type | string | Não | — |
results[].events[].timestamp | string | Não | — |
results[].events[].description | string | Sim | — |
results[].events[].origin | string | Não | — |
results[].events[].destination | string | Não | — |
results[].message | string | Não | — |
reason | string | Não | — |
actionUrl | string | Não | — |
Códigos HTTP do contrato
| Status | Descrição |
|---|---|
| 200 | Resultados de rastreio. |
| 400 | Corpo inválido. |
| 401 | Chave ausente ou inválida. |
| 402 | Assinatura necessária (subscription_required) ou franquia grátis do mês esgotada (free_quota_exceeded, com Retry-After até a virada do mês UTC). |
| 403 | Chave pública não pode rastrear — use a chave secreta. |
| 413 | Corpo grande demais. |
| 429 | Limite por minuto excedido (rate_limited). Aguarde os segundos indicados em Retry-After. |
| 502 | Falha ao consultar os Correios. |
Consulte erros e limites para os erros de autenticação e escopo, incluindo 403, e o formato de falha.
Schema completo
Baixar OpenAPI · Guia de rastreamento
Contrato e comportamento
Os códigos no exemplo são ilustrativos. Um objeto não encontrado deve ser tratado por
found, sem assumir falha de toda a chamada.