curl -X POST https://{loja}.com.br/api/hunter/v1/pedidos/PED-000123/rastreio \
-H "Content-Type: application/json" \
-H "X-API-Key: hk_..." \
-d '{
"codigo_rastreio": "AA123456789BR",
"transportadora": "Correios PAC",
"url_rastreio": "https://rastreamento.correios.com.br/app/index.php?objetos=AA123456789BR"
}'
curl -X POST https://{loja}.com.br/api/hunter/v1/pedidos/PED-000123/rastreio \
-H "Content-Type: application/json" \
-H "X-API-Key: hk_..." \
-d '{
"codigo_rastreio": "BB987654321BR",
"transportadora": "Correios PAC",
"url_rastreio": "https://rastreamento.correios.com.br/app/index.php?objetos=BB987654321BR"
}'
{
"success": true,
"data": {
"pedido": {
"codigo": "PED-000123",
"status": "enviado",
"atualizado_em": "2026-07-15T14:23:07Z"
},
"rastreio": {
"codigo": "AA123456789BR",
"transportadora": "Correios PAC",
"url": "https://rastreamento.correios.com.br/app/index.php?objetos=AA123456789BR"
},
"acao": "registrado"
}
}
{
"success": true,
"data": {
"pedido": {
"codigo": "PED-000123",
"status": "enviado",
"atualizado_em": "2026-07-15T14:35:00Z"
},
"rastreio": {
"codigo": "BB987654321BR",
"transportadora": "Correios PAC",
"url": "https://rastreamento.correios.com.br/app/index.php?objetos=BB987654321BR"
},
"acao": "corrigido"
}
}
{
"success": false,
"error": {
"code": "CONFLICT",
"message": "Pedido 'PED-000123' está em status 'pagamento_aprovado' — não pode receber rastreio (esperado: em_separacao ou enviado)."
}
}
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Pedido com código 'PED-INEXISTENTE' não encontrado."
}
}
Pedidos
Registrar rastreio
Registra ou corrige código de rastreio. Idempotência ABERTA — sobrescreve se pedido já enviado.
POST
/
api
/
hunter
/
v1
/
pedidos
/
{codigo}
/
rastreio
curl -X POST https://{loja}.com.br/api/hunter/v1/pedidos/PED-000123/rastreio \
-H "Content-Type: application/json" \
-H "X-API-Key: hk_..." \
-d '{
"codigo_rastreio": "AA123456789BR",
"transportadora": "Correios PAC",
"url_rastreio": "https://rastreamento.correios.com.br/app/index.php?objetos=AA123456789BR"
}'
curl -X POST https://{loja}.com.br/api/hunter/v1/pedidos/PED-000123/rastreio \
-H "Content-Type: application/json" \
-H "X-API-Key: hk_..." \
-d '{
"codigo_rastreio": "BB987654321BR",
"transportadora": "Correios PAC",
"url_rastreio": "https://rastreamento.correios.com.br/app/index.php?objetos=BB987654321BR"
}'
{
"success": true,
"data": {
"pedido": {
"codigo": "PED-000123",
"status": "enviado",
"atualizado_em": "2026-07-15T14:23:07Z"
},
"rastreio": {
"codigo": "AA123456789BR",
"transportadora": "Correios PAC",
"url": "https://rastreamento.correios.com.br/app/index.php?objetos=AA123456789BR"
},
"acao": "registrado"
}
}
{
"success": true,
"data": {
"pedido": {
"codigo": "PED-000123",
"status": "enviado",
"atualizado_em": "2026-07-15T14:35:00Z"
},
"rastreio": {
"codigo": "BB987654321BR",
"transportadora": "Correios PAC",
"url": "https://rastreamento.correios.com.br/app/index.php?objetos=BB987654321BR"
},
"acao": "corrigido"
}
}
{
"success": false,
"error": {
"code": "CONFLICT",
"message": "Pedido 'PED-000123' está em status 'pagamento_aprovado' — não pode receber rastreio (esperado: em_separacao ou enviado)."
}
}
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Pedido com código 'PED-INEXISTENTE' não encontrado."
}
}
Comportamento
Chame quando o pedido for postado no correio/transportadora. Este endpoint:- Registra
codigo_rastreio,transportadoraeurl_rastreiono pedido - Se pedido estava em
em_separacao: transiciona praenviado - Se pedido já estava em
enviado: sobrescreve o rastreio anterior (correção) - Grava histórico em ambos os casos (motivo
rastreio_registrado_pelo_hunterourastreio_corrigido_pelo_hunter)
Idempotência ABERTA — diferente de
/processado. Você pode chamar esse endpoint várias vezes no mesmo pedido enviado pra corrigir código de rastreio errado. Cada chamada bumpa atualizado_em e o pedido reaparece no próximo pull de quem estiver monitorando.Path param
string
required
Código do pedido (ex:
PED-000123).Payload
string
required
5–30 caracteres. Sem regex rígido — aceita formato de qualquer transportadora (
AA123456789BR, NF123456789, TR-2026-000001, etc).string
required
2–100 caracteres. String livre (ex:
"Correios PAC", "Correios SEDEX", "Jadlog Package", "J&T Express", "Loggi Direct").string (URL)
Opcional. Link público de rastreio (será mostrado ao cliente).
Comportamento por status atual do pedido
| Status atual | Ação | Response |
|---|---|---|
em_separacao | Registra + transiciona pra enviado | 200, acao: "registrado" |
enviado | Sobrescreve rastreio (correção) | 200, acao: "corrigido" |
entregue | Rejeitado | 409 CONFLICT |
cancelado | Rejeitado | 409 CONFLICT |
aguardando_pagamento | Rejeitado | 409 CONFLICT |
pagamento_recusado | Rejeitado | 409 CONFLICT |
pagamento_aprovado | Rejeitado | 409 CONFLICT |
devolvido | Rejeitado | 409 CONFLICT |
curl -X POST https://{loja}.com.br/api/hunter/v1/pedidos/PED-000123/rastreio \
-H "Content-Type: application/json" \
-H "X-API-Key: hk_..." \
-d '{
"codigo_rastreio": "AA123456789BR",
"transportadora": "Correios PAC",
"url_rastreio": "https://rastreamento.correios.com.br/app/index.php?objetos=AA123456789BR"
}'
curl -X POST https://{loja}.com.br/api/hunter/v1/pedidos/PED-000123/rastreio \
-H "Content-Type: application/json" \
-H "X-API-Key: hk_..." \
-d '{
"codigo_rastreio": "BB987654321BR",
"transportadora": "Correios PAC",
"url_rastreio": "https://rastreamento.correios.com.br/app/index.php?objetos=BB987654321BR"
}'
{
"success": true,
"data": {
"pedido": {
"codigo": "PED-000123",
"status": "enviado",
"atualizado_em": "2026-07-15T14:23:07Z"
},
"rastreio": {
"codigo": "AA123456789BR",
"transportadora": "Correios PAC",
"url": "https://rastreamento.correios.com.br/app/index.php?objetos=AA123456789BR"
},
"acao": "registrado"
}
}
{
"success": true,
"data": {
"pedido": {
"codigo": "PED-000123",
"status": "enviado",
"atualizado_em": "2026-07-15T14:35:00Z"
},
"rastreio": {
"codigo": "BB987654321BR",
"transportadora": "Correios PAC",
"url": "https://rastreamento.correios.com.br/app/index.php?objetos=BB987654321BR"
},
"acao": "corrigido"
}
}
{
"success": false,
"error": {
"code": "CONFLICT",
"message": "Pedido 'PED-000123' está em status 'pagamento_aprovado' — não pode receber rastreio (esperado: em_separacao ou enviado)."
}
}
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Pedido com código 'PED-INEXISTENTE' não encontrado."
}
}
Detalhes técnicos
'acao' no response — quando usar?
'acao' no response — quando usar?
Semanticamente pode ser ignorado — o efeito prático é o mesmo (rastreio ativo). Útil apenas em log local pra distinguir “primeira gravação” vs “correção”.
registrado: pedido veio deem_separacaoe agora estáenviadocorrigido: pedido já estavaenviadoe o rastreio foi sobrescrito
postado_em é preservado?
postado_em é preservado?
Sim. Se você chama
/rastreio na primeira vez, postado_em é setado. Em correções subsequentes, o valor original é preservado (usa COALESCE(postado_em, NOW()) internamente). Isso mantém a data real da postagem imutável mesmo em correções tardias.Como o cliente vê?
Como o cliente vê?
Assim que o rastreio é registrado, a página do pedido no site da loja mostra o código, transportadora e link (se enviado). Cliente é notificado por email/WhatsApp (dependendo da configuração da loja).
Erros
| Status | Code | Situação |
|---|---|---|
404 | NOT_FOUND | Pedido não existe |
409 | CONFLICT | Pedido em status incompatível (não em em_separacao nem enviado) |
400 | VALIDATION | Payload inválido (código curto/longo, URL mal-formada, transportadora ausente) |
Recuperação de falhas
- Timeout durante a chamada → pode reenviar. Se já processou, vira
acao: "corrigido"; se não,acao: "registrado". Ambos são sucesso. 409 CONFLICT→ não retente. Investigue o status atual do pedido viaGET /pedidos?updated_since=...— se forentregueoucancelado, ação impossível.