Guia
Consulta à API dos Correios sem contrato
Para quem lidera a operação e quem implementa a integração.
Lojas e sistemas que precisam consultar o status de uma encomenda dos Correios fazem isso pela API pública do Seu Rastreio, sem cadastrar contrato, cartão de postagem ou usuário dos Correios. Quem autentica a chamada é a chave de API da conta no Seu Rastreio.
Este artigo define o que a consulta cobre, o que o JSON devolve, a diferença para a página pública de rastreio e o que continua exigindo contrato: a logística reversa. Campos, códigos HTTP e exemplos ficam em /api-docs/rastreio.
Como consultar sem contrato com os Correios
- Criar a conta e a chave. No painel, abra Chaves de API, gere a chave (prefixo sr_live_) e guarde o valor no servidor.
- Ter assinatura ativa ou em teste. Sem isso a API responde 402. O plano de entrada tem teste gratuito de 7 dias; os limites ficam em /planos.
- Chamar GET /api/public/rastreio/{codigo}. Envie o código dos Correios no path e Authorization Bearer. Leia eventoMaisRecente; histórico e previsão entram no plano pago.
- Tratar cota e o que exige contrato. 429 é a cota mensal de rastreios. Logística reversa segue outro fluxo e pede as credenciais do contrato com os Correios.
O que significa consultar sem contrato
Contrato, neste contexto, é o acordo comercial da empresa com os Correios: código administrativo, cartão de postagem e usuário (idCorreios) usados para emitir postagem e logística reversa. Nada disso entra na consulta de rastreio. O Seu Rastreio lê o código da encomenda e devolve o status pela própria API.
O Seu Rastreio não é os Correios e não é afiliado a eles. A consulta também não é a API de contrato (CWS) dos Correios. O integrador usa a documentação pública do Seu Rastreio, com chave `sr_live_` e o endpoint de rastreio, em vez do portal contratual dos Correios.
O código dos Correios segue duas letras, nove números e duas letras, como `AA123456789BR`. O mesmo endpoint reconhece códigos da Total Express; este artigo trata da consulta de códigos dos Correios.
O que a loja precisa para consultar
É preciso uma conta no Seu Rastreio, uma chave de API gerada em Dashboard → Chaves de API e uma assinatura ativa ou em teste. A chave aparece só na criação: fica no servidor, em variável de ambiente, e não vai para o navegador do cliente nem para o repositório.
Sem chave válida a API responde 401. Sem assinatura ativa ou em teste responde 402, com a orientação de assinar um plano. O teste gratuito de 7 dias do plano de entrada cobre esse acesso; não há plano gratuito permanente.
Cada plano tem uma cota mensal de rastreios. Código novo conta na cota. Consultar de novo um código que o time já acompanha não consome outra unidade. No limite, a resposta é 429, com o uso atual e o teto do plano.
Como a chamada funciona
A consulta é um GET `/api/public/rastreio/{codigo}`, com o código no path e o header `Authorization: Bearer` seguido da chave. Não há parâmetro de contrato, cartão ou usuário dos Correios.
No sucesso, use `eventoMaisRecente` para telas e avisos. Plano pago com assinatura ativa ou em teste também recebe `historico` (eventos, o mais recente primeiro) e `previsaoEntrega`. O campo `linkDetalhesCompletos` aponta a página pública, para o comprador abrir o rastreio sem a chave da loja.
Respostas encontradas podem ficar em cache por 10 minutos, como a documentação descreve. Erros não entram nesse cache. Códigos HTTP, query opcional de nome, e-mail e telefone do cliente, e exemplos em cURL, JavaScript e Python estão em /api-docs/rastreio.
O que continua exigindo contrato com os Correios
A logística reversa (autorização de postagem, coleta e etiqueta de devolução) usa o contrato da empresa. O dono ou o admin cadastra as credenciais no painel: código administrativo, cartão, serviços e usuário idCorreios. Sem essa credencial o painel não emite a reversa, nem pela API nem pela página pública de devolução.
A consulta de rastreio não emite etiqueta de ida nem substitui o contrato de postagem. Quem só precisa mostrar onde está a encomenda permanece na API de rastreio. Quem precisa abrir devolução segue o guia de credenciais de logística reversa.
Página pública e API
O comprador rastreia na home e em `/objetos/…` sem conta e sem chave. A loja usa a API no próprio sistema (e-commerce, ERP, atendimento) para ler o mesmo tipo de status com cota, histórico conforme o plano e o link para o cliente.
Um 401 na API não aparece para quem só abre a página pública. A chave identifica o time; o código da encomenda identifica o objeto.
Perguntas frequentes
Dúvidas comuns de quem coloca a integração em produção.
- Preciso de contrato com os Correios para consultar rastreio pela API?
- Não. A consulta de rastreio dos Correios pela API do Seu Rastreio não pede contrato, cartão de postagem nem usuário dos Correios. A loja autentica com a chave de API do Seu Rastreio e precisa de assinatura ativa ou em teste.
- Preciso de cartão de postagem ou usuário idCorreios para consultar o rastreio?
- Não para a consulta de rastreio. Cartão de postagem, código administrativo e usuário idCorreios entram quando a empresa emite logística reversa com o contrato dela nos Correios.
- A API do Seu Rastreio é a API de contrato (CWS) dos Correios?
- Não. É a API pública do Seu Rastreio, documentada em /api-docs/rastreio. O endpoint é GET /api/public/rastreio/{codigo}, com Authorization Bearer. O Seu Rastreio não é os Correios e não é afiliado a eles.
- O cliente final precisa de chave para rastrear?
- Não. A home e a página /objetos/{código} funcionam com o código da encomenda, sem conta e sem a chave da loja. A chave fica no servidor que chama a API.
- Logística reversa também funciona sem contrato com os Correios?
- Não. Emitir autorização, coleta ou etiqueta de devolução exige as credenciais do contrato da empresa com os Correios, cadastradas no painel. A dispensa de contrato vale para a consulta de rastreio.
- O histórico completo vem em toda consulta?
- A resposta sempre pode trazer o evento mais recente. Histórico completo e previsão de entrega entram no plano pago, com assinatura ativa ou em teste, como descreve a documentação da API de rastreamento.
- O que acontece se a cota mensal de rastreios estourar?
- A API responde 429 e informa o uso atual e o teto do plano. Consultar de novo um código que o time já acompanha não consome outra unidade da cota. Dá para acompanhar o consumo no painel e mudar de plano na mesma conta.
- Qual é o formato do código dos Correios na consulta?
- Duas letras, nove números e duas letras, por exemplo AA123456789BR. Formato não reconhecido responde 400. O mesmo endpoint também aceita códigos da Total Express.
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 06/11/2026