GET /v1/couriers

Retorna o catálogo de transportadoras suportadas. É a lista autoritativa: todo id aqui funciona como parâmetro de rota, e nenhum id fora dela é aceito.

Este endpoint é respondido pelo próprio gateway. Não consulta transportadora, não consome cota e não é cobrado.

Requisição

curl https://api.pacotevicio.dev/v1/couriers \
  -H "X-API-Key: pv1_..."

Resposta

{
  "data": [
    { "id": "correios",     "name": "Correios",      "required_headers": [] },
    { "id": "aliexpress",   "name": "AliExpress",    "required_headers": [] },
    { "id": "anjun",        "name": "Anjun",         "required_headers": [] },
    { "id": "shopee",       "name": "Shopee",        "required_headers": [] },
    { "id": "jtexpress",    "name": "J&T Express",   "required_headers": ["X-Tracking-Document"] },
    { "id": "totalexpress", "name": "Total Express", "required_headers": [] }
  ]
}

AliExpress

Use aliexpress. Internamente esses envios são operados pela Cainiao, mas esse nome não aparece na API: tanto na rota quanto no campo courier da resposta o valor é sempre aliexpress.

J&T Express

jtexpress exige o header X-Tracking-Document com o CPF ou CNPJ do destinatário (apenas dígitos, 11 ou 14 caracteres).

curl https://api.pacotevicio.dev/v1/track/jtexpress/888030556767025 \
  -H "X-API-Key: pv1_..." \
  -H "X-Tracking-Document: 12345678901"

Sem o header, a resposta é 422 document_required — e não é cobrada. Em rotas com detecção automática, envie o header preventivamente se o código puder ser da J&T: a exigência só é descoberta depois que a transportadora é identificada. O header é ignorado pelas demais transportadoras. Na detecção automática, um documento malformado é tratado como ausente.

Ambiguidade entre slug e código

O primeiro segmento depois de /v1/track/ é lido como transportadora somente se estiver no catálogo. Ou seja, /v1/track/correios/raw significa "Correios, código de rastreamento raw" — e não "detecção automática, resposta crua".

Novas transportadoras

O catálogo cresce ao longo do tempo. Consulte este endpoint em vez de manter uma lista fixa no seu código.