GET /v1/track/:tracking_code

Consulta o rastreamento de um objeto. A transportadora é detectada pelo formato do código, ou informada por você na rota.

Variações de rota

Parâmetros de rota

O segmento tracking_code é obrigatório. Sem ele, /v1/track/ não corresponde a uma rota e retorna 404 not_found, sem cobrança.

Query parameters

retry_level controla quanto tempo insistimos antes de desistir. Rastreamento depende de sistemas de terceiros que falham de forma intermitente; níveis mais altos toleram mais falhas temporárias, ao custo de latência.

Escolha pelo tempo que a sua aplicação pode esperar. Para uma tela que o usuário está olhando, low ou medium. Para um job em segundo plano, high.

Um valor fora da lista responde 400 invalid_retry_level, sem consumir cota.

Headers

Veja Transportadoras para as regras completas.

Headers de resposta

Resposta normalizada

{
  "tracking_code": "BR123456789BR",
  "courier": "correios",
  "status": "collected",
  "status_updated_at": "2026-07-15T13:54:00Z",
  "service": "REGISTRADO CONVENCIONAL",
  "package_description": null,
  "origin": null,
  "destination": null,
  "estimated_delivery_date": null,
  "estimated_delivery": null,
  "delivered_at": null,
  "recipient": null,
  "events": [
    {
      "timestamp": "2026-06-12T15:10:00Z",
      "status": "collected",
      "description": "Objeto coletado",
      "location": {
        "country": "BR",
        "state": "SP",
        "city": "Franca",
        "facility": "Unidade de Distribuição",
        "street": "Rua Voluntários da Franca",
        "number": "1500",
        "neighborhood": "Centro"
      },
      "destination": null,
      "courier_status_code": "CO",
      "courier_status_label": "Objeto coletado",
      "detail": null,
      "comment": null
    },
    {
      "timestamp": "2026-07-15T13:54:00Z",
      "status": "collected",
      "description": "Objeto coletado",
      "location": { "country": "BR", "state": "SP", "city": "Sao Paulo", "facility": "Unidade de Distribuição" },
      "destination": null,
      "courier_status_code": "CO",
      "courier_status_label": "Objeto coletado",
      "detail": null,
      "comment": null
    }
  ]
}

Quando estimated_delivery.type é range, apresente o intervalo entre from_date e to_date. A data antiga estimated_delivery_date contém apenas o primeiro dia e não indica uma data firme de entrega. Quando type é fixed, as duas datas coincidem. Todos os campos de previsão podem ser null quando a transportadora não informa uma estimativa.

Por exemplo, uma previsão entre 26 de setembro e 7 de outubro aparece assim:

{
  "estimated_delivery": {
    "type": "range",
    "from_date": "2026-09-26",
    "to_date": "2026-10-07"
  }
}

Campos de evento:

Descrições e informações complementares podem mudar quando corrigimos a interpretação dos dados da transportadora. Use status para decisões sobre a situação do objeto.

Todos os timestamps são UTC. Objetos ausentes vêm como null, nunca como objetos vazios; strings vazias também viram null. Durante a atualização dos serviços, destination pode estar ausente em respostas da versão anterior. Os campos adicionais de endereço em location são omitidos quando a unidade do evento não fornece um logradouro ou o campo correspondente está vazio.

Atribuição no plano Básico

Respostas normalizadas de usuários no plano Básico começam com um evento sintético um segundo anterior ao primeiro evento real:

{
  "timestamp": "2026-02-24T18:51:28Z",
  "status": "unknown",
  "description": "Rastreio fornecido por PacoteVicio.dev",
  "location": null,
  "destination": null,
  "courier_status_code": null,
  "courier_status_label": null,
  "detail": null,
  "comment": null
}

Esse evento não veio da transportadora e não altera status nem status_updated_at, que continuam representando o evento real mais recente. Ele também aparece quando créditos extras financiam a chamada de um usuário Básico. Planos pagos e respostas /raw não recebem a atribuição.

Atribuição obrigatória: é proibido remover, ocultar, alterar ou substituir esse evento ao exibir ou redistribuir dados de rastreamento obtidos com o plano Básico. O descumprimento pode resultar na suspensão ou no encerramento da conta e de suas chaves de API.

Código sem informação

Nas rotas normalizadas, se a transportadora não encontra o código, a resposta é 404 tracking_not_found — e é cobrada, porque a consulta foi feita. Nas rotas /raw, a transportadora pode informar a ausência no próprio payload; veja abaixo.

Resposta crua (/raw)

As rotas /raw devolvem o payload exato da transportadora, sem normalização. Use quando você já processa o formato original — por exemplo, ao migrar de uma integração direta.

Três avisos:

1. Sem garantia de compatibilidade. Transportadoras mudam esses payloads sem avisar, e nós repassamos a mudança.
2. O formato varia por transportadora. Confira o header X-Courier antes de interpretar o corpo.
3. O payload bruto pode conter um erro da transportadora. Nesse caso a resposta pode ser 200 com o erro no formato original, sem o envelope da PacoteVício. Por exemplo, Correios pode responder {"erro":true,"mensagem":"..."} quando não encontra o código. A consulta continua cobrada. Erros gerados pelo gateway, como chave inválida ou limite atingido, usam o envelope de Códigos de erro.

curl https://api.pacotevicio.dev/v1/track/correios/BR123456789BR/raw \
  -H "X-API-Key: pv1_..."

{
  "codObjeto": "BR123456789BR",
  "tipoPostal": { "sigla": "BR", "descricao": "ETIQUETA FIS REGIST URG", "categoria": "REGISTRADO CONVENCIONAL", "tipo": "N" },
  "dtPrevista": "",
  "eventos": [
    {
      "codigo": "CO",
      "tipo": "01",
      "dtHrCriado": { "date": "2026-07-15 10:54:00.000000", "timezone_type": 3, "timezone": "America/Sao_Paulo" },
      "descricao": "Objeto coletado",
      "unidade": { "codSro": "01327970", "tipo": "Unidade de Distribuição", "endereco": { "cidade": "Sao Paulo", "uf": "SP" } },
      "descricaoFrontEnd": "Objeto coletado",
      "finalizador": "N"
    }
  ],
  "situacao": "T"
}

O exemplo acima é ilustrativo e parcial: o payload real dos Correios traz vários outros campos, e outras transportadoras têm estruturas completamente diferentes.

Detecção automática

Sem courier na rota, a transportadora é identificada pelo formato do código. Se nenhuma transportadora suportada corresponder, a resposta é 422 courier_not_detected, que não é cobrada — nenhuma consulta foi feita.

Alguns formatos são ambíguos entre transportadoras. Quando isso acontece, consultamos as candidatas em sequência, o que aumenta o tempo de resposta. Se você já sabe a transportadora, force-a na rota: é mais rápido e determinístico.