Autenticação

A API PacoteVício usa chaves de API. Gere, visualize e revogue a sua na página Chaves de API do portal.

Mantenha a chave em segredo: ela dá acesso à sua cota. Não a exponha em repositórios públicos nem em código client-side — qualquer pessoa com acesso ao navegador do usuário conseguiria lê-la.

Headers

Header	Obrigatório	Valor
`X-API-Key`	Sim	Sua chave, no formato `pv1_…`
`X-Tracking-Document`	Depende	CPF/CNPJ do destinatário. Obrigatório para J&T Express — veja Transportadoras
`User-Agent`	Recomendado	Identificador da sua aplicação, ex.: `minha-app/1.0`

Accept não é obrigatório: todas as respostas são application/json; charset=utf-8, independentemente do que você enviar.

Exemplos

curl https://api.pacotevicio.dev/v1/track/BR123456789BR \
  -H "X-API-Key: pv1_4f8a92b1c0d6e3f7a8b9c2d4e6f1a3b54f8a92b1c0d6e3f7a8b9c2d4e6f1a3b5" \
  -H "User-Agent: minha-app/1.0"

const res = await fetch("https://api.pacotevicio.dev/v1/track/BR123456789BR", {
  headers: {
    "X-API-Key": process.env.PV_API_KEY,
    "User-Agent": "minha-app/1.0",
  },
});

Erros de autenticação e acesso

Status	`code`	Significado
`401`	`missing_api_key`	O header `X-API-Key` não foi enviado
`401`	`invalid_api_key`	A chave é desconhecida ou foi revogada
`403`	`subscription_inactive`	A chave é válida, mas a conta não tem assinatura ativa
`403`	`account_suspended`	A conta foi suspensa; o acesso à API está bloqueado
`403`	`phone_verification_required`	Plano Básico sem telefone verificado

Nenhuma dessas respostas consome cota.

Se receber 401, confirme que o header está presente e que a chave continua ativa no portal. Ao rotacionar uma chave, a anterior é revogada imediatamente.

Rastreando um problema

Toda resposta traz o header X-Request-Id, repetido em error.request_id no corpo dos erros. Registre esse valor nos seus logs: com ele conseguimos localizar a requisição exata no nosso lado.

{
  "error": {
    "code": "invalid_api_key",
    "message": "Chave de API inválida ou revogada.",
    "request_id": "0ebcea5b-1727-4bf9-af88-4deb11b438f2"
  }
}