VibeFox Cargoson for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões mais antigas do PHP.
Conta na Cargoson (somente para preços em tempo real): os preços em tempo real usam a API de preços de frete da Cargoson. As consultas de preço de frete exigem uma assinatura da Cargoson com acesso à API (plano Advanced ou superior, no momento da redação). A chave de API é emitida na sua conta Cargoson; se o seu plano não mostrar as configurações de API, peça ajuda ao suporte da Cargoson. Os preços vêm das transportadoras e das tabelas de preços conectadas a essa conta. Se você usa apenas preços fixos, não precisa de conta na Cargoson.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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 VibeFox Cargoson depois na lista de módulos e clique em Configure.
3. Informe 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. Escolha como o custo de entrega será calculado e preencha as seções correspondentes: os preços fixos e, para os preços em tempo real, a chave de API e o CEP de coleta (veja Configuração). Clique em Save.
Na instalação, o módulo cria a transportadora Cargoson com o texto de prazo de entrega Delivery by the cheapest Cargoson carrier. 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 ficam na página do módulo: Modules > Module Manager > VibeFox Cargoson > Configure. Elas se aplicam a todas as zonas da transportadora. Cada seção tem seu próprio botão Save, que salva a página inteira. Após salvar, você vê Settings saved. Cached Cargoson prices were cleared. Números decimais podem ser digitados com ponto ou vírgula. Nada é salvo, e a página exibe um erro, se um campo numérico contiver texto ou um número negativo, se Currency conversion rate for 0, se Minimum weight for maior que Maximum weight, se Method title tiver mais de 64 caracteres, se Price currency não for um código de 3 letras, ou se uma linha da tabela de preços tiver um código de país ou um preço inválido. Se o módulo não reconhecer a unidade de peso da loja, um aviso após salvar informa que os pesos dos produtos são considerados em quilogramas; defina a unidade em International > Localization (Local units).
General
Enable Cargoson: liga ou desliga a transportadora. É a mesma chave do status da transportadora em Shipping > Carriers.
Method title: o nome da transportadora exibido no carrinho e na finalização de compra. Padrão: Cargoson. Obrigatório. É também o nome da transportadora em Shipping > Carriers.
Shipping cost: como o preço é calculado.
O motivo de um preço em tempo real ausente é registrado no log do módulo. Ele nunca é exibido ao cliente.
API da Cargoson (necessária somente para preços em tempo real)
API key: a chave de API da sua conta Cargoson. Ela é enviada somente à Cargoson e nunca é exibida aos clientes nem gravada no log. Após salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente para alterá-la.
Remove the saved API key: aparece quando há uma chave salva. Ative a opção e salve para excluir a chave.
Carrier: quais preços são usados. O cliente vê uma única tarifa.
Package type code: o código de tipo de pacote da Cargoson enviado com a consulta de preço. Padrão: CLL. Os exemplos da API da Cargoson usam EUR (palete EUR) e FIN (palete FIN). Para encomendas, use o código de pacote da sua conta Cargoson. O pedido é enviado como um único pacote com o peso total do carrinho.
Price currency: a moeda dos preços na sua conta Cargoson, como código de 3 letras. Padrão: EUR. A API retorna valores sem código de moeda.
Currency conversion rate: necessário somente se a moeda dos preços for diferente da moeda padrão da loja: 1 unidade da moeda da Cargoson = X unidades da moeda padrão da loja. Deixe em branco para rejeitar esses preços, assim o cliente nunca é cobrado em moeda errada.
Envio a partir de (endereço de coleta) (usado para preços em tempo real)
Collection country: o país de onde você envia. Por padrão, é o país da loja.
Collection postcode: o CEP de onde você envia. A Cargoson exige. Se estiver vazio e o país de coleta for o país da loja, é usado o CEP da loja em Shop Parameters > Contact > Stores.
A data de coleta enviada à Cargoson é hoje, no fuso horário da loja, ou a segunda-feira seguinte, nos fins de semana.
Preços fixos (usados quando Shipping cost é Fixed prices, e como alternativa para os preços em tempo real)
Price per country and size: uma tabela com uma coluna Country (código de 2 letras), uma coluna Price e preços por peso do carrinho na moeda padrão da loja, sem impostos: XS até 1 kg, S até 2 kg, M até 3 kg, L até 5 kg, XL acima de 5 kg. Um preço de tamanho vazio ou igual a 0 usa a coluna Price; um Price vazio significa que não há tarifa fixa para aquele tamanho. Clique em Add country para adicionar uma linha e no ícone de lixeira para removê-la. Use * como código de país para todos os países sem linha própria. Países sem linha (quando não há linha *) não recebem tarifa fixa, então a transportadora fica oculta para eles. Os preços devem ser números iguais ou maiores que 0. Uma linha vazia é ignorada.
Fixed price applies: Per order cobra o preço uma vez. Per item (price × quantity) o multiplica pelo número de itens no carrinho. Os preços em tempo real da Cargoson são sempre por envio.
Condições
Minimum weight: oculta a transportadora abaixo deste peso do carrinho, em kg. 0 significa sem limite.
Maximum weight: oculta a transportadora acima deste peso do carrinho, em kg. Padrão: 25. 0 significa sem limite.
Minimum order amount: exibe a transportadora somente quando o subtotal do carrinho (após descontos, antes dos impostos) for pelo menos este valor. Deixe em branco para exibi-la sempre.
Free shipping: ativa a entrega gratuita quando o valor do pedido indicado abaixo for atingido.
Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual a entrega é gratuita. É usado somente quando Free shipping está ativado.
Tax: a regra de imposto da transportadora, ou No tax. Os preços de transporte na Cargoson geralmente são líquidos (sem impostos). Escolha No tax se seus preços já incluírem impostos.
Disponibilidade sem zonas de entrega
Normalmente a transportadora é oferecida nas zonas atribuídas a ela em Shipping > Carriers.
Ignore shipping zones: oferece a Cargoson para os países indicados abaixo, independentemente das zonas atribuídas à transportadora. Ao ativar e salvar, a transportadora é atribuída a todas as zonas; zonas criadas depois também são atribuídas. Ao desativar e salvar, a transportadora recupera as zonas anteriores.
Countries: os países de destino para esse modo. Deixe em branco para usar todos os países para os quais você envia (países ativos). Este campo só é usado quando Ignore shipping zones está ativado.
Avançado
Debug log: registra cada cálculo de tarifa em logs/vfd_cgs_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros da API e preços rejeitados são sempre registrados, mesmo com esta opção desativada. A chave de API e o CEP do cliente nunca são registrados.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativado, ao desinstalar o módulo são excluídos as configurações da Cargoson, a transportadora, os preços em cache, as cotações dos pedidos e os logs. Quando desativado, tudo é mantido para uma reinstalação.
Como funciona na finalização de compra
Na etapa de entrega, o PrestaShop pede ao módulo o preço da Cargoson. Somente produtos físicos contam: produtos virtuais não somam peso e não entram no valor do pedido. Os pesos dos produtos são convertidos da unidade da loja para quilogramas. O módulo verifica primeiro as condições: país de entrega, peso do carrinho e valor mínimo do pedido. Se o frete grátis se aplicar, o preço é 0 e nenhuma solicitação é enviada à Cargoson.
No modo de preços fixos, o preço é obtido da tabela. Nos modos em tempo real, o módulo envia à Cargoson a data de coleta, o país e o CEP de coleta, o país e o CEP de entrega e um pacote com o código de tipo de pacote e o peso total do carrinho (no mínimo 0,1 kg). Um preço em tempo real só é solicitado quando o endereço de entrega tem CEP. A Cargoson retorna os preços das suas transportadoras; o módulo escolhe o mais barato (da transportadora selecionada, se houver) e o converte para a moeda padrão da loja, se necessário. O preço é calculado na moeda padrão e depois exibido na moeda do carrinho do cliente.
Cada resposta fica em cache por 1 hora, para que o mesmo carrinho não gere nova solicitação. Uma solicitação com falha fica em cache por 10 minutos, para que a finalização de compra não espere pela Cargoson a cada atualização. O tempo limite da API é de 10 segundos. Se a Cargoson retornar um erro, nenhum preço para a rota ou um preço em outra moeda sem taxa de conversão, o cliente não vê nenhum erro. A transportadora fica oculta ou, no modo de alternativa, é usado o preço fixo.
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 somente tarifas. Ele não cria envios ou reservas na Cargoson, não imprime etiquetas nem rastreia encomendas, e os clientes não podem escolher armário automático nem ponto de retirada. O carrinho é cotado como um único pacote com o peso total; as dimensões do pacote não são enviadas. Somente o preço mais baixo é exibido, não uma lista de transportadoras.
Pedidos
A página de um pedido da Cargoson exibe um bloco Cargoson shipping com a tarifa calculada na finalização de compra:
Carrier, Service e Cargoson service ID: a transportadora e o serviço da Cargoson cotados, exibidos quando um preço em tempo real foi usado.
Price source: Cargoson live price, Fixed price ou Free shipping threshold.
Calculated price (excl. tax): o preço na moeda padrão da loja.
A cotação é salva quando o pedido é feito e não muda depois. Reserve o envio na Cargoson ou com as integrações próprias dela.
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 Cargoson é o primeiro bloco em Modules > Module Manager > VibeFox Cargoson > Configure, acima das configurações. Insira 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-shipping-cargoson e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente funcionários com a permissão de configuração 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 muda, ou depois que você libera 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 multistore. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a transportadora Cargoson não é exibida aos clientes na finalização de 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 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 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 inserida e, depois, uma vez por semana. Não é preciso 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 Cargoson não aparece na finalização de compra: verifique se a licença está ativa e se Enable Cargoson está ligado. Em Shipping > Carriers, confira 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 está em Countries). Verifique os limites de peso e Minimum order amount. No modo de preços fixos, confira se o país ou * tem preço para o tamanho do carrinho. Os produtos também podem ser limitados a certas transportadoras na página do produto.
Os preços em tempo real não aparecem: veja o campo Log na página do módulo. Erros da API são sempre registrados; ative o Debug log para ver cada cálculo. Motivos comuns: CEP de entrega ainda não informado, CEP de coleta ausente, chave de API rejeitada (chave errada ou expirada, ou sem acesso à API no seu plano Cargoson), nenhuma transportadora para a rota ou o peso, ou um preço em outra moeda. Com Cargoson live prices, fixed prices if the API fails, os clientes continuam vendo o preço fixo enquanto você resolve o problema.
A Cargoson rejeita o tipo de pacote: use o código de pacote que a sua conta Cargoson utiliza em Package type code. O motivo aparece no log.
Preço em outra moeda é rejeitado: defina Price currency como a moeda dos seus preços da Cargoson e informe a Currency conversion rate.
O imposto é cobrado duas vezes sobre o frete: seus preços da Cargoson já incluem os impostos. 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 os preços da Cargoson em cache.
A página diz que a transportadora Cargoson não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Cargoson e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. Os preços em cache são sempre removidos. Se Remove data on uninstall estiver ativado, a transportadora é excluída (os pedidos mantêm o histórico), e as configurações, as cotações dos pedidos e o log são removidos. Se estiver desativado, a transportadora apenas é desativada, as configurações e as cotações dos pedidos realizados são mantidas, e somente as cotações de carrinhos sem pedido são removidas. Ao instalar o módulo novamente, a transportadora salva recebe seu status anterior; portanto, Reset não ativa uma transportadora que você tenha desativado.
A Cargoson é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela Cargoson.