Guias para negócio e 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.

Encomendas Total Express vêm com códigos no padrão TX (a documentação pública traz exemplos). No Seu Rastreio você não escolhe a transportadora na URL: o sistema identifica o formato e devolve a linha de tempo no mesmo contrato da rota de rastreio — um só GET para Correios e Total, um só tipo de resposta no seu painel de integração. Operação: menos treinamento no SAC e uma URL de rastreio coerente com a marca. Tecnologia: reutilize a chave, o `/api/public/rastreio/{codigo}` e o tratamento de erros do guia dos Correios; ajuste apenas a validação do código (AWB TX).

O comprador rastreia no site do Seu Rastreio digitando o código, sem criar conta; a página de detalhe fica em /objetos/.... A sua equipe usa a chave e a API (ou o painel) para automatizar e-commerce, pedidos e status no CRM. Essa distinção evita chamados indevidos (“por que o cliente vê 401?”): 401 é resposta de API; o site público não exige a chave da loja. Comunicação: link público no pós-venda; chave e integração só no seu servidor.

A API de CEP devolve o endereço a partir de oito dígitos, com a mesma chave dos outros módulos. Use no checkout e em integrações para preencher cidade, bairro e logradouro com menos digitação manual e menos abandono de carrinho. O cache (prazo indicado em /api-docs/cep) alivia picos de tráfego. TI: `GET /api/public/cep/{cep}`, com ou sem hífen no path conforme a documentação, `Authorization: Bearer` e tabela de erros na própria página. Comercial: contrato de API claro, documentado, alinhado ao escopo com agência ou fábrica de software.

O POST em `/api/public/pedidos` liga o código de rastreio e o estado do pedido ao time comercial, com externalId idempotente — ou seja, a mesma chave lógica de pedido da loja, atualizada de forma segura. A partir daí, rastreio, página de loja e webhooks passam a refletir o mesmo dado, com menos e-mail manual e menos planilhas paralelas. Diretoria e operações ganham visão única do funil; engenharia implementa o corpo e os status conforme /api-docs/pedidos (exemplos em cURL, JavaScript e Python). Alinhe o mapeamento de status ao acordado com comercial, suporte e e-commerce.

Cada time pode oferecer uma URL pública de rastreio com logo, cores, título e slug (subdomínio), no formato publicado em /api-docs/paginas-personalizadas — em geral `https://(seu-slug).seurastreio.com.br`. O cliente busca por rastreio (ou, quando a documentação permitir, por pedido) sem acessar a API: é a experiência de marca com o mesmo dado que alimenta a operação interna via chave e integrações. Negócio: confiança no pós-venda, menos dúvida sobre a origem do rastreio, e link no WhatsApp e e-mail. TI: validar o slug, a documentação de páginas personalizadas e, se a resposta da API de rastreio trouxer o campo `linkDetalhesCompletos` para a URL genérica, alinhar marketing e produto a um único padrão de URL.

A logística reversa liga devoluções e trocas à operação real dos Correios, com o Seu Rastreio como camada de criação, acompanhamento e integração. O time cadastra credenciais contratuais, consome tudo com chave de API e acompanha limites e respostas como descrito em /api-docs/logistica-reversa e em /planos. Diretoria e logística enxergam previsibilidade de volume e cota. Tecnologia segue rotas explícitas: credenciais, criação, listagem, consulta — e mensagens de negócio (por exemplo, limite de cota `429` quando a documentação assim indicar) para acionar o fluxo certo (comercial, operação, suporte).

A rota de listagem ( /api-docs/logistica-reversa/credenciais ) mostra o que o Seu Rastreio exibe a partir do cadastro no painel com os dados fornecidos pelos Correios. O `credentialId` e demais campos vêm da tabela oficial: a TI monta o corpo do POST de criação a partir dali, sem inventar o JSON fora do que a documentação manda agora. Governança: restringir quem acessa senha e códigos contratuais. Integração: o GET fica no servidor (nunca no navegador do cliente) e a chave de API fora de repositório público.

O POST reúne identificador de credencial, endereço, serviço e, quando aplicável, vínculo a pedido — tudo em /api-docs/logistica-reversa/criar. A resposta de sucesso e os códigos de erro (incluindo cota) seguem a própria documentação: os times de dados e operação devem ligar `message` e o corpo de erro a processos (reprocessar, comercial, abrir chamado de contrato com o operador, etc.). Não trate o texto deste guia como esquema congelado: a página de criação manda no conjunto de campos obrigatórios e exemplos da versão publicada hoje.

A rota de listagem ( /api-docs/logistica-reversa/listar ) devolve as solicitações com paginação; parâmetros, mecanismo de continuação e o formato da resposta estão só naquela página — ponto de partida para ERP, relatórios e tela interna de devolução. Operação acompanha a fila de trocas com o mesmo dado do painel, evitando planilha paralela. Tecnologia implementa o laço de paginação e limita taxa de chamadas conforme a documentação; a rota física continua nos Correios, então não prometa em produto o que a doc e a transportadora não suportam.

A rota de detalhe ( /api-docs/logistica-reversa/consultar ) devolve a solicitação, status e blocos de informação e histórico conforme a documentação publicada hoje — o id vem da criação ou da listagem, sempre com Bearer. SAC e atendimento podem exibir tela e API alinhados à política de dados pessoais da sua empresa. Atraso ou incidente na entrega física segue regra de transportadora; aqui o foco é o contrato do Seu Rastreio. Evite reconsulta em laço curto: respeite limites e a boa convivência descrita no uso geral da API pública.

O Seu Rastreio permite conectar rastreio a WhatsApp no pós-venda, conforme o plano e o que o painel oferece após o acesso. A documentação de /api-docs/whatsapp concentra método, cabeçalhos HTTP, códigos e limites — base para a TI implementar servidor a servidor com a chave correta. Diretoria, marketing e jurídico cruzam isso com opt-in, regras da plataforma WhatsApp e LGPD: responsabilidade de vocês, não de um roteiro genérico aqui. Operação e TI preservam o mínimo de tráfego, retentativas e fila do lado de casa, evitando bombardear o destinatário com status idênticos de novo em de novo.

Com webhooks, a sua infra recebe HTTP POST quando o último evento de rastreio muda, no modelo (eventos, cabeçalhos HTTP, corpo, reentregas) descrito em /api-docs/webhooks. Gestão coloca a operação a proativa (e-mail, CRM, tarefas). Tecnologia aplica HMAC no corpo bruto, resposta 2xx imediata, idempotência pelo id de entrega e, em produção, acompanhamento de 2xx, 4xx e 5xx. A documentação cobre ainda o gerenciamento (criar, testar, trocar segredo, entregas quando a página listar). Fique com ela como fonte única de campos — versões evoluem.

A API pública liga o seu e-commerce, ERP e automações ao rastreio, CEP e demais recursos com uma chave de API — tudo isso de forma previsível para o negócio (contrato e orçamento) e para a tecnologia (HTTP, autenticação, erros com mensagem clara). O desenho é simples: (1) gerar a chave no Dashboard → Chaves de API (o valor costuma começar com `sr_live_` e só é mostrado na criação — armazene em cofre de segredos e em gestão de acessos), (2) enviar um GET de prova a `/api/public/rastreio/{código}` ou `/api/public/cep/{cep}` com o header `Authorization: Bearer`, e (3) ler o JSON de sucesso ou a mensagem de falha, como em /api-docs/inicio-rapido. A chave não publica no front-end aberto, não vaza em repositório e não circula no WhatsApp. Integração sólida acontece no back-end ou em ferramentas aprovadas.

A documentação reúne exemplos em cURL, JavaScript e Python em /api-docs/exemplos (e em cada subpágina de linguagem), com o padrão Bearer e os hosts oficiais do Seu Rastreio. Isso reduz o tempo de teste de integração e serve de modelagem para o seu back-end, ERP ou automação: basta trocar a chave, o código de rastreio ou o CEP e tratar a resposta como o contrato JSON daquela rota, não como texto livre. Estratégia prática: (1) variáveis de ambiente e publicação (deploy) sem a chave no repositório; (2) a linguagem em que a sua equipe produz (Node, função em nuvem, lote) para reduzir custo e risco; (3) um único ponto de cliente HTTP compartilhado por serviço, com tempo limite (timeout) e política de retentativas alinhada à criticidade do canal.

O HTTP 401 em /api/public/... (quando a rota exige autenticação) indica que a requisição não foi aceita: falta o header, a chave veio errada, truncada, expirou ou foi revogada, ou o formato não bate com o exigido na documentação daquela rota. Não confunda com a página pública de rastreio: quem acompanha o pedido no site em /objetos/... não envia chave; ver outro guia se o sintoma for “página em branco” ou link incorreto. Regra de ouro: não coloque a chave em e-mail, mensagens instantâneas sem canal seguro aprovado, nem em repositório. Ajuste o `Authorization: Bearer` e o cofre de segredos (CI/CD) antes de abrir chamado — e nunca anexe a chave ao chamado de suporte.

A plataforma integra hoje Correios (códigos no padrão clássico, ex.: `AA…BR`) e Total Express (padrão TX…), sem exigir transportadora na URL base: envie o código com `GET` em /api/public/rastreio/{codigo} e Bearer. A resposta traz linha de tempo e campos conforme /api-docs/rastreio, incluindo o último evento e, se o plano permitir, histórico e previsão. O mesmo rastreio o comprador vê na home e em /objetos/...; a chave fica só com o time na API. Produto e diretoria reduzem o custo de múltiplas integrações. Tecnologia aplica cache e limite de taxa com critério — mas o fato da encomenda na rua ainda depende da transportadora; o Seu Rastreio expõe o status previsto no contrato público da API.