Pular para o conteúdo principal

Correios — erros e como corrigir

Quando os Correios recusam uma chamada do idworks — geração de etiqueta, envio de EDI, consulta de CEP, autenticação — o canal devolve um código curto (PPN-202, RTL-036, GTW-006, CEP-003, etc.) seguido de uma frase curta em português. O código identifica o serviço (PPN = Pré-Postagem; RTL = Rótulo/Etiqueta; GTW = Gateway de autenticação; CEP = consulta de CEP) e a frase explica o problema. Este artigo é o catálogo dessas mensagens: o que cada uma significa em linguagem de operador, onde ela aparece no idworks e como corrigir.

A configuração geral da integração (credenciais, contrato, serviços contratados, faturador) está em Correios. Os erros mais comuns na geração de etiqueta também aparecem por lá — este artigo é a referência completa.

Índice​

Conceito

Autenticação e credenciais (GTW)

Endereço e CEP (CEP)

Pré-postagem e dados do envio (PPN)

Etiqueta (RTL)

Referência rápida

Onde os erros dos Correios aparecem no idworks?​

📍 Onde: os erros podem aparecer em três telas, dependendo da ação que disparou a chamada:

  • Vendas → Pedidos → ação Gerar etiqueta ou Enviar EDI — quando a integração responde ao botão da tela, o erro aparece direto na linha do pedido (e fica no histórico do pedido em Timeline).
  • Configurações → Integrações → Log Integrações — diário completo de tudo que o idworks chamou nos Correios, com a resposta crua do canal. Use os filtros Integração = Correios e Status = Erro para listar só falhas. Tela detalhada em Log Integrações.
  • Hub → Pedidos Integrados — quando o erro acontece durante a importação de um pedido vindo de canal que usa Correios como transportadora, o motivo fica na linha.

Em todos os casos, o texto que importa é a sigla (PPN-X, RTL-X, GTW-X, CEP-X) seguida da frase em português — essa combinação é o que você usa para identificar a causa.

O que significam os prefixos GTW, PPN, RTL e CEP?​

Os Correios separam os erros por família de serviço. Saber o prefixo já encurta o diagnóstico:

  • GTW (Gateway) — falha de autenticação. O token de acesso (usuário + senha do contrato) está inválido ou expirou. A correção é nas credenciais da integração.
  • PPN (Pré-Postagem) — falha ao registrar o envio. Geralmente algum dado do pedido (CEP, contrato, serviço, declaração de conteúdo) está fora do padrão.
  • RTL (Rótulo/Etiqueta) — falha na geração da etiqueta propriamente dita. Faltou algum campo obrigatório da etiqueta (telefone, documento, endereço).
  • CEP (Consulta de CEP) — falha ao consultar o endereço de um CEP. CEP digitado errado, CEP novo ainda não carregado na base dos Correios.

Quando o mesmo erro aparece em vários pedidos ao mesmo tempo, a causa quase sempre é configuração (GTW para credencial, PPN-208 para contrato/serviço). Quando o erro aparece em um pedido específico, a causa quase sempre é dado do pedido (CEP, telefone, peso).

GTW-006 — Token inválido​

Mensagem "GTW-006: Token inválido". O usuário/contrato dos Correios cadastrado na integração não foi aceito pelo gateway de autenticação. As causas mais comuns:

  • Senha trocada no portal dos Correios e não atualizada no idworks.
  • Usuário do contrato com tipo errado (alguns contratos usam usuário PJ + senha; outros usam CRM + token de API).
  • Contrato suspenso ou cancelado — o gateway recusa a autenticação enquanto o contrato não estiver ativo.

Como resolver:

  1. Em Configurações → Integrações → Minhas Integrações → Correios, abra a integração e clique em Configurar parâmetros.
  2. No grupo Credenciais de Acesso, confira Usuário, Senha e Cartão de Postagem. Atualize se trocou recentemente.
  3. Teste o login com as mesmas credenciais no portal Meu Correios (https://meucorreios.correios.com.br). Se também falhar lá, o problema está no contrato — acione o gerente dos Correios.
  4. Se o login no portal funciona mas a integração continua recusando, copie os dados de novo (atenção a espaços no início/fim) e salve.
  5. Depois de salvar, tente gerar uma etiqueta nova.

GTW-007 — Token expirado​

Mensagem "GTW-007: Token expirado". O token de autenticação que o idworks tinha em cache passou da validade. Diferente do GTW-006, não é problema de senha — é só renovação. Costuma se resolver sozinho na próxima chamada.

Como resolver:

  1. Aguarde um minuto e tente a ação de novo — o idworks renova o token automaticamente na próxima chamada.
  2. Se o erro persistir em várias tentativas, é sinal de que a renovação não está funcionando (geralmente porque a senha mudou no portal). Nesse caso, trate como GTW-006 — Token inválido e atualize as credenciais.

CEP-003 — CEP não foi encontrado​

Mensagem "CEP-003: O CEP NÚMERO não foi encontrado". O CEP informado no pedido não existe na base oficial dos Correios. Acontece principalmente em:

  • CEP digitado errado — letra trocada, dígito faltando, número de outro endereço.
  • CEP genérico que o cliente digitou para "pular" o campo (por ex., 00000-000, 99999-000).
  • CEP novo que ainda não foi adicionado à base dos Correios (acontece em loteamentos e bairros recém-aprovados).
  • CEP de área rural sem cobertura dos Correios.

Como resolver:

  1. Abra o pedido em Vendas → Pedidos e veja o endereço do destinatário.
  2. Confira o CEP no site oficial dos Correios (https://buscacep.correios.com.br). Se o site também não acha, o CEP não existe ou ainda não foi carregado.
  3. Peça o CEP correto ao comprador (pelo canal de venda, por mensagem, por telefone). Não chute o CEP — afeta o frete e a entrega.
  4. Atualize o endereço no pedido e gere a etiqueta de novo.

Em pedidos importados de canal, o CEP errado costuma vir do cadastro do comprador no marketplace. Em algumas plataformas você consegue pedir correção pelo próprio chat do pedido — em outras, oriente pelo telefone/e-mail.

PPN-202 — API CEP Informa (CEP inválido ou inexistente)​

Mensagem "PPN-202: API CEP Informa - CEP-003: O CEP NÚMERO não foi encontrado". É a versão "embrulhada" do erro CEP-003 — o PPN-202 é o aviso da pré-postagem (PPN) de que a consulta de CEP falhou, e o CEP-003 é o detalhe da falha. Causa e correção são as mesmas: CEP do destinatário inválido ou inexistente. Resolva pelo passo a passo do CEP-003.

PPN-208 — API Cliente-Contrato (contrato/serviço não autorizado)​

Mensagem "PPN-208: API Cliente-Contrato" (geralmente seguida de "Erro ao validar o Serviço" ou "Cliente não autorizado para o serviço solicitado"). O contrato dos Correios cadastrado não tem permissão para o serviço que o idworks está tentando usar — por exemplo, o pedido foi enviado como PAC (03298, 04510), mas o contrato só tem SEDEX (03220, 04162) habilitado; ou o serviço é Mini Envios e o contrato não inclui essa modalidade.

Também acontece quando:

  • O cartão de postagem está ativo mas o serviço foi descontinuado/renumerado pelos Correios (acontece com frequência — os Correios mudam códigos de serviço).
  • O serviço exige adesão específica (Mini Envios, Mercado Livre Coleta, Logística Reversa) e o contrato não foi atualizado.
  • O CNPJ do faturador do pedido não bate com o CNPJ do cartão de postagem.

Como resolver:

  1. Identifique qual serviço o pedido está tentando usar (em Vendas → Pedidos → aba Frete → campo Serviço Correios).
  2. Em Configurações → Integrações → Minhas Integrações → Correios → Configurar parâmetros → grupo Configurações Gerais, confira a lista de serviços habilitados no contrato.
  3. Se o serviço não está na lista, acione o gerente dos Correios para liberar o serviço no contrato — ou troque o serviço no pedido por um que esteja habilitado.
  4. Se o serviço está na lista mas o erro persiste, é provável que o código tenha mudado. Compare o código de serviço cadastrado com o que aparece no portal Meu Correios → Contratos → detalhe do contrato.
  5. Confirme que o faturador do pedido (a empresa que emite a NF) é a mesma empresa que assinou o contrato dos Correios. Multi-empresa precisa de contrato por empresa, ou cartão de postagem compartilhado pelo CNPJ raiz.

PPN-348 — Faltam itens da Declaração de Conteúdo​

Mensagem "PPN-348: Não foram informados todos os itens da Declaração de Conteúdo (conteúdo, quantidade, valor e peso informado)". Para alguns serviços (em especial Mini Envios, Logística Reversa e envios com valor declarado), os Correios exigem a Declaração de Conteúdo completa — cada item com descrição, quantidade, valor unitário e peso.

Quando algum desses quatro campos está em branco em qualquer item do pedido, o canal recusa o envio.

Como resolver:

  1. Abra o pedido em Vendas → Pedidos e revise cada item.
  2. Confirme que cada produto tem descrição fiscal, valor, quantidade e peso unitário preenchidos.
  3. O peso geralmente vem do cadastro do produto — se está zerado, o problema está no SKU. Em Produtos → Listar Produtos, edite o SKU e preencha Peso (em kg). Para produtos com variações, cada SKU precisa ter seu próprio peso.
  4. Salve e gere a etiqueta de novo.

Em vendas de marketplace que agrupam itens num único envio, o peso somado precisa estar correto. Itens sem peso somam zero, e o canal entende que faltou informação.

Peso do objeto não pode exceder o limite máximo permitido para o serviço​

Mensagem "Peso do objeto não pode exceder o limite máximo permitido para o serviço informado". O peso somado do envio passou do limite do serviço escolhido. Cada serviço tem teto próprio:

  • Mini Envios — até 30 kg (mas a maior parte das modalidades é até 0,5–1 kg por objeto).
  • PAC e SEDEX — até 30 kg por objeto.
  • Serviços específicos (encomenda agrupada, carga) podem ter outros tetos.

Como resolver:

  1. Confira o peso total do envio em Vendas → Pedidos → aba Pacotes / Etiquetas.
  2. Se o peso passou do teto do serviço, troque o serviço por um compatível (de Mini Envios para PAC, por exemplo).
  3. Se o serviço estava correto, é provável que o peso cadastrado dos produtos esteja errado — revise o cadastro do SKU.
  4. Para envios realmente pesados, considere dividir o pedido em vários pacotes (aba Pacotes permite criar mais de um pacote por pedido) — cada pacote recebe etiqueta própria, e cada um precisa estar abaixo do teto.

RTL-036 — Número do destinatário não foi informado​

Mensagem "RTL-036: O número do destinatário não foi informado". A etiqueta dos Correios exige o número do logradouro (a parte numérica do endereço — 123, 45A, S/N). Quando esse campo veio em branco do pedido (ou veio só como espaço), o canal recusa a geração da etiqueta.

Acontece especialmente em:

  • Pedidos importados de canais cujo formulário não tem campo separado para número (o número vem grudado na rua).
  • Cadastros antigos importados com endereço em campo único.
  • Endereços rurais sem número, em que o operador deixou em branco em vez de informar S/N.

Como resolver:

  1. Abra o pedido em Vendas → Pedidos e localize o endereço de entrega.
  2. No campo Número, preencha o número do logradouro. Para endereços sem número, use S/N (sem número) — os Correios aceitam essa convenção.
  3. Salve o pedido e gere a etiqueta de novo.
  4. Para evitar repetição em pedidos futuros do mesmo cliente, atualize também o cadastro em Clientes → Listar → editar cliente → endereço.

Privilégios da tela​

Esta tela tem privilégios próprios que controlam o que cada usuário pode fazer. Configure os perfis de acesso em Configurações → Perfis de Acesso vinculando os privilégios abaixo aos grupos desejados. Como a correção desses erros passa por várias telas, os privilégios mais usados são:

PrivilégioLibera
Visualizar PedidoAcessar Vendas → Pedidos para corrigir endereço, peso ou serviço.
Editar endereço sku pedidoEditar endereço de entrega do pedido.
Editar ConsumidorCorrigir CEP, número e telefone no cadastro do cliente.
Editar ProdutoCorrigir peso e dimensões do SKU.
Criar parametrizações empresaAtualizar credenciais e parâmetros da integração Correios.
Visualizar Log IntegraçõesAcessar Configurações → Integrações → Log Integrações para ler a resposta crua do canal.
Última atualização em