Rastreamento por transportadora
API de rastreamento AliExpress
Acompanhe encomendas internacionais do AliExpress com os mesmos status normalizados das transportadoras brasileiras — inclusive o período de alfândega, que costuma ser o mais confuso para quem comprou.
Formato do código
Encomendas internacionais usam códigos longos, com prefixo e sufixo de letras e sequências numéricas. Envie exatamente o que aparece no pedido, sem espaços, e a API identifica o envio.
- LP00000000000000 (exemplo fictício)
- CN000000000BR (exemplo fictício)
Cainiao nos bastidores, aliexpress na resposta
Os envios do AliExpress são operados pela Cainiao, mas esse nome não aparece na API: tanto na rota quanto no campo courier o valor é sempre aliexpress. Você não precisa conhecer a operação logística por trás do marketplace para integrar.
Se quiser fixar a transportadora, use GET /v1/track/aliexpress/{codigo}. Caso contrário, a detecção automática resolve — e continua funcionando quando o vendedor envia por outra transportadora.
Alfândega não é erro
Encomendas internacionais passam por tributação e revisão aduaneira, e isso aparece como tax: aguardando pagamento de tributo ou revisão. Não trate tax como falha na sua interface, ou o cliente vai achar que o pedido foi cancelado.
Problemas aduaneiros de fato, como retenção ou documentação pendente, chegam como exception. A descrição do evento e o campo detail trazem o texto da transportadora para você exibir ao comprador.
Prazos longos exigem cache
Um envio internacional pode passar dias sem novo evento. Consultar de hora em hora não antecipa nada e consome cota: guarde status_updated_at e só refaça a consulta quando o timestamp avançar.
Para varreduras em lote, retry_level high absorve a instabilidade dos sistemas internacionais. Para uma tela de acompanhamento, use low ou medium para responder rápido.
Primeira consulta
Envie o código com a transportadora explícita na rota. A alternativa é GET /v1/track/{codigo}, que detecta a transportadora pelo formato.
curl "https://api.pacotevicio.dev/v1/track/aliexpress/LP00000000000000" \
--header "X-API-Key: SUA_CHAVE_DE_API"{
"tracking_code": "LP00000000000000",
"courier": "aliexpress",
"status": "tax",
"status_updated_at": "2026-10-17T09:12:00Z",
"service": "Cainiao Super Economy",
"package_description": null,
"origin": null,
"destination": null,
"estimated_delivery_date": null,
"estimated_delivery": null,
"delivered_at": null,
"recipient": null,
"events": [
{
"timestamp": "2026-09-28T03:40:00Z",
"status": "collected",
"description": "Objeto recebido pelo operador logístico",
"location": {
"country": "CN",
"state": "GD",
"city": "Shenzhen",
"facility": "Centro de triagem"
},
"destination": null,
"courier_status_code": null,
"courier_status_label": null,
"detail": null,
"comment": null
},
{
"timestamp": "2026-10-05T18:25:00Z",
"status": "in_transit",
"description": "Objeto em trânsito internacional",
"location": {
"country": "BR",
"state": "SP",
"city": "Guarulhos",
"facility": "Aeroporto Internacional"
},
"destination": null,
"courier_status_code": null,
"courier_status_label": null,
"detail": null,
"comment": null
},
{
"timestamp": "2026-10-17T09:12:00Z",
"status": "tax",
"description": "Aguardando pagamento de tributo",
"location": {
"country": "BR",
"state": "SP",
"city": "Guarulhos",
"facility": "Alfândega"
},
"destination": null,
"courier_status_code": null,
"courier_status_label": null,
"detail": null,
"comment": null
}
]
}O exemplo usa dados fictícios. Os campos seguem o contrato de GET /v1/track/{codigo}.
Perguntas frequentes
O courier vem como aliexpress ou Cainiao?
Sempre aliexpress. Cainiao é a operação logística por trás do marketplace, mas o slug público da transportadora na API é aliexpress, tanto na rota quanto no campo courier.
Como identificar que a encomenda está na alfândega?
O status normalizado tax indica espera por pagamento de tributo ou revisão aduaneira. O evento correspondente traz a descrição da transportadora e o campo detail com informações adicionais.
A API rastreia encomendas internacionais fora do Brasil?
A API acompanha o trajeto informado pela transportadora, incluindo trechos internacionais e o desembaraço no Brasil. A cobertura de cada etapa depende do que a transportadora expõe.
Vale a pena consultar várias vezes por dia?
Não. Envios internacionais mudam de status poucas vezes por dia. Compare status_updated_at com o valor anterior e só consulte de novo quando houver sinal de mudança.