Pular para o conteúdo
PacoteVício API
Menu

Rastreamento por transportadora

API de rastreamento dos Correios

Consulte objetos PAC e SEDEX por código e receba status, eventos e datas em JSON padronizado — sem captcha, sem scraping e sem manter um robô apontado para a página dos Correios.

Iniciar gratuitamente Ver documentação

Formato do código

Objetos registrados dos Correios usam duas letras, nove dígitos e o sufixo BR. PAC e SEDEX compartilham o mesmo formato, então a API distingue o serviço pelo próprio objeto — você não precisa informar nada além do código.

  • AA123456789BR
  • EX000000000BR (exemplo fictício)

Como a consulta acontece

Você chama GET /v1/track/{codigo} e a API identifica os Correios pelo formato do código. A resposta traz o status atual, o histórico de eventos em ordem cronológica e os campos service e delivered_at quando a transportadora os informa.

Se o seu fluxo já sabe que a encomenda é dos Correios, use a rota explícita GET /v1/track/correios/{codigo}. Ela evita a etapa de detecção e deixa a intenção registrada no log da sua aplicação.

O que você deixa de manter

Raspar a página dos Correios significa lidar com captcha, bloqueio por IP, mudança de layout e indisponibilidade intermitente. Cada um desses problemas vira um alerta de madrugada e uma correção de emergência.

A PacoteVício concentra esse trabalho: o parâmetro retry_level define quanto tempo a consulta insiste antes de desistir (low 10s, medium 20s, high 45s), e falhas temporárias da transportadora não são cobradas da sua cota.

Status normalizados e eventos

O campo status assume um de dez valores — pending, collected, in_transit, out_for_delivery, available_for_pickup, tax, delivered, exception, returned e unknown — independentemente do texto que os Correios devolvem. O status do topo é o do evento mais recente, e delivered_at tem precedência quando está preenchido.

Cada evento também guarda courier_status_code e courier_status_label com o valor bruto dos Correios. Use esses campos para exibir ou depurar, nunca para regra de negócio: eles mudam sem aviso.

Primeira consulta

Envie o código com a transportadora explícita na rota. A alternativa é GET /v1/track/{codigo}, que detecta a transportadora pelo formato.

cURL
curl "https://api.pacotevicio.dev/v1/track/correios/EX000000000BR" \
  --header "X-API-Key: SUA_CHAVE_DE_API"
Resposta 200 — exemplo
{
  "tracking_code": "EX000000000BR",
  "courier": "correios",
  "status": "out_for_delivery",
  "status_updated_at": "2026-10-20T11:42:00Z",
  "service": "SEDEX",
  "package_description": null,
  "origin": null,
  "destination": null,
  "estimated_delivery_date": null,
  "estimated_delivery": null,
  "delivered_at": null,
  "recipient": null,
  "events": [
    {
      "timestamp": "2026-10-18T14:05:00Z",
      "status": "collected",
      "description": "Objeto postado",
      "location": {
        "country": "BR",
        "state": "SP",
        "city": "Franca",
        "facility": "Agência dos Correios"
      },
      "destination": null,
      "courier_status_code": "PO",
      "courier_status_label": "Objeto postado",
      "detail": null,
      "comment": null
    },
    {
      "timestamp": "2026-10-19T22:10:00Z",
      "status": "in_transit",
      "description": "Objeto em trânsito",
      "location": {
        "country": "BR",
        "state": "SP",
        "city": "Ribeirão Preto",
        "facility": "Centro de Tratamento"
      },
      "destination": null,
      "courier_status_code": "RO",
      "courier_status_label": "Objeto em trânsito",
      "detail": null,
      "comment": null
    },
    {
      "timestamp": "2026-10-20T11:42:00Z",
      "status": "out_for_delivery",
      "description": "Saiu para entrega ao destinatário",
      "location": {
        "country": "BR",
        "state": "SP",
        "city": "Campinas",
        "facility": "Unidade de Distribuição"
      },
      "destination": null,
      "courier_status_code": "BDE",
      "courier_status_label": "Saiu para entrega",
      "detail": null,
      "comment": null
    }
  ]
}

O exemplo usa dados fictícios. Os campos seguem o contrato de GET /v1/track/{codigo}.

Perguntas frequentes

Preciso de alguma credencial dos Correios?

Não. A PacoteVício consulta os Correios pela sua própria integração. Você só precisa da chave da API, enviada no cabeçalho X-API-Key.

A API funciona para PAC e SEDEX?

Sim. PAC, SEDEX e demais objetos registrados usam o mesmo formato de código (duas letras, nove dígitos e BR). O campo service indica o serviço quando os Correios o informam.

O código pode ser enviado em minúsculas?

O parâmetro aceita letras, números e hífen, de 1 a 40 caracteres, sem espaços. Normalize para maiúsculas antes de enviar para manter o mesmo código em cache e em log.

Como saber se o objeto saiu para entrega?

O status normalizado out_for_delivery corresponde ao momento em que o objeto está com o entregador. O evento equivalente também traz courier_status_code e courier_status_label com o texto original dos Correios.

Outras transportadoras