Primeiros passos

Bem-vindo à API PacoteVício. Este guia leva você da primeira requisição a uma integração pronta para produção.

Integrando com ajuda de um agente de IA? Esta documentação também está disponível em formato para LLMs em /docs/llms.txt — cada artigo é servido como markdown bruto em /docs/{slug}.md.

Pré-requisitos

  • Uma conta no portal PacoteVício
  • Uma chave de API ativa (acesse Chaves de API no menu)

Base URL

https://api.pacotevicio.dev

Todos os endpoints ficam sob o prefixo de versão /v1.

Sua primeira requisição

curl https://api.pacotevicio.dev/v1/track/BR123456789BR \
  -H "X-API-Key: <SUA_CHAVE>"

{
  "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" },
      "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
    }
  ]
}

Não é preciso informar a transportadora: ela é detectada pelo formato do código.

O que você precisa saber antes de integrar

Três regras evitam a maior parte dos problemas de integração:

  1. Use status, não courier_status_code. O campo status é normalizado e igual para todas as transportadoras. Os campos courier_status_* são o vocabulário bruto da transportadora e mudam sem aviso. Veja Status normalizados.

  2. Trate erros pelo error.code, nunca pela message. O code é contrato; a message existe para humanos e pode ser reescrita. Veja Códigos de erro.

  3. events vem do mais antigo para o mais recente. O evento atual é sempre o último do array — que é de onde status e status_updated_at vêm. No plano Básico, o primeiro item é a atribuição sintética à PacoteVicio.dev; ele não representa uma movimentação da transportadora. É proibido remover, ocultar, alterar ou substituir esse evento ao exibir ou redistribuir os dados. O descumprimento pode suspender ou encerrar a conta e suas chaves de API.

Teste antes de escrever código

No portal, a página Chaves de API tem a área Testar API: escolha entre Rastrear pacote, Objetos originais (resposta crua da transportadora) e Listar transportadoras. Clique em Enviar requisição. A chamada usa a sua chave real, passa pelos mesmos limites de uma requisição da sua aplicação e mostra status HTTP, tempo de resposta e corpo.

A requisição é real. Se a transportadora responder, ela consome uma unidade da sua cota — veja Cobrança de requisições.

Próximos passos