Guia
Como consultar rastreio dos Correios pela API do Seu Rastreio
Para quem lidera a operação e quem implementa a integração.
Se a sua loja ou sistema precisa mostrar onde está a encomenda sem depender só do site dos Correios, a API de rastreamento do Seu Rastreio concentra a consulta em um único contrato JSON: você envia o código (ex.: `AA123456789BR`) e recebe o evento mais recente, com opção de histórico e previsão conforme o plano do time.
Para a gestão: reduz ligação ao suporte, alimenta e-mail e SMS com status confiáveis e mantém a experiência da marca. Para TI: `GET` autenticado com `Authorization: Bearer`, resposta documentada em /api-docs/rastreio e o mesmo padrão usado em produção no site.
Como colocar a consulta no ar
- Obter a chave de API. Painel → Chaves de API → gerar e armazenar o valor (prefixo sr_live_).
- Chamar GET /api/public/rastreio/{codigo}. Código no formato dos Correios e header Authorization Bearer no servidor.
- Mapear o JSON. Exibir eventoMaisRecente; habilitar histórico e previsão se o plano e a doc permitirem; tratar erros com message e helpUrl.
Pré-requisitos: conta, chave e código válido
Crie uma conta no Seu Rastreio, abra o Dashboard e gere a chave de API (em geral com prefixo `sr_live_`). Ela aparece só na criação — trate como senha: cofre, variável de ambiente, nunca no front-end público da loja.
O código de rastreio deve seguir o formato dos Correios (duas letras, nove números, duas letras). Evite espaços e caracteres extras na URL. Em alto volume, respeite os limites descritos na documentação e use cache no seu lado para não desperdiçar chamadas.
Implementação: GET, cabeçalho e leitura do JSON
A chamada é um GET para `/api/public/rastreio/{codigo}` na base do Seu Rastreio, com o código no path (ex.: `AA123456789BR`), sem chaves na URL final.
Inclua `Authorization: Bearer` + sua chave exatamente como nos exemplos da documentação. Sem chave válida, a API responde 401; o corpo costuma trazer `message` e, quando houver, helpUrl com orientação.
No JSON de sucesso, use `eventoMaisRecente` para telas e notificações; em planos com o recurso, aproveite histórico e previsão de entrega conforme a tabela de campos em /api-docs/rastreio.
Após a integração: atendimento e canais do cliente
Valide o código no checkout ou ERP antes de chamar a API, evitando requisições inúteis. O retorno pode incluir `linkDetalhesCompletos`: use em e-mail transacional para o comprador abrir a página pública de rastreio, sem expor a chave da empresa.
O mesmo endpoint atende Total Express (códigos TX). Para outra transportadora, use o guia dedicado. Se aparecer 401, revise a chave (veja o guia erro 401 na API pública). Planos e o que entra em cada resposta estão em /planos e na documentação do endpoint.
Perguntas frequentes
Dúvidas comuns de quem coloca a integração em produção.
- O consumidor final precisa de chave de API para rastrear no site do Seu Rastreio?
- Não. O rastreio aberto na home e em /objetos/… funciona com o código. A chave identifica o seu time e libera a API e cotas; não deve ser enviada ao comprador.
- A API do Seu Rastreio substitui a API de contrato dos Correios (AR)?
- Não é a mesma coisa. O Seu Rastreio expõe uma API própria, alinhada ao produto, com os campos descritos em /api-docs/rastreio. Sua equipe de TI usa essa referência para integrar, não a documentação exclusiva de contrato dos Correios.
Próximo passo: documentação oficial
Parâmetros, tabelas de resposta, limites e exemplos em código — tudo na referência de API pública.
Atualizado em 23/04/2026