Status normalizados

Cada transportadora tem seu próprio vocabulário. O campo status traduz os eventos para um único conjunto de valores, para que sua aplicação não precise conhecer nenhuma transportadora em particular.

status aparece em dois lugares: no topo da resposta (a situação atual do objeto) e em cada item de events (a situação naquele momento).

Valores

`status`	Significado
`pending`	Etiqueta emitida, ainda sem movimentação
`collected`	Coletado do remetente ou postado
`in_transit`	Em trânsito pela rede da transportadora
`out_for_delivery`	Com o entregador, saiu para entrega
`available_for_pickup`	Aguardando retirada em um ponto
`tax`	Aguardando pagamento de tributo ou revisão tributária
`delivered`	Entregue
`exception`	Tentativa falha, problema aduaneiro, avaria ou problema de endereço
`returned`	Devolvido ao remetente
`unknown`	O status ainda não tem tradução ou o item é a atribuição sintética do plano Básico

`unknown` não é erro

Em um evento da transportadora, unknown significa que o evento existe e é real, mas ainda não mapeamos aquele código específico. Os campos courier_status_code e courier_status_label continuam disponíveis com o valor bruto — dá para inspecionar e, se for relevante para o seu caso, nos avisar para incluirmos no mapeamento.

A exceção é o primeiro evento das respostas do plano Básico. Ele tem a descrição Rastreio fornecido por PacoteVicio.dev, usa unknown e deixa os campos da transportadora como null, porque é uma atribuição sintética e não uma movimentação do objeto. O status no topo da resposta não é afetado.

Compatibilidade

Novos valores podem ser adicionados sem aviso. Trate qualquer valor desconhecido como unknown:

const KNOWN = new Set([
  "pending", "collected", "in_transit", "out_for_delivery",
  "available_for_pickup", "tax", "delivered", "exception", "returned", "unknown",
]);

const status = KNOWN.has(pacote.status) ? pacote.status : "unknown";

Em TypeScript, evite switch exaustivo sem default:

switch (pacote.status) {
  case "delivered": return "Entregue";
  case "out_for_delivery": return "Saiu para entrega";
  case "exception": return "Problema na entrega";
  default: return "Em andamento";   // sempre tenha este caminho
}

Campos brutos da transportadora

courier_status_code e courier_status_label são passthrough: vêm da transportadora sem tradução, variam entre transportadoras e mudam sem aviso. Use-os para exibição, depuração ou registro — nunca como base de lógica de negócio. Para isso existe o status.

Como o status do topo é calculado