VibeFox Correios for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.

Contrato dos Correios (apenas para preços em tempo real): os preços em tempo real usam a API de preços dos Correios Web Services (CWS) e precisam das credenciais de um contrato dos Correios com cartão de postagem. São necessários três dados: seu usuário do Meu Correios (geralmente o CNPJ ou o CPF do contrato), o código de acesso à API e o número do cartão de postagem. Gere o código de acesso no portal dos Correios Web Services (cws.correios.com.br; para homologação, cwshom.correios.com.br). Você também precisa do CEP de onde envia. Sem credenciais, o módulo funciona apenas com preços fixos.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.

Instalação

1. No back office, vá em Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.

2. Quando o envio terminar, clique em Configure, ou encontre depois o VibeFox Correios na lista de módulos e clique em Configure.

3. Informe a sua chave de licença VibeFox em License key, no bloco de licença no topo da página Configure, e clique em Activate (veja Chave de licença).

4. Informe o usuário da API dos Correios, o código de acesso, o número do cartão de postagem, o CEP de origem e o serviço. Se a moeda padrão da sua loja não for BRL, informe a cotação em BRL. Preencha os preços fixos para os outros países e como alternativa (veja Configuração) e clique em Save.

Na instalação, o módulo cria a transportadora Correios com o texto de prazo de entrega Correios (Brazilian Post). A transportadora é atribuída a todas as zonas e a todos os grupos de clientes. Você pode alterar zonas, grupos de clientes, prazo de entrega, logotipo e limites de tamanho em Shipping > Carriers. Não defina preços ali: o preço sempre vem do módulo.

Configuração

Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Correios > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa os preços dos Correios e os tokens da API em cache. Os números podem ser digitados com ponto ou vírgula.

A página mostra avisos quando os preços em tempo real ou a transportadora não podem funcionar: apenas algumas das três credenciais estão preenchidas, falta o CEP de origem, falta a cotação em BRL para uma loja em outra moeda, ou não há credenciais nem preços fixos. Cada aviso informa se, enquanto isso, são usados os preços fixos ou se a transportadora fica oculta. Também aparece um aviso se a unidade de peso ou de dimensão da loja não for reconhecida pelo módulo (ela é então lida como kg ou cm); defina kg, g, lb ou oz e cm, mm, m ou in em International > Localization (Local units).

O salvamento é recusado com uma mensagem se o título do método estiver vazio ou for inválido (no máximo 64 caracteres), se um campo numérico ou um preço em Country prices não for um número igual ou maior que 0, se a cotação em BRL for 0, se Min cart weight for maior que Max cart weight, se o CEP de origem não tiver 8 dígitos ou se o outro código de serviço tiver mais de 5 dígitos. Nada é salvo até você corrigir o valor.

Geral

Enable Correios: liga ou desliga a transportadora em todas as zonas de uma vez. É o mesmo interruptor do status da transportadora em Shipping > Carriers.

Method title: o nome da transportadora exibido no carrinho e na finalização da compra. Padrão: Correios. Obrigatório.

Tax: a regra de imposto somada ao custo do frete, ou No tax (o padrão).

API dos Correios (preços em tempo real no Brasil)

Para endereços no Brasil, o preço vem da API de preços dos Correios. Se a API não retornar preço (API fora do ar, CEP não atendido, pacote grande demais), é usado o preço fixo de Country prices, ou a transportadora fica oculta quando não há um. Os detalhes dos erros vão para o log, nunca para o cliente.

API user: seu login no portal Meu Correios, geralmente o CNPJ ou o CPF do contrato.

Access code: o código de acesso à API (código de acesso) gerado no portal dos Correios Web Services. Não é a senha do portal. Depois de salvar, o campo fica vazio e exibe Saved — leave empty to keep it (empty the API user as well to remove it). Digite um novo valor somente para alterá-lo. Para remover o código salvo, esvazie API user e Access code e salve.

Posting card: o número do cartão de postagem (cartão de postagem) do seu contrato: 10 dígitos, geralmente começando com dois zeros, por exemplo 0012345678. Números menores são completados com zeros à esquerda. Você pode conferir o número na página Correios Fácil do site dos Correios.

Homologation: usa o ambiente de homologação (teste) dos Correios: as requisições vão para apihom.correios.com.br com um código de acesso de homologação. Desative em uma loja em produção.

Origin CEP: o CEP (8 dígitos) de onde os pacotes são enviados, por exemplo 01001-000.

Service: o serviço dos Correios cobrado na finalização da compra. Códigos de varejo: PAC (04510, padrão), SEDEX (04014), SEDEX 12 (04782), SEDEX 10 (04790), SEDEX Hoje (04804). Códigos de contrato: PAC (03298), SEDEX (03220), SEDEX 12 (03140), SEDEX 10 (03158), SEDEX Hoje (03204), Correios Mini Envios (04227). Os códigos de contrato exigem um cartão de postagem de um contrato que inclua o serviço.

Other service code: opcional, um código de serviço de 5 dígitos do seu contrato que não está na lista, por exemplo 03085. Um código menor é completado com zeros à esquerda. Quando preenchido, é usado no lugar de Service.

Package format: o tipo de objeto enviado aos Correios.

Default product weight: em kg, enviado aos Correios para cada produto que não tenha peso. Padrão: 0.3. Os pesos e as dimensões dos produtos são convertidos a partir das unidades da sua loja (a descrição do campo as mostra), e o carrinho é cobrado como um único pacote.

BRL → store currency rate: o nome do campo mostra a moeda padrão da sua loja, por exemplo BRL → EUR rate. Os preços dos Correios estão em BRL. Se a moeda padrão não for BRL, informe quantas unidades da sua moeda vale um BRL, por exemplo 0.17. Sem ela, os preços em tempo real não são usados. A cotação deve ser maior que 0. Se a moeda padrão for BRL, deixe o campo vazio.

Preços fixos (usados para países fora do Brasil, sem credenciais de API e como alternativa quando a API não retorna preço)

Country prices: uma tabela de países com um preço Base e preços por peso do carrinho na moeda padrão da sua loja, sem impostos: XS até 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL acima de 5 kg. Um preço de tamanho vazio ou zero usa o preço Base. Clique em Add country para adicionar uma linha e no X para remover uma. A linha * Default (all other countries) define os preços de todos os países sem linha própria. Um país sem linha (e sem *) não recebe preço fixo. Uma linha sem nenhum preço não é salva. Um preço que não seja número, ou que seja negativo, interrompe o salvamento com um erro. Um preço base de 0 significa frete grátis para esse país.

Fixed price per: Order cobra o preço uma vez. Item (price × quantity) multiplica pelo número de itens no carrinho. Isso se aplica somente aos preços fixos. Os preços em tempo real são sempre calculados para o pacote inteiro.

Condições

Min cart weight: em kg, oculta a transportadora abaixo deste peso do carrinho. 0 significa sem limite. Não pode ser maior que Max cart weight.

Max cart weight: em kg, oculta a transportadora acima deste peso do carrinho. Padrão: 30. 0 significa sem limite, e um campo vazio significa 30 kg. Os pacotes PAC e SEDEX dos Correios podem pesar até 30 kg.

Minimum order amount: mostra a transportadora somente quando o subtotal do carrinho (produtos que precisam de envio, após descontos, antes dos impostos) atinge este valor. Deixe vazio para sempre mostrar.

Free shipping: ativa a entrega gratuita a partir do valor abaixo.

Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual o frete é grátis. Nesse caso, nenhuma requisição é feita à API.

Disponibilidade sem zonas de envio

Normalmente a transportadora é exibida nas zonas às quais foi atribuída em Shipping > Carriers.

Ignore shipping zones: oferece a transportadora para os países abaixo, independentemente da zona correspondente. Ao salvar, a transportadora é adicionada a todas as zonas. Desativar a opção remove as zonas que ela adicionou. Uma zona criada depois, enquanto a opção estiver ativa, é adicionada automaticamente.

Countries: os países de destino para esse modo. Deixe vazio para usar todos os países ativos da loja. Este campo é usado somente quando Ignore shipping zones está ativado.

Avançado

Debug log: grava os cálculos de preço em logs/vfd_crr_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros da API são sempre registrados, mesmo quando esta opção está desativada. O usuário da API, o código de acesso, o cartão de postagem, o token e os CEPs dos clientes não são registrados.

Log: mostra o tamanho e as últimas entradas do log de depuração. Clique em Clear log para esvaziá-lo.

Remove data on uninstall: quando ativado, desinstalar o módulo apaga as configurações, a transportadora, os serviços dos pedidos, os preços em cache e o log. Quando desativado, tudo é mantido para uma reinstalação.

Como funciona na finalização da compra

Na etapa de envio, o PrestaShop pede ao módulo o preço dos Correios. Somente produtos físicos contam: produtos virtuais não somam peso e não entram no valor do pedido. O módulo verifica primeiro as condições: países permitidos (com Ignore shipping zones), peso do carrinho e valor mínimo do pedido. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada aos Correios.

Para um endereço no Brasil com credenciais configuradas, o módulo primeiro obtém um token da API para o seu cartão de postagem. O token também informa os números do contrato e da diretoria regional, então o preço é o preço do seu contrato. Em seguida, solicita o preço do serviço escolhido pelo CEP de origem e de destino, pelo peso do pacote em gramas e pelo tamanho do pacote em cm. Um preço só é solicitado quando o CEP de destino tem 8 dígitos. Quando todos os produtos têm dimensões, o tamanho do pacote é estimado a partir delas; caso contrário, é enviado o tamanho mínimo dos Correios. Pacotes acima de 30 kg não são enviados à API. O preço em BRL é convertido com a sua cotação. O preço é calculado na moeda padrão da sua loja e depois exibido na moeda do carrinho do cliente.

Cada preço fica em cache por 1 hora por pacote. Uma requisição com falha fica em cache por 10 minutos, para que uma queda da API não atrase cada atualização da finalização da compra. O token fica em cache até pouco antes de expirar e é renovado automaticamente; se os Correios o rejeitarem, um novo token é solicitado e a requisição de preço é repetida uma vez. O tempo limite da API é de 12 segundos.

Se a API não retornar preço, é usado o preço fixo, ou a transportadora fica oculta quando não há preço fixo. O cliente nunca vê os detalhes dos erros da API; eles vão para o log de depuração.

Se você editar a transportadora em Shipping > Carriers depois que ela tiver pedidos, o PrestaShop a salva como uma nova versão da transportadora. O módulo segue a nova versão automaticamente.

O módulo calcula apenas as tarifas. Ele não obtém os preços internacionais dos Correios (Exporta Fácil, Packet), estimativas de prazo de entrega, etiquetas, pré-postagens, declarações nem rastreamento. Os clientes não podem escolher uma agência ou um escaninho dos Correios. Serviços adicionais (valor declarado, mão própria, aviso de recebimento) não são adicionados. O módulo mostra um único serviço dos Correios por loja, e as cotações de moeda não são atualizadas automaticamente.

Pedidos

Quando um pedido é feito com a transportadora Correios, o módulo salva como o preço do frete foi calculado. A página do pedido no back office passa a mostrar um bloco Correios com Correios service (para um preço em tempo real, por exemplo PAC — contrato (03298)) e Price source: Live price (Correios API), Fixed price ou Free shipping.

Chave de licença

O módulo funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Correios é o primeiro bloco em Modules > Module Manager > VibeFox Correios > Configure, acima das configurações. Informe a chave em License key e clique em Activate. Depois disso, o bloco mostra a chave mascarada, o status (por exemplo, a data até a qual a licença está ativa e o seu domínio) e os botões Check now para verificar o status novamente, Change key para informar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-shipping-correios e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente funcionários com a permissão Configure do módulo podem alterar a chave. Os textos do bloco seguem o idioma do back office (inglês e russo estão incluídos).

Se a chave não for aceita, o bloco informa o motivo, por exemplo Key not found, This key belongs to another product, Domain limit reached ou License expired on seguido de uma data. Depois que o endereço da loja mudar, ou depois que você liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, o módulo continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o domínio da loja principal, também em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, a transportadora Correios não é exibida aos clientes na finalização da compra e nenhuma tarifa é calculada. A vitrine do PrestaShop não sabe que você está conectado ao back office, então a transportadora também fica oculta para você: é possível configurar o módulo antes de comprar uma chave, mas não testá-lo na finalização da compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem uma renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser informada e depois uma vez por semana. Não é necessário nenhum cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.

Solução de problemas

Os Correios não aparecem na finalização da compra: verifique se a licença está ativa e se Enable Correios está ligado. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente (ou se Ignore shipping zones está ligado e o país é permitido). Confira os limites de peso e o Minimum order amount. Sem preço em tempo real, deve existir um preço fixo para o país ou para *. Os produtos também podem estar limitados a determinadas transportadoras na página do produto.

A transportadora mostra um preço fixo em vez do preço dos Correios: veja o campo Log na página do módulo. Os erros dos Correios são registrados ali: código de acesso errado, serviço que não está no seu contrato, CEP não atendido, pacote acima de 30 kg ou acima dos limites de tamanho. Confira também se o CEP de origem está informado, se o CEP do cliente tem 8 dígitos e, se a moeda padrão não for BRL, se a cotação em BRL está informada. Ative o Debug log para ver cada cálculo.

A requisição do token falha: verifique o usuário da API, o código de acesso, o cartão de postagem e o ambiente. Um código de acesso de homologação só funciona com Homologation ligado, e um código de produção só com ele desligado.

Os preços parecem desatualizados após uma alteração: clique em Save na página do módulo. Isso limpa os preços em cache e o token da API.

A página informa que a transportadora dos Correios não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.

Ao salvar, aparece a mensagem de que você não tem permissão: o seu perfil de funcionário pode visualizar o módulo, mas não configurá-lo. Salvar as configurações e limpar o log exigem a permissão de configuração do módulo.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Correios e escolha Uninstall. A chave de licença, o status da licença, os preços e tokens em cache são sempre removidos. Se Remove data on uninstall estiver ligado, a transportadora é excluída (os pedidos mantêm o histórico) e as configurações, os serviços salvos dos pedidos e o log são removidos. Se estiver desligado, a transportadora é apenas desativada e todas as configurações são mantidas. Reinstalar o módulo restaura a transportadora com o status que ela tinha antes.

Correios é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pelos Correios.