VibeFox Shippo for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões anteriores do PHP.
Conta Shippo: crie uma conta na Shippo, conecte ou ative as transportadoras (USPS, UPS, FedEx, DHL e outras) e copie o token de API em Shippo > Settings > Advanced > API. A Shippo cobra pelas etiquetas compradas, não pelas requisições de tarifas. Contas novas na Shippo podem precisar ser verificadas pela Shippo antes que as tarifas em tempo real sejam retornadas. Sem token, são usados apenas os preços de contingência.
Produtos: os produtos devem ter peso e dimensões. Produtos sem dimensões usam a caixa padrão.
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 upload terminar, clique em Configure, ou encontre depois o VibeFox Shippo 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. Cole seu token de API da Shippo e preencha o endereço em Ship from. O código postal é obrigatório para tarifas em tempo real.
5. Escolha a Shippo rate currency (USD se você envia dos EUA) e, se a moeda padrão da sua loja for diferente, informe a Exchange rate.
6. Opcionalmente, informe preços de contingência na tabela de país e peso e depois clique em Save.
Na instalação, o módulo cria a transportadora Shippo Shipping com o texto de prazo de entrega Shippo carriers (USPS, UPS, FedEx, DHL). 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 Shippo > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa as tarifas da Shippo em cache.
Os avisos no topo da página informam quando a transportadora nunca poderá ser exibida ou quando as tarifas em tempo real não podem ser usadas: falta o token de API, falta o código postal ou o país de origem, falta a taxa de câmbio, ou a unidade de peso ou de dimensão da loja não é uma que o módulo reconhece (defina kg, g, lb ou oz e cm, mm, m ou in em International > Localization, unidades locais). Um aviso lembra quando um token de teste está definido. Ao salvar, um valor que não é número, um número negativo ou um Minimum weight (kg) maior que Maximum weight (kg) é informado como erro, e nada é salvo até você corrigir.
Geral
Enable Shippo shipping: liga ou desliga a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Name: o nome da transportadora mostrado ao cliente na finalização de compra. Padrão: Shippo Shipping. Obrigatório, no máximo 64 caracteres.
Tax: a regra de imposto da transportadora, ou No tax. As tarifas da Shippo não incluem imposto sobre vendas. No tax as mostra como cotadas; uma regra de imposto acrescenta imposto sobre o frete de acordo com suas regras fiscais.
Conta Shippo
API token: seu token de API da Shippo. Use o token ao vivo (shippo_live_...) para tarifas reais na loja em produção, ou um token de teste (shippo_test_...) para as tarifas de teste da Shippo. O token é enviado somente à Shippo e nunca é registrado em log. Depois de salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo somente para alterá-lo, ou marque Remove the saved API token para excluí-lo.
Allowed carriers / services: opcional, separado por vírgulas. Informe uma transportadora como a Shippo a nomeia (USPS, UPS, FedEx, DHL Express) ou um token de nível de serviço da Shippo (usps_priority, ups_ground). A tarifa permitida mais barata é exibida. Deixe vazio para exibir a tarifa mais barata de qualquer transportadora.
Origem do envio (o endereço de onde seus pacotes são enviados; campos vazios são preenchidos com o endereço da loja em Shop Parameters > Contact > Stores quando estiver no mesmo país)
Sender name / company: o nome do remetente. Ele também é usado para assinar a declaração alfandegária. Se estiver vazio, é usado o nome da loja.
Street address: a rua do remetente.
City: a cidade do remetente.
State / province: o código do estado com duas letras, por exemplo CA ou NY. Algumas transportadoras precisam dele.
Postal / ZIP code: obrigatório para tarifas em tempo real.
Country: o país de onde você envia. Padrão: Estados Unidos.
Tarifas
Parcels: como o carrinho é enviado à Shippo.
Default box size: comprimento x largura x altura na unidade de dimensão da sua loja (mostrada no nome do campo), por exemplo 30 x 20 x 10. A Shippo precisa do tamanho da caixa. Ele é usado quando um produto do carrinho não tem dimensões. Deixe vazio para usar 30 x 20 x 10 cm. Um valor que não pode ser lido é ignorado com um aviso após salvar.
Shippo rate currency: a moeda em que a Shippo cota suas transportadoras, que é a moeda do país de origem: USD (EUA), CAD (Canadá), GBP (Reino Unido), EUR (zona do euro) ou AUD (Austrália). Padrão: USD. As tarifas que a Shippo devolve na moeda padrão da sua loja são sempre usadas como estão.
Exchange rate: o preço de 1 unidade da moeda de tarifa da Shippo na moeda padrão da sua loja, por exemplo 0.92. Não é necessário quando as duas moedas são iguais. Sem ele, as tarifas na outra moeda não são usadas e valem os preços de contingência. O módulo não converte moedas automaticamente.
Preços de contingência (usados quando não há tarifa em tempo real: sem token de API, Shippo inacessível, token rejeitado ou sem tarifas de transportadoras para o endereço; preços na moeda padrão da sua loja, sem impostos; deixe os dois campos vazios para ocultar a transportadora nesse caso)
Country prices: uma tabela de preços por país e peso do carrinho. Clique em Add country para adicionar uma linha e no ícone de lixeira para remover uma. As colunas são Price e as faixas de peso XS (até 1 kg), S (até 2 kg), M (até 3 kg), L (até 5 kg) e XL (acima de 5 kg). Uma faixa vazia ou 0 usa a coluna Price. A linha * Default se aplica a países sem linha própria. Uma linha nova começa como * Default. Uma linha salva com todas as células vazias cobra 0, então exclua as linhas que você não preencher.
Other countries: o preço para países que não estão na tabela acima (quando não há linha * Default). Deixe vazio para ocultar a transportadora para eles.
Condições
Free shipping from: o subtotal do carrinho (após descontos, antes de impostos) a partir do qual o frete é grátis. Nesse caso nenhuma requisição é feita à Shippo. Deixe vazio para desativar.
Minimum subtotal: mostra a transportadora somente se o subtotal do carrinho (após descontos, antes de impostos) for pelo menos esse valor. Deixe vazio para sempre mostrar.
Minimum weight (kg): o peso mínimo do carrinho para mostrar a transportadora. 0 significa sem limite.
Maximum weight (kg): a transportadora fica oculta acima desse peso do carrinho. Padrão: 30. 0 significa sem limite. Campo vazio é salvo como 30.
Disponibilidade sem zonas de envio
Normalmente a transportadora é oferecida em suas zonas de envio em Shipping > Carriers. Alternativamente, ela pode ser oferecida por país, independentemente das zonas.
Ignore shipping zones: oferece a transportadora para os países abaixo, esteja ou não atribuída a zona deles. Enquanto estiver ativado, a transportadora é adicionada a todas as zonas, inclusive às criadas depois. Desativando, as zonas adicionadas são removidas e a transportadora mantém as próprias zonas.
Countries: os países de destino para esse modo. Deixe vazio para usar todos os países ativos da loja. Este campo só é usado quando Ignore shipping zones está ativado.
Avançado
Debug log: registra as requisições à Shippo em logs/vfd_shpo_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros de API são sempre registrados, mesmo com esta opção desativada. O token de API e os endereços dos clientes 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, desinstalar o módulo exclui as configurações do módulo, a transportadora e o log. Quando desativado, tudo é mantido para uma reinstalação. As tarifas em cache são sempre removidas. A transportadora e o serviço salvos com os pedidos fazem parte do histórico de pedidos e são mantidos.
Como funciona na finalização de compra
Na etapa de envio, o PrestaShop pede ao módulo o preço da Shippo. Somente produtos físicos contam: produtos virtuais não somam peso e não entram no subtotal. O módulo verifica primeiro as condições: os países de Ignore shipping zones, o peso do carrinho e o subtotal mínimo. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada à Shippo.
Depois, o módulo envia à Shippo o endereço de origem, o endereço do cliente e o pacote. Para países onde o PrestaShop exige código postal, a requisição aguarda até o cliente informá-lo. Para envios internacionais, é adicionada uma declaração alfandegária com nomes, quantidades, pesos e valores dos itens. A Shippo devolve as tarifas das suas transportadoras, e o módulo usa a tarifa permitida mais barata. O preço é calculado na moeda padrão da sua loja e depois exibido na moeda do carrinho do cliente.
No modo por pedido, os itens são empilhados em uma caixa: os lados mais longo e intermediário dos maiores itens, e os lados menores de todas as unidades somados. Se algum produto não tiver dimensões, a caixa padrão é usada para todo o pacote. No modo por item, cada produto é cotado como um pacote próprio e a tarifa é multiplicada pela quantidade.
Cada resposta fica em cache por 1 hora por endereço e pacote. Quando a Shippo responde sem uma tarifa utilizável, o endereço é lembrado por 10 minutos. Após um timeout, token rejeitado, erro de servidor ou limite de requisições, o módulo pausa as requisições por 5 minutos e usa os preços de contingência. O timeout da requisição é de 10 segundos.
Se não houver tarifa em tempo real, o preço vem da tabela de contingência e, depois, de Other countries. Se nenhuma se aplicar, a transportadora fica oculta. O cliente nunca vê um erro. 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 segue a nova versão automaticamente.
O módulo calcula apenas tarifas. Ele não compra etiquetas, não rastreia pacotes, não valida endereços e não oferece pontos de retirada ou de entrega, seguro, opções de assinatura ou etiquetas de devolução. Somente a tarifa permitida mais barata é exibida, e não uma lista de todos os serviços. Não há embalagem de caixas além do empilhamento descrito acima, nem acréscimo na tarifa ou taxa de manuseio.
Pedidos
Quando um pedido é feito com uma tarifa em tempo real da Shippo, o módulo mantém a Carrier / service escolhida e, para um pacote por pedido, os Estimated delivery days. Eles aparecem no bloco Shippo na página do pedido no back office, para que você possa comprar a etiqueta correspondente na Shippo. Os dados são congelados com o pedido: alterações posteriores no carrinho não os mudam. Pedidos com preço de contingência ou frete grátis não têm bloco Shippo.
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 Shippo é o primeiro bloco da página Modules > Module Manager > VibeFox Shippo > 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 estão a linha Product: presta-shipping-shippo e o link Manage licenses and domains in your account, que abre a sua conta do 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 do vibefox.net.
Sem uma chave ativa, a transportadora Shippo 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 precisam de 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 é 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 Shippo não aparece na finalização de compra: verifique se a licença está ativa e se Enable Shippo shipping 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á ativado e o país é permitido). Confira os limites de peso e o Minimum subtotal. Sem tarifa em tempo real, verifique se o país, * Default ou Other countries tem um preço. Produtos também podem ser limitados a determinadas transportadoras na página do produto.
As tarifas em tempo real não aparecem: ative o Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo. Motivos comuns: falta o token de API ou o código postal de origem, a moeda padrão da loja é diferente da moeda de tarifa da Shippo sem taxa de câmbio, o código postal do cliente ainda não foi informado, nenhuma transportadora da sua conta Shippo atende o endereço, ou a conta Shippo ainda não foi verificada.
Tarifas de teste na loja em produção: um token de teste (shippo_test_...) retorna tarifas de teste da Shippo. Use o token ao vivo (shippo_live_...).
Frete grátis para países inesperados: verifique a tabela de preços em busca de uma linha vazia, especialmente uma linha * Default vazia. Uma linha com todas as células vazias cobra 0.
As tarifas parecem desatualizadas após uma alteração: clique em Save na página do módulo. Isso limpa as tarifas da Shippo em cache.
A página diz que a transportadora Shippo 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 Shippo e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. As tarifas em cache são sempre removidas. Se Remove data on uninstall estiver ativado, a transportadora é excluída (os pedidos mantêm o histórico) e as configurações e o log são removidos. Se estiver desativado, a transportadora é apenas desativada e todas as configurações são mantidas. Reinstalar o módulo devolve à transportadora o status que ela tinha antes. Os pedidos existentes mantêm os dados de transportadora e serviço da Shippo.
A Shippo é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela Shippo.