# PacoteVício API

> API pública de rastreamento de encomendas de múltiplas transportadoras brasileiras e
> internacionais. Uma única requisição consulta a transportadora e devolve o histórico do
> objeto — com detecção automática da transportadora pelo formato do código.

Base URL: `https://api.pacotevicio.dev`. Todos os endpoints ficam sob `/v1`. Autenticação via
header `X-API-Key` (formato `pv1_...`). Respostas são sempre JSON; erros nunca chegam com status
`2xx`. Trate o campo `error.code` (estável, em inglês) — nunca a `message` (em português, para
humanos). Campos e parâmetros usam `snake_case`; timestamps são RFC 3339 em UTC.

## Docs

- [Primeiros passos](https://api.pacotevicio.dev/docs/getting-started.md): pré-requisitos, base
  URL, primeira requisição e as três regras que evitam a maioria dos erros de integração.
- [Autenticação](https://api.pacotevicio.dev/docs/authentication.md): header `X-API-Key`,
  `X-Tracking-Document` (obrigatório para J&T Express) e os erros 401/403 relacionados.
- [Limites de uso](https://api.pacotevicio.dev/docs/rate-limits.md): cota e burst por plano, e
  os headers `RateLimit`/`RateLimit-Policy`.
- [Pacotes de requisições](https://api.pacotevicio.dev/docs/request-packages.md): créditos
  avulsos pré-pagos, validade e ordem de consumo frente à cota do plano.
- [Cobrança de requisições](https://api.pacotevicio.dev/docs/billing.md): quais respostas
  consomem cota (200 e 404 tracking_not_found), quais não consomem e o status
  reservado `invalid_document`.
- [Códigos de erro](https://api.pacotevicio.dev/docs/errors.md): o envelope de erro (`code`,
  `message`, `param`, `courier`, `doc_url`, `request_id`) e a tabela completa de códigos.

## Endpoints

- [GET /v1/track/:tracking_code](https://api.pacotevicio.dev/docs/tracking-get.md): rastreamento
  com detecção automática ou transportadora forçada, variantes normalizada e `/raw`, parâmetro
  `retry_level`.
- [GET /v1/couriers](https://api.pacotevicio.dev/docs/couriers.md): catálogo de transportadoras
  suportadas — endpoint não cobrado, servido pelo próprio gateway.

## Referência

- [Status normalizados](https://api.pacotevicio.dev/docs/normalized-status.md): o enum
  unificado de `status` que substitui o vocabulário específico de cada transportadora.