Rastreamento por transportadora
API de rastreamento Shopee
Acompanhe pedidos da Shopee dentro do seu próprio sistema, com status normalizados e histórico de eventos em JSON — inclusive quando o envio é operado por uma transportadora parceira.
Qual código enviar
Use o código de rastreio que a Shopee mostra no detalhe do pedido, não o número do pedido. O parâmetro aceita de 1 a 40 caracteres, com letras, números e hífen, sem espaços.
- SPX0000000000 (exemplo fictício)
- BR000000000BR (exemplo fictício)
Shopee Xpress e parceiras
Dependendo do vendedor e do modal de envio, o pedido é entregue pela Shopee Xpress ou por uma transportadora parceira. Em vez de manter uma tabela de qual transportadora atende qual vendedor, envie o código e leia o campo courier da resposta.
Quando você já sabe a origem, GET /v1/track/shopee/{codigo} força a transportadora e responde 400 courier_not_supported se o código não pertencer a ela. Na detecção automática, códigos de outras transportadoras continuam sendo rastreados normalmente.
Pedido aprovado, etiqueta emitida, objeto parado
O status pending cobre o intervalo em que a etiqueta já existe mas o objeto ainda não teve movimentação. É o status certo para exibir "aguardando postagem" sem inventar uma mensagem a partir do texto da transportadora.
Quando o objeto entra na rede, os eventos passam por in_transit, out_for_delivery e delivered. available_for_pickup indica que o pedido espera retirada em um ponto, e exception cobre tentativa de entrega frustrada, problema de endereço ou avaria.
Atualização em lote sem estourar limites
Um pedido típico muda de status poucas vezes por dia. Consultar a mesma encomenda a cada minuto gasta cota e não melhora a experiência de quem acompanha o pedido: use cache pelo campo status_updated_at e só consulte de novo quando o timestamp mudar.
Para varreduras em segundo plano, suba o retry_level para high e distribua as chamadas ao longo do intervalo. Para uma tela aberta pelo usuário, low ou medium respondem mais 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/shopee/SPX0000000000" \
--header "X-API-Key: SUA_CHAVE_DE_API"{
"tracking_code": "SPX0000000000",
"courier": "shopee",
"status": "in_transit",
"status_updated_at": "2026-10-21T08:30:00Z",
"service": "Shopee Xpress",
"package_description": null,
"origin": null,
"destination": null,
"estimated_delivery_date": null,
"estimated_delivery": null,
"delivered_at": null,
"recipient": null,
"events": [
{
"timestamp": "2026-10-19T17:20:00Z",
"status": "collected",
"description": "Objeto coletado pelo vendedor",
"location": {
"country": "BR",
"state": "SP",
"city": "São Paulo",
"facility": "Ponto de coleta"
},
"destination": null,
"courier_status_code": null,
"courier_status_label": null,
"detail": null,
"comment": null
},
{
"timestamp": "2026-10-21T08:30:00Z",
"status": "in_transit",
"description": "Objeto em trânsito para o centro de distribuição",
"location": {
"country": "BR",
"state": "SP",
"city": "Guarulhos",
"facility": "Centro de distribuição"
},
"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
Preciso do ID do pedido ou do código de rastreio?
Do código de rastreio. O ID do pedido é interno da Shopee e não é aceito pela API. O código aparece no detalhe do pedido, junto ao status do envio.
A API cobre pedidos enviados por transportadoras parceiras?
Sim. A detecção automática identifica a transportadora pelo formato do código e devolve o slug correspondente no campo courier. Para forçar a Shopee, use /v1/track/shopee/{codigo}.
Como tratar um pedido que ainda não tem código?
Sem código não há consulta. Trate esse estado no seu sistema como "aguardando envio" e comece a consultar quando o vendedor informar o código. O status pending já cobre o período entre a emissão da etiqueta e a primeira movimentação.
Posso usar a API em uma página pública de rastreio?
Sim, desde que a chave fique no servidor. Exponha um endpoint próprio que valide o pedido do usuário e chame a PacoteVício por trás — nunca envie a X-API-Key para o navegador.