Pular para o conteúdo

Conectando os Correios

Frete e logísticaConexão: credenciaisAtualizado em

Ver o que a Toca faz com o Correios →

Em homologação

Abrir integrações no app

A conexão com os Correios usa a API oficial do seu contrato com os Correios, a mesma que plataformas de loja e ERPs usam para calcular frete e gerar etiqueta. Ela tem dois jeitos, no mesmo card. O principal é a chave de acesso: você cria no CWS (o portal de APIs dos Correios) uma chave só para a Toca, escolhe quais APIs ela abre e por quanto tempo, até 180 dias, e pode revogá-la quando quiser. A Toca não recebe a sua senha nem o seu código de acesso, e os Correios mandam um e-mail à empresa a cada chave criada, alterada ou revogada. O outro jeito é informar o usuário do Meu Correios da empresa e o código de acesso às APIs.

Esta integração está em homologação: a conexão funciona normalmente, mas as consultas no chat ainda estão em validação.

Os Correios não deixam misturar tipos de autorização numa mesma chave. Por isso a chave principal é por cartão de postagem (preço, prazo, rastreio, pré-postagem, etiqueta e faturas), e pedir coleta ou abrir reclamação no Fale Conosco pede uma segunda chave, opcional, por idCorreios.

Antes de começar

  • É preciso ter contrato com os Correios. Sem contrato a integração não funciona: desde 2025 os Correios só abrem rastreio, CEP, preço e prazo pela API para quem tem contrato, e o Clube Correios não dá acesso às APIs.
  • As APIs precisam estar liberadas no contrato: preço, prazo, rastro, CEP e pré-postagem. Se alguma não estiver, peça ao seu representante comercial dos Correios.
  • Para a chave de acesso:
    • Entre em cws.correios.com.br/chaves-acesso (menu Chaves de Acesso do CWS) com o usuário e a senha do Meu Correios da empresa dona do contrato e clique em Criar nova Chave.
    • Preencha Nome de identificação e Descrição (por exemplo, “Toca”) e escolha em Expiração por quanto tempo a chave vale, no máximo 180 dias. Anote o dia em que ela vence: o card da Toca pede essa data.
    • Em APIs restritas por cartão de postagem, informe o número do cartão e ligue Pré-postagem, Preço, Prazo, SRO - Rastro, Faturas e Webhook com acesso total, porque nelas a Toca também faz consultas que enviam dados (preço e prazo em lote, etiqueta, extrato da fatura). CEP, Agência e Meu Contrato podem ficar só com leitura.
    • Clique em Criar nova chave e copie a chave de 40 dígitos que o CWS mostra.
    • Para a Toca pedir coleta e abrir reclamação (opcional): crie outra chave, em APIs restritas / autorizadas por idCorreios, com Coleta Interativa e Pedido Informação em acesso total.
    • Tenha à mão o número do cartão de postagem (10 números), o número do contrato e o CNPJ da empresa dona do contrato.
  • Para o usuário e código de acesso:
    • O usuário do Meu Correios tem de ser o da empresa (CNPJ) dona do contrato. No CWS, ele aparece no campo Usuário quando você clica em Credenciais.
    • O código de acesso é gerado em cws.correios.com.br, no menu Gestão de acesso a APIs, com a senha do Meu Correios. Se a sua loja, o seu ERP ou outro sistema já usa um código de acesso dos Correios, use o mesmo: gerar outro pode derrubar a integração que usa o anterior.
    • O cartão de postagem tem 10 números, com os zeros da frente. O comercial dos Correios envia o número no fechamento do contrato.

Passo a passo

  1. Acesse Configurações → Integrações na Toca.
  2. Localize o card Correios e clique em Conectar.
  3. Escolha um caminho:
    • Chave de acesso (recomendado): preencha Chave de acesso, A chave vale até (o dia em que ela vence), Cartão de postagem, Número do contrato e CNPJ do contrato. Se criou a chave do idCorreios, preencha também Chave do idCorreios (opcional) e Essa chave vale até (opcional). Clique em Salvar chave.
    • Usuário e código de acesso: abaixo de “ou use o usuário e o código de acesso”, preencha Usuário do Meu Correios e Código de acesso às APIs, deixe Autorizar o token por em Cartão de postagem (recomendado) e informe o Cartão de postagem. Clique em Salvar código. As opções Contrato e Só o usuário (idCorreios) existem para quem não usa cartão, mas deixam de fora a pré-postagem, a etiqueta e o Correios Log+.
  4. O card fica marcado como conectado. Pela chave, ele mostra até quando ela vale.

O que a Toca acessa

Com a conexão ativa, a Toca lê o preço e o prazo de cada serviço do seu contrato (SEDEX, PAC e os outros liberados no cartão) por CEP, peso e medidas; o rastreio dos objetos, de um em um ou até 50 por vez; as pré-postagens dos últimos 120 dias, com o código de rastreio e o status; as etiquetas das pré-postagens, que ela entrega em PDF para você imprimir; a declaração de conteúdo e o aviso de recebimento; as coletas pedidas; os serviços e os cartões do contrato; as faturas, com valor, vencimento e status, a prévia do mês em aberto e o extrato analítico; as divergências de peso e CEP cobradas; as agências e os CEPs; as manifestações abertas no Fale Conosco; e as assinaturas de webhook do contrato.

A Toca também altera: cria pré-postagens (inclusive de logística reversa) e cancela as que ainda não foram postadas; vincula a nota fiscal ao objeto; pede uma faixa de códigos de rastreio; pede e cancela coletas; abre reclamações e pedidos de ressarcimento no Fale Conosco; cuida das assinaturas de webhook do contrato; e cria pedidos no armazém do Correios Log+, para quem tem o serviço. Toda alteração só acontece mediante sua aprovação explícita, pedido a pedido, dentro do chat.

Algumas alterações não se desfazem, e o pedido de aprovação diz isso: cancelar pré-postagem ou coleta, pedir faixa de códigos de rastreio (sai da cota do contrato), pedir ressarcimento e criar pedido no Correios Log+.

Pela chave de acesso, a Toca só alcança as APIs que você ligou nela. O Correios Log+ só funciona pelo usuário e código de acesso: a API dele não aceita a chave.

Ficam de fora: a importação de pré-postagens por arquivo, o boleto e o extrato da fatura em PDF (baixe no Correios Empresas) e o envio do XML da nota ao Correios Log+.

Manutenção da conexão

A chave de acesso vence no dia escolhido em Expiração, e os Correios a revogam sozinhos nesse dia. Quinze dias antes, o card troca o botão Gerenciar por Renovar chave: crie uma chave nova no CWS, com as mesmas APIs, abra o card, cole a chave e o dia novo e clique em Atualizar chave. Depois do vencimento, a Toca para de consultar os Correios até a chave nova ser salva.

Você pode revogar a chave quando quiser em cws.correios.com.br/chaves-acesso, pelo botão Revogar Chave, e a Toca perde o acesso na hora. Para mudar as APIs da chave, use editar chave e Alterar Chave no CWS; se o CWS mostrar uma chave nova depois disso, cole-a no card.

Pelo usuário e código de acesso, o acesso temporário dos Correios vale 24 horas, e a Toca renova sozinha. A conexão deixa de funcionar se o código de acesso for gerado de novo no CWS ou se o cartão de postagem for suspenso ou cancelado no contrato.

Para trocar algum dado, abra o card em Configurações → Integrações pelo botão Gerenciar, preencha o dado novo e clique em Atualizar chave ou Atualizar código. Salvar o outro caminho troca a conexão para ele. Por segurança, a chave e o código salvos aparecem mascarados.

Problemas comuns

  • O card mostra “Chave vencida” ou a Toca diz que a chave venceu — crie uma chave nova no CWS, com as mesmas APIs, e salve no card com o dia novo.
  • A Toca diz que os Correios não aceitaram a credencial ou negaram o acesso (401 ou 403), com a chave no prazo — a chave pode ter sido revogada ou não ter aquela API ligada. Confira em cws.correios.com.br/chaves-acesso e edite a chave ou crie outra. Pelo código de acesso, o 403 é a API fora do contrato: peça a liberação ao comercial dos Correios.
  • Pedir coleta ou abrir reclamação não funciona pela chave — essas duas APIs são do idCorreios e pedem a segunda chave (opcional), com Coleta Interativa e Pedido Informação.
  • O Correios Log+ não responde — ele só aceita o usuário e o código de acesso. Conecte por esse caminho para usar o Correios Log+.
  • Os Correios não emitem o acesso pelo código (401) — confira o usuário do Meu Correios e o código de acesso. Se o código foi gerado de novo no CWS, atualize o card com o novo.
  • Cartão de postagem recusado ou contrato não encontrado — confira os 10 números do cartão e se ele está ativo no contrato. Em caso de dúvida, fale com o comercial dos Correios.
  • A Toca não acha uma pré-postagem antiga — a lista dos Correios mostra só os últimos 120 dias. Para objetos mais antigos, peça o rastreio pelo código.
  • A integração da loja ou do ERP parou depois de conectar — um código de acesso novo foi gerado no CWS. Atualize o código nos outros sistemas ou volte a usar o mesmo código em todos. Pela chave de acesso isso não acontece.
  • Conectou o contrato errado — use Excluir integração no menu ⋯ do card e conecte de novo, com os dados do contrato certo.

Outras integrações de frete e logística

Abrir integrações no app