Guia de Configuração do Módulo

Índice

1. Introdução
2. Estrutura de Navegação
3. Credenciais
4. Configuração Básica¹
5. Configuração de Métodos¹
6. Configurações de Serviço¹
7. Modo Fallback¹
8. Configurações de PPN (antiga PLP)¹
9. Troubleshooting
10. Referência de Campos

¹ :warning: - Apenas será visível para a edição após cadastrar, salvar e validar sua crendencial.

Introdução

O módulo Correios CWS oferece integração completa com os serviços dos Correios para Magento, permitindo cálculo de fretes, impressão de etiquetas e geração de PPN (antiga PLP) (Pré-Postagem Nacional). Este guia fornece instruções detalhadas para configurar e otimizar o módulo em sua loja.

Estrutura de Navegação

Para acessar todas as configurações do módulo Correios CWS, siga o caminho:

1. Faça login no painel administrativo do Magento
2. Navegue para Lojas > Configuração
3. No menu lateral, selecione Vendas > Métodos de Entrega
4. Localize e expanda a seção Correios

Você encontrará a configuração do módulo organizada nas seguintes seções:

• Credenciais
• Configuração Básica
• Configuração de Métodos
• Configurações de Serviço
• Modo Fallback
• Configurações de PPN (antiga PLP)

Figura 1: Acesso à seção Lojas > Configuração

Figura 2: Acesso à seção Vendas > Métodos de Entrega

Credenciais

A primeira etapa para configurar o módulo é inserir e validar suas credenciais dos Correios.

Configurações Obrigatórias:

1. Ambiente:

   • Selecione entre ambiente de teste ou produção
   • Recomendamos iniciar com o ambiente de teste para validar a integração

2. Credenciais de Acesso:

   • Usuário: Insira o nome de usuário fornecido pelos Correios
   • Token: Insira o token de acesso (ATENÇÃO: este não é a senha de acesso à web, mas o token específico gerado para integrações)
   • Cartão de Postagem: Número do cartão de postagem vinculado ao seu contrato

3. Debug:

   • Ative para registrar logs detalhados durante a fase de implementação
   • Recomendado desativar em ambiente de produção

4. Validar Credenciais:

   • Após inserir as credenciais, clique em "Validar Credenciais"
   • O sistema irá verificar e salvar automaticamente as informações do contrato
   • Após validação bem-sucedida, os campos Direção, Contrato, CNPJ e ID dos Correios serão preenchidos automaticamente

IMPORTANTE: Somente após validar as credenciais com sucesso, as demais configurações do módulo serão disponibilizadas.

Figura 3: Seção de configuração de credenciais no primeiro acesso

Figura 4: Seção de credenciais após salvar os dados iniciais

Figura 5: Visualização após testar e validar as credenciais com sucesso

Figura 6: Novas opções de configuração são habilitadas após validar as credenciais

Configuração Básica

Após validar suas credenciais, configure as opções básicas do módulo:

1. Ativação do Módulo:

   • Habilitar: Sim/Não (ative para disponibilizar o método de envio)

2. Título:

   • Defina como o método de envio será exibido para seus clientes (por padrão: "Correios")

3. Mensagem de Erro:

   • Personaliza a mensagem exibida quando o serviço dos Correios não está disponível

4. Restrições de País:

   • "Enviar para Países Aplicáveis": Todos os Países ou Países Específicos
   • "Enviar para Países Específicos": Selecione os países permitidos (caso tenha selecionado "Países Específicos")

Figura 7: Configurações básicas do módulo

Configuração de Métodos

Configure os serviços de entrega disponíveis:

1. Atualizar Serviços:

   • Clique neste botão para buscar e atualizar os serviços disponíveis pela API dos Correios
   • Recomendamos executar esta ação periodicamente para manter os serviços atualizados

2. Regras de Embalagem:

   • Configure regras específicas para embalagens com base no peso, dimensões e tipo de produto
   • Útil para produtos que necessitam de embalagens especiais

3. Métodos Disponíveis:

   • Selecione quais serviços dos Correios deseja disponibilizar em sua loja (SEDEX, PAC, etc.)
   • O módulo só exibirá os serviços contratados disponíveis para seu cartão de postagem

4. Método Gratuito:

   • Selecione qual método será usado quando o frete grátis for aplicado via regras de promoção
   • Isso garante que suas regras de frete grátis utilizem corretamente o serviço desejado

Figura 8: Configuração de métodos antes de atualizar os serviços

Figura 9: Mensagem de sucesso após atualizar os serviços

Figura 10: Configuração de métodos após carregar os serviços disponíveis

Configurações de Serviço

Personalize o comportamento dos serviços:

1. Valor Declarado:

   • Quando ativado, o valor do seguro será adicionado automaticamente (se disponível para o método)
   • Recomendado para produtos de maior valor

2. Mão Própria:

   • Ative para adicionar o serviço de entrega em mãos ao destinatário

3. Aviso de Recebimento:

   • Ative para solicitar confirmação de entrega assinada pelo destinatário

4. Peso Máximo do Pacote:

   • Defina o peso máximo suportado para cada pacote
   • Verifique com os Correios o limite máximo para os serviços contratados

5. Taxa de Manuseio:

   • Calcular Taxa de Manuseio: Por pedido ou por pacote
   • Aplicar Manuseio: Por pedido ou por item
   • Taxa de Manuseio: Valor adicional a ser cobrado

6. Prazo Adicional:

   • Adiciona dias extras ao prazo informado pelos Correios
   • Útil para garantir margem no prazo de entrega prometido

7. Regras de Desconto:

   • Configure descontos específicos com base em critérios como CEP, valor do pedido ou peso

Figura 11: Configurações de serviço

Modo Fallback

O modo de contingência é utilizado quando a API dos Correios está indisponível:

1. Ativar Modo Fallback:

   • Habilite para usar a tabela de contingência quando o serviço dos Correios estiver indisponível

2. Peso Padrão para Cálculo:

   • Define o peso usado para cálculo no modo de contingência

3. Regras de Serviço:

   • Configure valores e prazos alternativos para cada serviço

4. Atualizar Tabela:

   • Atualiza automaticamente a tabela de contingência com base nos dados mais recentes

IMPORTANTE: A tabela de contingência é atualizada automaticamente uma vez por semana. Podem ocorrer discrepâncias de valores em relação à API principal.

Figura 12: Configuração do modo de contingência

Configurações de PPN (antiga PLP)

Configure a geração e impressão de etiquetas e PPN (antiga PLP:

1. Tipo de Etiqueta:

   • Selecione o tipo de etiqueta desejado (normal, carta registrada, etc.)

2. Formato da Etiqueta:

   • Escolha o formato de impressão (PDF, PNG, etc.)

3. Layout de Impressão:

   • Defina o layout para impressão das etiquetas (uma por página, múltiplas por página)

4. Status Permitidos para Criar Etiquetas:

   • Selecione quais status de pedido permitem a geração de etiquetas

5. Dados do Remetente:

   • Nome: Nome completo do remetente
   • Celular: Número de celular com DDD (será usado para comunicação via SMS)
   • Email: Email do remetente
   • CPF/CNPJ: Documento do remetente (deve ser o mesmo do contrato)
   • Endereço Completo: Logradouro, número, complemento, bairro, cidade, CEP, país e estado

ATENÇÃO: Os dados do remetente são obrigatórios para a geração de etiquetas e PPN (antiga PLP.

Figura 13: Configurações gerais de PPN (antiga PLP)

Figura 14: Configuração dos dados do remetente

Troubleshooting

Problemas Comuns:

1. Erro de Validação de Credenciais:

   • Verifique se está usando o token correto (não a senha de acesso web)
   • Confirme se o ambiente selecionado corresponde às credenciais fornecidas

2. Serviços Não Aparecem:

   • Clique em "Atualizar Serviços" para buscar os serviços disponíveis
   • Verifique se os serviços estão ativos em seu contrato com os Correios

3. Falha no Cálculo de Frete:

   • Verifique se os produtos possuem peso e dimensões cadastrados corretamente
   • Confirme se o CEP de origem está configurado nas configurações da loja
   • Ative o modo debug para analisar os logs de erro

4. Etiquetas Não Sendo Geradas:

   • Verifique se todos os dados do remetente estão preenchidos corretamente
   • Confirme se o status do pedido está entre os permitidos para geração de etiquetas

Em caso de dúvidas ou problemas persistentes, consulte a documentação completa do módulo ou entre em contato com o suporte da O2TI.

Referência de Campos

A tabela abaixo apresenta todos os campos de configuração do módulo com suas respectivas validações:

Seção	Campo	Tipo	Validação	Obrigatório	Observações
Credenciais	Ambiente	Seleção	-	Sim	Selecione entre produção ou teste
Credenciais	Usuário	Texto	required-entry	Sim	Usuário fornecido pelos Correios
Credenciais	Token	Texto	required-entry	Sim	Token específico gerado para integrações
Credenciais	Cartão de Postagem	Texto	required-entry	Sim	Número do cartão de postagem
Credenciais	Debug	Sim/Não	-	Não	Recomendado ativar em ambiente de testes
Configuração Básica	Habilitado	Sim/Não	-	Sim	Para ativar o método de envio
Configuração Básica	Título	Texto	-	Não	Nome exibido ao cliente
Configuração Básica	Mensagem de Erro	Texto	-	Não	Mensagem quando indisponível
Configuração Básica	Enviar para Países	Seleção	-	Não	Restrição de países
Configuração de Métodos	Serviços Disponíveis	Múltipla Seleção	-	Sim	Serviços dos Correios disponíveis
Configuração de Métodos	Método Gratuito	Seleção	-	Não	Para regras de frete grátis
Configurações de Serviço	Valor Declarado	Sim/Não	-	Não	Adiciona seguro ao valor
Configurações de Serviço	Mão Própria	Sim/Não	-	Não	Serviço adicional
Configurações de Serviço	Aviso de Recebimento	Sim/Não	-	Não	Serviço adicional
Configurações de Serviço	Peso Máximo do Pacote	Texto	validate-number validate-zero-or-greater	Não	Em kg
Configurações de Serviço	Taxa de Manuseio	Texto	validate-number validate-zero-or-greater	Não	Valor adicional
Configurações de Serviço	Prazo Adicional	Texto	validate-number validate-zero-or-greater	Não	Em dias
Modo Fallback	Ativar Modo Fallback	Sim/Não	-	Não	Contingência quando API indisponível
Modo Fallback	Peso Padrão para Cálculo	Texto	-	Não	Usado no modo de contingência
Configurações de PPN (antiga PLP)	Tipo de Etiqueta	Seleção	-	Não	Normal, carta, etc.
Configurações de PPN (antiga PLP)	Formato da Etiqueta	Seleção	-	Não	PDF, PNG, etc.
Configurações de PPN (antiga PLP)	Layout de Impressão	Seleção	-	Não	Quantidade por página
Configurações de PPN (antiga PLP)	Status Permitidos	Múltipla Seleção	-	Não	Status para gerar etiquetas
Dados do Remetente	Nome	Texto	required-entry	Sim	Nome completo
Dados do Remetente	Celular	Texto	required-entry validate-number minimum-length-11 maximum-length-11	Sim	Somente números com DDD
Dados do Remetente	Email	Texto	required-entry	Sim	Email válido
Dados do Remetente	CPF/CNPJ	Texto	required-entry validate-number minimum-length-11 maximum-length-14	Sim	Somente números
Dados do Remetente	Logradouro	Texto	required-entry	Sim	Rua, avenida, etc.
Dados do Remetente	Número	Texto	required-entry	Sim	Número do endereço
Dados do Remetente	Complemento	Texto	-	Não	Informação adicional
Dados do Remetente	Bairro	Texto	required-entry	Sim	Bairro do endereço
Dados do Remetente	Cidade	Texto	required-entry	Sim	Nome da cidade
Dados do Remetente	CEP	Texto	required-entry	Sim	CEP válido
Dados do Remetente	País	Seleção	-	Sim	País do remetente
Dados do Remetente	Estado/Região	Texto	required-entry	Sim	Estado do remetente

![Exemplo de Erro Comum] Figura 12: Exemplo de mensagem de erro durante validação de credenciais