VibeFox FedEx for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior com a extensão cURL. Sem elas, o módulo se recusa a instalar.

Conta FedEx e chaves de API (apenas para tarifas em tempo real): no FedEx Developer Portal (developer.fedex.com), crie um projeto com a Rate API, vincule sua conta de envio FedEx e copie a API Key e a Secret Key. Você também precisa do número da conta FedEx de 9 dígitos. As chaves de teste funcionam somente com Sandbox ativado; as de produção, somente com ele desativado. O módulo usa a REST API da FedEx com OAuth 2.0; ele não precisa de número de medidor nem de senha dos web services. Se você usar apenas preços fixos, não precisa das chaves da FedEx.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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 encontre VibeFox FedEx depois na lista de módulos e clique em Configure.

3. Digite 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. Digite a API Key, a Secret Key, o número da conta FedEx de 9 dígitos e o endereço de Ship from (CEP e, para os EUA e o Canadá, a sigla do estado com 2 letras). Desative Sandbox se estiver usando chaves de produção. Opcionalmente, digite preços fixos como alternativa. Clique em Save.

Ao instalar, o módulo cria a transportadora FedEx com o texto de prazo de entrega FedEx delivery. 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 FedEx > 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. Cada salvamento também limpa o token e as tarifas da FedEx em cache.

No topo da página, o módulo mostra avisos: apenas algumas das três credenciais de API estão preenchidas, não há chaves de API nem preços fixos (nesse caso a transportadora nunca é exibida), não há CEP de origem, não há estado de origem para os EUA ou o Canadá, a moeda da loja é diferente da moeda da conta FedEx sem taxa de câmbio, a unidade de peso da loja (ou, com um tamanho de caixa, a unidade de dimensão) não é reconhecida pelo módulo, ou há uma transportadora excluída. Os campos numéricos aceitam ponto ou vírgula decimal. Um número ou tamanho de caixa inválido, uma taxa de câmbio de 0, uma moeda da conta que não seja um código de 3 letras e um nome com mais de 64 caracteres não são salvos e são informados; o campo mantém o valor anterior e os demais campos são salvos. Um peso mínimo maior que o peso máximo também é informado, e ambos os pesos mantêm os valores anteriores.

Geral

Enable/Disable: liga ou desliga o envio pela FedEx. É o mesmo interruptor do status da transportadora em Shipping > Carriers.

Name: o nome do método de envio exibido ao cliente na finalização de compra (o nome da transportadora). Padrão: FedEx. Obrigatório.

Tax status: a regra de imposto da transportadora, ou No tax. Com uma regra de imposto (e com impostos ativados na loja), o PrestaShop acrescenta o imposto ao custo do frete, então é usado o valor da FedEx sem impostos. Com No tax, o valor líquido da FedEx é usado como está.

API da FedEx (tarifas em tempo real)

Sem chaves, são usados os preços fixos abaixo. A seção tem o botão Clear cached FedEx token and rates.

Sandbox: usa o sandbox da FedEx (apis-sandbox.fedex.com) com chaves de teste. Desative-o para tarifas reais (apis.fedex.com) com chaves de produção. Padrão: ativado.

API Key: a API Key (client_id) do seu projeto no FedEx Developer Portal.

Secret Key: a Secret Key (client_secret) do mesmo projeto. Após salvar, o campo fica vazio e exibe Saved — leave empty to keep it. Digite um novo valor apenas se quiser alterá-lo. Apagar a API Key também remove a Secret Key salva.

FedEx account number: o número da conta de envio FedEx de 9 dígitos vinculada ao projeto. As tarifas da conta (negociadas) são cotadas para ela.

Rates: Account rates (your negotiated FedEx prices) (padrão) ou List rates (FedEx published prices).

Residential delivery: cota os endereços dos clientes como residenciais (FedEx Home Delivery, adicional de entrega residencial). Desative se você enviar principalmente para empresas. Padrão: ativado.

Box size: dimensões opcionais da caixa, na unidade de dimensão da sua loja, por exemplo 30x20x15. Nesse caso, a FedEx aplica o peso dimensional. Deixe em branco para cotar apenas pelo peso.

FedEx account currency: a moeda da sua conta FedEx, por exemplo USD para contas dos EUA ou CAD para o Canadá. Padrão: USD. A FedEx sempre é solicitada a cotar também na moeda padrão da loja.

Exchange rate: necessária apenas quando a FedEx devolve tarifas somente na moeda da conta e a moeda padrão da sua loja é diferente: o preço de 1 unidade da moeda da conta na sua moeda padrão, por exemplo 0.92. Sem ela, essas tarifas não são usadas.

Origem do envio

O endereço de onde a FedEx coleta os pacotes ou onde você os entrega. Usado para as tarifas em tempo real.

Country: o país de onde você envia. Padrão: United States.

State / province code: a sigla de 2 letras, obrigatória para os EUA e o Canadá, por exemplo TN, CA ou ON.

City: a cidade de origem.

ZIP / postal code: o CEP de origem. A FedEx precisa dele para cotar as tarifas.

Preços fixos

São usados quando nenhuma chave de API é informada e como alternativa quando a FedEx não devolve nenhuma tarifa (API fora do ar, chaves incorretas, nenhum serviço disponível). Deixe os dois campos vazios para ocultar a transportadora nesse caso.

Country prices: uma tabela com códigos de país de destino de 2 letras e preços na moeda padrão da sua loja, sem impostos. Clique em Add row para adicionar um país e no ícone da lixeira para remover. Use * como código de país para qualquer outro país. Linhas que não sejam um código de país (ou *) com um preço são ignoradas e informadas ao salvar.

Fallback cost: um preço fixo quando nenhum preço por país corresponde. Deixe vazio para ocultar a transportadora.

Fixed price is: Per order cobra o preço uma vez. Per item (price x number of items) multiplica o preço pelo número de itens no carrinho. Isso vale apenas para preços fixos. As tarifas em tempo real da FedEx são sempre cotadas para o peso total do carrinho.

Condições

Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual esta transportadora é gratuita. Deixe vazio para nunca oferecer frete grátis.

Minimum subtotal: exibe a transportadora somente quando o subtotal do carrinho for pelo menos este valor. Deixe vazio para exibi-la sempre.

Min weight: o peso mínimo do carrinho em kg para que a transportadora apareça. 0 significa sem limite.

Max weight: o peso máximo do carrinho em kg. A transportadora fica oculta se for ultrapassado. 0 significa sem limite.

Default product weight: o peso em kg usado para produtos sem peso, para as tarifas da FedEx e para os limites de peso acima. Padrão: 0.5. Os pesos dos produtos são convertidos a partir da unidade de peso da sua loja (kg, g, lb ou oz), definida em International > Localization (Local units).

Disponibilidade sem zonas de envio

Ignore shipping zones: oferece a transportadora para os países abaixo, mesmo que a zona deles não esteja atribuída a ela. Ao salvar, a transportadora é vinculada a todas as zonas, inclusive às criadas depois. Desativando, a transportadora recupera as zonas anteriores.

Countries: os países de destino para esse modo. Deixe vazio para todos os países da loja. Usado apenas quando Ignore shipping zones está ativado.

Avançado

Debug log: registra as requisições à API e o cálculo das tarifas em logs/vfd_fdx_debug.log.php, dentro da pasta do módulo. O arquivo não pode ser aberto pela web. Erros de API são sempre registrados. Chaves, tokens e endereços de clientes nunca são registrados.

Log: mostra o tamanho e as entradas mais recentes do registro. Clique em Clear log para esvaziá-lo.

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

Como funciona na finalização de compra

Na etapa de envio, o PrestaShop pede ao módulo o preço da FedEx. Somente produtos físicos contam: produtos virtuais não somam peso e não entram no subtotal. O módulo verifica primeiro os países permitidos (com 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 à FedEx.

Caso contrário, o módulo obtém um token OAuth e envia à Rate API da FedEx o endereço de origem, o endereço de entrega, o peso do carrinho (em kg ou, para lojas que usam lb ou oz, em lb), o tamanho da caixa, se definido, e a sua moeda padrão como moeda preferida. Para países que exigem CEP, a requisição só é feita depois que o cliente informa um. Para envios internacionais, é enviado o valor aduaneiro do carrinho. Os códigos de estado são enviados somente para os EUA e o Canadá.

A FedEx devolve os serviços disponíveis. Para cada serviço, o módulo pega a tarifa da conta ou de lista que você escolheu, prefere uma tarifa na sua moeda padrão, converte uma tarifa na moeda da conta FedEx com a sua taxa de câmbio e descarta as tarifas que não consegue converter. O serviço mais barato define o preço, e o preço é exibido na moeda do carrinho do cliente.

O token fica em cache por ambiente e chave e é solicitado novamente de forma automática quando a FedEx o rejeita. As cotações ficam em cache por 1 hora. Uma requisição de tarifa com falha é lembrada por 10 minutos, e uma requisição de token com falha por 5 minutos, para que uma instabilidade não deixe lenta cada atualização da finalização de compra. O tempo limite da API é de 15 segundos. Se a FedEx não responder, o cliente não vê erro: é usado o preço fixo ou a transportadora fica oculta. 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 FedEx, não imprime etiquetas, não agenda coletas, não rastreia encomendas e não permite que o cliente escolha um ponto da FedEx. Ele mostra uma opção (o serviço mais barato), e não várias, e não há empacotamento em caixas: o carrinho é cotado como um único pacote.

Pedidos

Na página do pedido no back office, os pedidos com a transportadora FedEx têm um bloco FedEx shipping. Ele mostra o FedEx service da tarifa (para tarifas em tempo real), a Price source (FedEx live rate, Fixed price (no live rate) ou Free shipping threshold) e o Calculated price (excl. tax) na sua moeda padrão. Os valores são fixados quando o pedido é feito: alterações posteriores nas configurações não os modificam.

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 FedEx é o primeiro bloco de Modules > Module Manager > VibeFox FedEx > 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 estão a linha Product: presta-shipping-fedex 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 FedEx 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 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 informada, 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 FedEx 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 ative Ignore shipping zones e confira Countries). Confira os avisos no topo da página do módulo, os limites de peso e o Minimum subtotal. Sem tarifa em tempo real, a transportadora precisa de um preço por país, de uma linha * ou de um Fallback cost. Além disso, os produtos 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. Ali são registrados chaves erradas, o ambiente errado (chaves de teste com Sandbox desligado, ou chaves de produção com ele ligado), um CEP de entrega ausente e os códigos de erro da FedEx.

Minha loja não está em USD: a FedEx é solicitada a cotar na moeda padrão da sua loja. Se a sua conta devolver apenas a moeda dela, configure FedEx account currency e Exchange rate. Sem taxa de câmbio, essas tarifas são ignoradas e o preço fixo é usado, para que um valor em USD nunca seja mostrado em reais.

"Per item" multiplica a tarifa da FedEx? Não. Per item se aplica apenas aos preços fixos.

As tarifas parecem desatualizadas após uma mudança: salvar a página do módulo limpa o cache. Você também pode clicar em Clear cached FedEx token and rates.

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

Só alguns serviços devem ser oferecidos: os desenvolvedores podem restringir os serviços com o hook actionVfdFdxAllowedServices. Os hooks actionVfdFdxRateRequest e actionVfdFdxApiBaseUrl alteram a requisição de tarifa e o endereço da API.

Desinstalação

Acesse Modules > Module Manager, abra o menu ao lado de VibeFox FedEx e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. Tokens e tarifas 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, o log e os serviços FedEx armazenados dos pedidos são removidos. Se estiver desativado, a transportadora apenas é desativada e todas as configurações são mantidas. Reinstalar o módulo (ou usar Reset) devolve à transportadora salva o status que ela tinha antes da desinstalação.

FedEx é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela FedEx.