VibeFox Chilexpress for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior, com a extensão cURL para as tarifas em tempo real. O módulo não é instalado em versões antigas do PHP.
Chaves de API da Chilexpress (somente para tarifas em tempo real): crie uma conta no portal de desenvolvedores da Chilexpress (developers.wschilexpress.com) e assine dois produtos: Rating (Cotizador) e Coverage (Coberturas / Georreferencia). Cada produto tem a sua própria chave de assinatura. As chaves de teste funcionam somente no ambiente de teste; as chaves de produção são emitidas para clientes empresariais da Chilexpress com contrato de cliente. Você também precisa do código county da Chilexpress da comuna de onde envia, por exemplo STGO. Se usar apenas preços fixos, não precisa de chaves de API.
Regiões chilenas (somente para tarifas em tempo real): as tarifas em tempo real precisam da região do endereço de entrega. O PrestaShop não tem regiões chilenas por padrão; o módulo pode adicioná-las para você (veja Chilean regions abaixo). O país Chile precisa existir na loja.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.
Instalação
1. No back office, acesse 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, depois, encontre VibeFox Chilexpress na lista de módulos e clique em Configure.
3. Insira 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. Preencha a tabela Country prices. Para as tarifas em tempo real, informe as duas chaves de assinatura, o código county de origem e, se a moeda da loja não for CLP, a taxa de câmbio para CLP; clique em Add Chilean regions se a página pedir; depois escolha a fonte das tarifas (veja Configuração) e clique em Save.
Na instalação, o módulo cria a transportadora Chilexpress com o texto de prazo de entrega Chilexpress courier. A transportadora fica vinculada à zona Chile e a todos os grupos de clientes. Você pode alterar zonas, grupos de clientes, prazo de entrega, logo e limites de tamanho em Shipping > Carriers. Não defina preços ali: o preço sempre vem do módulo. Para oferecer a Chilexpress em outras zonas, adicione-as à transportadora nessa página ou ative Ignore shipping zones.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Chilexpress > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa as tarifas da Chilexpress e as listas de comunas em cache. As alterações exigem a permissão "configure" para o módulo; sem ela, a página mostra You do not have permission to configure this module.
A página lista os problemas no topo: há tarifas de API selecionadas, mas falta uma chave, o código county de origem ou a taxa de câmbio para CLP; a tabela de preços não tem linha para o Chile nem para o padrão; a loja não tem regiões chilenas ou o formulário de endereço chileno não tem campo de região; a unidade de peso ou de dimensão da loja não é reconhecida pelo módulo (nesse caso ela é lida como kg ou cm; defina-a em International > Localization, Local units); a transportadora foi excluída. Os números podem ser digitados com ponto ou vírgula, como no idioma do seu back office. Um número inválido ou negativo, uma CLP exchange rate igual a 0, um Min weight (kg) maior que o Max weight (kg) ou um Name com mais de 64 caracteres são erros, e nada é salvo até você corrigi-los.
Geral
Enable/Disable: ativa ou desativa a entrega pela Chilexpress. É a mesma chave do status da transportadora em Shipping > Carriers.
Name: o nome do método de entrega exibido ao cliente na finalização de compra. É o nome da transportadora. Padrão: Chilexpress. Obrigatório, até 64 caracteres.
Tax: a regra tributária da transportadora, ou No tax (o padrão de uma nova transportadora). As tarifas da API da Chilexpress são usadas exatamente como cotadas. Escolha No tax se a cotação já incluir IVA e a loja acrescentaria imposto por cima.
Tarifas
Rate source: de onde vem o preço.
As tarifas em tempo real estão disponíveis somente para destinos no Chile. Os outros países sempre usam os preços fixos.
Country prices: uma tabela de países de destino com uma coluna Price e preços opcionais por tamanho de pacote, na moeda padrão da sua loja, sem impostos. O tamanho vem do peso do carrinho: XS até 1 kg, S até 2 kg, M até 3 kg, L até 5 kg, XL acima de 5 kg. Um tamanho deixado em 0 usa Price. Clique em Add country para adicionar uma linha e no ícone de lixeira para remover uma. A linha * Default vale para os países sem linha própria. Um país sem linha (e sem * Default) não recebe preço fixo, então a transportadora fica oculta ali. Uma linha cujo preço e preços por tamanho são todos 0 dá frete grátis. Uma tabela vazia é exibida com uma linha para o Chile a 0, e a última linha não pode ser removida, apenas zerada; por isso, insira preços reais antes de salvar a página. Um país repetido ou um preço inválido é corrigido (a duplicata é ignorada, o preço vai para 0) e um aviso lista as correções.
Calculation type: Per order cobra o preço fixo uma vez. Per item (fixed price x number of items) o multiplica pelo número de itens no carrinho. Uma tarifa da API da Chilexpress é sempre cotada para o pacote inteiro.
API da Chilexpress (tarifas em tempo real)
A seção começa com links para o portal de desenvolvedores e para as páginas de assinatura de Rating e Coverage.
Test environment: usa o ambiente de teste da Chilexpress (qaservices.wschilexpress.com). Use-o com chaves de teste e desative-o em uma loja real.
Rating API key: a chave de assinatura do produto Rating (Cotizador).
Coverage API key: a chave de assinatura do produto Coverage (Coberturas / Georreferencia). Ela é usada para encontrar o código county da Chilexpress da comuna do cliente (o campo City do endereço, junto com a região).
Depois de salvar, o campo da chave fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo. A chave é salva como você digitou; apenas os espaços em volta são removidos.
Remove the saved Rating API key e Remove the saved Coverage API key: aparecem somente quando há uma chave salva. Marque a opção e clique em Save para excluir a chave.
Origin county code: o código county da Chilexpress (comuna) de onde você envia, de 2 a 5 letras, por exemplo STGO (Santiago Centro), PROV (Providencia) ou VALP (Valparaíso). Fica vazio após a instalação. Um valor que não é um código county é recusado com um erro.
Service: o serviço da Chilexpress usado para a tarifa. Se ele não for oferecido para o destino, é usado o serviço mais barato disponível.
CLP exchange rate: a Chilexpress cota em pesos chilenos. É necessária somente se a moeda padrão da sua loja não for CLP: o preço de 1 CLP nessa moeda, por exemplo 0.001. Sem ela, as tarifas da API não são usadas. Se a moeda da loja for CLP, deixe o campo vazio. O valor deve ser maior que 0.
Chilean regions: as comunas do Chile são pesquisadas por região, por isso as tarifas em tempo real precisam da região do endereço. Se a loja não tiver regiões chilenas, o campo mostra o botão Add Chilean regions. Ele adiciona as 16 regiões como estados do Chile (códigos ISO RM, VS…), ativa "Contains states" para o Chile e adiciona o campo de região ao formulário de endereço chileno. Regiões que já existem (pelo código ou pelo nome) não são adicionadas duas vezes. Quando tudo estiver pronto, o campo mostra Chilean addresses have a region com o número de regiões.
Disponibilidade
Min weight (kg): o peso mínimo do carrinho para a transportadora aparecer. 0 significa sem limite.
Max weight (kg): a transportadora fica oculta acima deste peso do carrinho. Padrão: 25. 0 significa sem limite; um campo vazio significa 25 kg. Min weight (kg) não pode ser maior que este valor.
Minimum subtotal: exibe a transportadora somente quando o subtotal do carrinho (produtos que precisam de entrega, após descontos, sem impostos) for pelo menos este valor. Deixe o campo vazio para exibi-la sempre.
Ignore shipping zones: oferece a transportadora para os países abaixo mesmo que a zona deles não esteja vinculada a ela: a transportadora fica vinculada a todas as zonas, e as zonas criadas depois também são vinculadas. Ao desativar, a transportadora volta a ter as zonas anteriores.
Countries: os países de destino para esse modo, escolhidos entre os países ativos da loja. Deixe vazio para permitir todos os países. Este campo só é usado se Ignore shipping zones estiver ativo.
Frete grátis
Free shipping: ativa o limite para frete grátis.
Free shipping from: o subtotal do carrinho (produtos que precisam de entrega, após descontos, sem impostos) a partir do qual o frete é grátis. É usado somente se Free shipping estiver ativo. Nesse caso, nenhuma solicitação é feita à API.
Avançado
Debug log: grava as solicitações à API e os cálculos de tarifas em logs/vfd_chx_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros da API são sempre registrados, mesmo com esta opção desativada. As chaves de API e os endereços dos clientes nunca são registrados.
Log: mostra o tamanho e as últimas entradas do log de depuração. Clique em Clear log para limpá-lo.
Remove data on uninstall: quando ativo, desinstalar o módulo apaga todas as suas configurações, a transportadora, as tarifas em cache, os logs e os serviços salvos com os pedidos. Quando desativado, tudo é mantido para uma nova instalação. Os próprios pedidos são sempre mantidos.
Como funciona na finalização de compra
Na etapa de entrega, o PrestaShop pede ao módulo o preço da Chilexpress. Somente os produtos que precisam de entrega entram na conta: produtos virtuais não somam peso e não entram no subtotal. O subtotal é calculado após as regras do carrinho (cupons), sem impostos, na moeda padrão da loja. O módulo verifica primeiro as condições: países permitidos (com Ignore shipping zones), peso do carrinho e subtotal mínimo. Se o frete grátis se aplicar, o preço é 0 e nenhuma solicitação é enviada à Chilexpress.
Para um endereço no Chile e uma fonte de tarifas de API, o módulo pega a região do endereço e a comuna do campo City e procura o código county da Chilexpress na lista de comunas dessa região (Coverage API). Acentos, espaços e variações de grafia são ignorados, então Ñuñoa e Nunoa coincidem, e Santiago coincide com Santiago Centro. Um código county digitado diretamente no campo City também é aceito. Em seguida, o módulo envia à Rating API os códigos county de origem e de destino, o peso do carrinho (no mínimo 0,1 kg), as dimensões do pacote (comprimento e largura do maior produto, alturas somadas) e o subtotal do carrinho em CLP como valor declarado. A Chilexpress retorna os seus serviços; o módulo usa o serviço escolhido ou o mais barato e converte o valor em pesos para a moeda padrão da loja. O preço é arredondado conforme as casas decimais dessa moeda e depois exibido na moeda do carrinho do cliente.
As tarifas ficam em cache por 1 hora e as listas de comunas por 7 dias. Uma solicitação que falhou fica registrada por 5 minutos, para que uma API lenta ou indisponível não atrase cada atualização da finalização de compra. O timeout da API é de 10 segundos. Se a Chilexpress retornar um erro, nenhum serviço com preço, ou se a comuna ou a região forem desconhecidas, o cliente não vê nenhum erro. No modo somente API, a transportadora fica oculta; caso contrário, é usado o preço fixo. O motivo é gravado no 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 acompanha a nova versão automaticamente.
O módulo calcula apenas tarifas. Ele não cria envios nem ordens de transporte (OT), não imprime etiquetas, não agenda coletas e não rastreia pacotes; reserve o envio na sua conta da Chilexpress. Os clientes não podem escolher uma agência da Chilexpress, e não há seletor de comunas: o cliente digita a comuna no campo padrão City. Envios internacionais usam os preços fixos.
Pedidos
Quando um pedido é feito com a transportadora Chilexpress, o módulo salva como o preço foi calculado. A página do pedido no back office mostra um bloco Chilexpress com Chilexpress service (para uma tarifa em tempo real, o serviço cotado pela Chilexpress, por exemplo Express) e Price source: Live rate (Chilexpress Rating API), Fixed price ou Free shipping.
Chave de licença
O módulo funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença License — VibeFox Chilexpress é o primeiro bloco da página Modules > Module Manager > VibeFox Chilexpress > Configure, acima das configurações. Digite 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-chilexpress 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 para o 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 único domínio: o domínio da loja principal, inclusive 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 Chilexpress não é exibida aos clientes na finalização de compra, e nenhuma tarifa é calculada. A vitrine do PrestaShop não sabe que você está logado no 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 de 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 a 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, 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
A Chilexpress não aparece na finalização de compra: verifique se a licença está ativa e se Enable/Disable 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á ativo e o país está em Countries). Confira os limites de peso e o Minimum subtotal. Com preços fixos, confirme se o país ou o * Default tem uma linha. Os produtos também podem estar limitados a certas transportadoras na página do produto.
O frete no Chile está grátis quando não deveria estar: a linha do Chile (ou * Default) em Country prices tem 0 em Price e nas colunas de tamanho. Insira os preços e clique em Save.
A tarifa em tempo real não aparece, e é usado o preço fixo: primeiro veja os avisos no topo da página do módulo. Se não houver avisos, ative Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo. Causas típicas: o endereço não tem região ou falta o campo de região (use Add Chilean regions), uma comuna que a Chilexpress não reconhece (verifique o campo City e a região), uma chave de outro produto ou ambiente, ou um destino sem cobertura da Chilexpress.
HTTP 401 ou 403 no log: a chave de assinatura está errada, inativa, ou é de outro produto ou ambiente. As chaves de teste funcionam somente com Test environment ativado.
As tarifas da API não são usadas em uma loja com outra moeda: informe a CLP exchange rate.
As tarifas da API têm IVA ou não? Elas são usadas exatamente como a Chilexpress as cota. Se a sua loja acrescenta imposto ao frete e a cotação já inclui IVA, defina Tax como No tax.
As tarifas parecem desatualizadas após uma mudança: clique em Save na página do módulo. Isso limpa as tarifas em cache e as listas de comunas.
A página diz "The Chilexpress carrier was not found": a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.
A página diz "The country Chile does not exist in this shop": adicione ou ative o Chile em International > Locations > Countries e depois use Add Chilean regions.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Chilexpress e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. As tarifas em cache e as listas de comunas são sempre removidas. Se Remove data on uninstall estiver ativo, a transportadora é excluída (os pedidos mantêm o histórico) e as configurações, o log e os serviços salvos com os pedidos são removidos. Se estiver desativado, a transportadora apenas é desativada e todas as configurações são mantidas. Instalar o módulo novamente restaura a transportadora salva com o status anterior. As regiões chilenas adicionadas com Add Chilean regions permanecem na loja.
Chilexpress é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Chilexpress.