VibeFox EasyPost for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior com a extensão cURL. O módulo recusa a instalação sem elas.
Conta EasyPost (apenas para tarifas em tempo real): crie uma conta no site da EasyPost, conecte suas contas de transportadoras (USPS, UPS, FedEx e outras) no painel da EasyPost e copie a chave de API em EasyPost Dashboard > Account Settings > API Keys. A EasyPost cobra pelas etiquetas compradas, não pelas consultas de tarifas. Se você usa apenas as tarifas de contingência, não precisa de uma conta EasyPost.
Produtos: os produtos precisam de peso e, de preferência, de dimensões.
Chave de licença VibeFox: adquirida 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 EasyPost depois na lista de módulos e clique em Configure.
3. Insira sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Cole sua chave de API da EasyPost e preencha o endereço Ship from. O CEP é obrigatório para as tarifas em tempo real.
5. Se a sua moeda padrão não for o USD, informe a USD exchange rate. Opcionalmente, informe as tarifas de contingência (veja Configuração). Clique em Save.
Na instalação, o módulo cria a transportadora EasyPost Shipping com o texto de prazo de entrega Live carrier rate (EasyPost). 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 EasyPost > 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 EasyPost armazenadas em cache.
No topo da página, o módulo mostra avisos quando as tarifas em tempo real não podem ser usadas: sem chave de API (com ou sem tarifas de contingência), sem CEP ou país de origem, ou com moeda padrão diferente de USD sem taxa de câmbio. Também aparece uma nota quando há uma chave de API de teste, um erro quando a transportadora do módulo foi excluída, e um aviso quando a unidade de peso ou de dimensão da sua loja (International > Localization) não é uma que o módulo reconhece (kg, g, lb, oz; cm, mm, m, in).
Ao salvar, um valor que não é um número (ou é negativo) não é gravado: um aviso indica o campo e o valor anterior é mantido. O mesmo acontece quando a USD exchange rate é 0, ou quando o Minimum weight é maior que o Maximum weight.
Geral
Enable EasyPost shipping: ativa ou desativa a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers. Padrão: on.
Name: o nome da transportadora exibido ao cliente na finalização de compra, com no máximo 64 caracteres (um nome maior é recusado e nada é salvo). Padrão: EasyPost Shipping. Se o nome estiver vazio ou tiver caracteres que o PrestaShop não permite no nome de uma transportadora, o nome padrão é usado.
Conta EasyPost
API key: sua chave de API da EasyPost, obtida em EasyPost Dashboard > Account Settings > API Keys. Uma chave de produção (começa com EZAK) retorna tarifas reais. Uma chave de teste (começa com EZTK) retorna tarifas de teste da EasyPost; use-a somente para testes. Depois de salvar, o campo fica vazio e mostra a chave salva mascarada, por exemplo EZAK******abcd. Deixe o campo vazio para mantê-la. Digite um valor novo apenas para alterá-la.
Remove the saved API key: marque esta caixa e clique em Save para excluir a chave salva.
Allowed carriers / services: opcional, separado por vírgulas. Informe uma transportadora (USPS) ou uma transportadora e um serviço (USPS:Priority, UPS:Ground), da forma como a EasyPost os nomeia. A tarifa permitida mais barata é mostrada. Deixe vazio para mostrar a tarifa mais barata de qualquer transportadora.
Origem do envio
O endereço de onde seus pacotes são enviados. Se o Country for o país da sua loja, os campos vazios são preenchidos com o endereço da loja em Shop Parameters > Contact > Stores (e o nome do remetente, com o nome da loja).
Sender name / company: o nome do remetente ou da empresa.
Street address: a rua do endereço de origem.
City: a cidade do endereço de origem.
State: o código do estado com duas letras, por exemplo CA ou NY.
ZIP code: o CEP ou código postal do endereço de origem. Obrigatório para as tarifas em tempo real.
Country: o país de onde você envia. Padrão: United States.
Tarifas
Parcels: como o carrinho é enviado à EasyPost.
Os pesos são convertidos da unidade da sua loja para onças (mínimo 1 oz) e as dimensões para polegadas. Se algum produto não tiver dimensões, o pacote é tarifado apenas pelo peso.
USD exchange rate: as tarifas da EasyPost estão em USD. Informe o preço de 1 USD na sua moeda padrão, por exemplo 0.92. Sem ele, as tarifas em tempo real não são usadas, apenas as de contingência. Não é necessário quando a moeda padrão é o USD. Lojas em USD e CAD pedem à EasyPost que cote na moeda própria. Tanto o ponto quanto a vírgula são aceitos como separador decimal.
Tax: a regra de imposto da transportadora, ou No tax. As tarifas da EasyPost não incluem imposto sobre vendas. Escolha as regras de imposto que se aplicam ao frete.
Tarifas de contingência
Usadas quando não há tarifa em tempo real: sem chave de API, EasyPost inacessível, chave recusada ou nenhuma transportadora com tarifa para o endereço. Os preços são na sua moeda padrão, sem impostos. Deixe os dois campos vazios para ocultar a transportadora nesse caso.
Country prices: uma linha por país: código do país com duas letras, dois-pontos e o preço, por exemplo US:9.99. Linhas em outro formato são ignoradas e listadas em um aviso ao salvar.
Other countries: o preço para os países que não estão na lista acima. Deixe vazio para ocultar a transportadora para eles.
Condições
Free shipping from: o subtotal do carrinho (produtos a enviar, após descontos, antes dos impostos, na sua moeda padrão) a partir do qual o frete é grátis. Nesse caso nenhuma requisição é feita à EasyPost. Deixe vazio para desativar.
Minimum subtotal: mostra a transportadora somente se o subtotal do carrinho (produtos a enviar, após descontos, antes dos impostos) for pelo menos este valor. Deixe vazio para mostrá-la sempre.
Minimum weight: oculta a transportadora quando o carrinho pesa menos, na unidade de peso da sua loja (indicada no rótulo do campo). 0 significa sem limite.
Maximum weight: oculta a transportadora quando o carrinho pesa mais, na unidade de peso da sua loja. 0 significa sem limite.
Disponibilidade sem zonas de envio
Normalmente a transportadora é oferecida nas zonas atribuídas a ela em Shipping > Carriers. Alternativamente, ela pode ser oferecida por país, independentemente das zonas.
Ignore shipping zones: oferece a transportadora para os países indicados abaixo, esteja ou não a zona deles atribuída à transportadora. Ao salvar com esta opção ativada, a transportadora é atribuída a todas as zonas, inclusive às criadas depois. Ao desativá-la, a transportadora recupera as zonas anteriores.
Countries: os países de destino para esse modo. Use Ctrl+clique para selecionar vários. Deixe vazio para usar todos os países ativos da sua loja. Este campo só é usado quando o Ignore shipping zones está ativado.
Avançado
Debug log: grava as requisições à EasyPost em modules/vfd_easypost/logs/vfd_ep.log.php. O arquivo não pode ser aberto pela web e é rotacionado ao atingir 5 MB. Erros da API são sempre registrados, mesmo com esta opção desativada. A chave de API e os endereços dos clientes nunca são registrados.
Remove data on uninstall: quando ativada, ao desinstalar o módulo suas configurações, tabelas e log são excluídos. Desativar o módulo nunca exclui as configurações.
Log: o painel abaixo das configurações mostra as últimas 100 linhas do log. Clique em Clear log para limpá-lo.
Como funciona na finalização de compra
Na etapa de envio, o PrestaShop pede ao módulo o preço da EasyPost. Só contam os produtos físicos: produtos virtuais não somam peso e não entram no subtotal. O módulo verifica primeiro as condições: país de destino (com Ignore shipping zones), peso do carrinho e subtotal mínimo. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada à EasyPost.
Caso contrário, o módulo envia à EasyPost o endereço de origem, o endereço de entrega e o pacote, e recebe as tarifas de todas as suas contas de transportadoras. Ele escolhe a tarifa permitida mais barata, converte-a para a sua moeda padrão e a mostra na moeda do carrinho do cliente. Para países que exigem CEP, a requisição só é feita quando o endereço de entrega tem um. Antes de o cliente informar um endereço, só o país do visitante é conhecido; por isso, nos países que exigem CEP, a tarifa de contingência é usada até que o endereço seja informado.
Cada resposta fica em cache por 1 hora para o mesmo endereço e o mesmo pacote. Um endereço sem tarifas utilizáveis é lembrado por 10 minutos. Após um tempo limite, uma chave recusada, um limite de requisições ou um erro do servidor da EasyPost, nenhuma requisição é feita por 5 minutos. O tempo limite da API é de 10 segundos. Em todos esses casos o cliente não vê nenhum erro: é usada a tarifa de contingência ou, se não houver uma, a transportadora é ocultada. O motivo é gravado no log.
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, não oferece pontos de retirada ou postagem e não adiciona opções de seguro ou assinatura. Mostra uma opção (a tarifa permitida mais barata), não uma lista de serviços. Não há embalagem em caixas além de empilhar os itens em um único pacote, e não há markup de tarifa nem taxa de manuseio.
Pedidos
Quando um pedido com a transportadora EasyPost é feito, a tarifa mostrada na finalização de compra fica armazenada com o pedido. A página do pedido no back office mostra o bloco EasyPost shipping:
Carrier / service: a transportadora e o serviço da EasyPost da tarifa, por exemplo USPS Priority. No modo um pacote por item, todos os serviços usados são listados.
Estimated delivery days: os dias de entrega retornados pela EasyPost (somente no modo um pacote por pedido, quando a EasyPost os retorna).
Price source: Live EasyPost rate, Fallback price (no live rate) ou Free shipping threshold.
Calculated price (excl. tax): o preço na sua moeda padrão.
Alterações posteriores no carrinho pelo back office não mudam esses valores. Use-os para comprar a etiqueta na sua conta EasyPost. As tarifas de carrinhos abandonados são removidas após 30 dias.
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 EasyPost é o primeiro bloco de Modules > Module Manager > VibeFox EasyPost > 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-easypost 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, 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 EasyPost não é mostrada 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ê: você pode 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, depois uma vez por semana. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A EasyPost não aparece na finalização de compra: verifique se a licença está ativa e se Enable EasyPost shipping está ligado. Em Shipping > Carriers, verifique se a transportadora está ativada e cobre a zona do país do cliente e o grupo do cliente (ou se Ignore shipping zones está ativado e o país selecionado). Confira os limites de peso e o Minimum subtotal. Sem tarifa em tempo real, a transportadora precisa de uma tarifa de contingência para o país ou para Other countries. Os produtos também podem ser limitados a determinadas transportadoras na página do produto.
As tarifas em tempo real não aparecem: leia os avisos no topo da página do módulo, depois ative o Debug log, recarregue a finalização de compra e veja o painel Log. Motivos comuns: sem chave de API ou CEP de origem, loja que não usa USD sem a USD exchange rate, o endereço de entrega ainda não tem CEP, nenhuma transportadora da sua conta EasyPost atende o endereço, ou os filtros de Allowed carriers / services excluem todas as tarifas.
As tarifas parecem preços de teste: há uma chave de teste (EZTK...) definida. Use uma chave de produção (EZAK...) na loja em funcionamento.
As tarifas pararam por alguns minutos: após um tempo limite, uma chave recusada ou um erro do servidor da EasyPost, o módulo pausa as requisições por 5 minutos e usa as tarifas de contingência. Verifique a chave de API e o log.
O imposto está incluído? As tarifas da EasyPost não incluem imposto sobre vendas. Escolha a regra de imposto em Tax para adicionar imposto sobre o frete.
As tarifas parecem desatualizadas após uma mudança: clique em Save na página do módulo. Isso limpa as tarifas da EasyPost armazenadas em cache.
A página informa que a transportadora do módulo não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.
Hooks para desenvolvedores: os hooks actionVfdEpShipmentRequest (corpo da requisição), actionVfdEpSelectedRate (tarifa escolhida) e actionVfdEpApiUrl (URL base da API) permitem ajustar o módulo.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox EasyPost e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. A transportadora é removida da finalização de compra (os pedidos mantêm o histórico), e as tarifas em cache são sempre removidas. Se Remove data on uninstall estiver ativado, as configurações, as tarifas salvas dos pedidos e o log também são removidos. Se estiver desativado, as configurações e os dados da EasyPost dos pedidos realizados são mantidos para uma reinstalação. Instalar ou redefinir o módulo cria uma nova transportadora. Se as configurações foram mantidas, ela recebe o status (ativada ou desativada) da transportadora anterior.
EasyPost é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela EasyPost.