VibeFox FedEx for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 ou superior (testado na 4.1.0.3).

PHP: 8.0 ou superior com a extensão cURL.

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

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.

Instalação

O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3 vfd_fedex-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_fedex.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_fedex-oc3-(version).ocmod.zip. A extensão não adiciona modificações OCMOD, então você não precisa atualizar Extensions > Modifications. Em vez do instalador, você também pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox FedEx e clique em Install (o botão verde +).

3. Clique em Edit (o botão com lápis) para abrir a página de configurações.

4. Informe a sua chave de licença VibeFox em License key no bloco de licença no topo da página Edit e clique em Activate (veja Chave de licença).

5. Informe 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á, o estado com 2 letras). Desative Sandbox ao usar chaves de produção. Opcionalmente, informe preços fixos como alternativa. Ative Enable/Disable e clique em Save.

OpenCart 4

1. No administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_fedex.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão do nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox FedEx, clique em Install (o botão verde +) e depois em Edit (o botão com lápis).

4. Informe a chave de licença e as configurações como nos passos 4 e 5 do OpenCart 3. A página de configurações e os seus campos são os mesmos nas duas versões.

Após a instalação, o método fica desativado até que você ative Enable/Disable e salve. Se você reinstalar a extensão depois de desinstalá-la, as configurações da FedEx que você manteve voltam a ser usadas.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Shipping > VibeFox FedEx > Edit. As seções ficam listadas à esquerda. Um botão Save no final salva a página inteira sem recarregá-la. Cada salvamento também limpa o token e as tarifas da FedEx em cache. Somente administradores com a permissão de modificação para esta extensão podem salvar as configurações.

No topo da página, a extensão 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 o método nunca aparece), não há CEP de origem, não há estado de origem para os EUA ou o Canadá, a moeda da loja não tem taxa de câmbio para tarifas na moeda da conta FedEx, uma unidade de peso que a extensão não reconhece quando não há uma classe de peso em kg (adicione uma em System > Localisation > Weight Classes) ou, com um tamanho de caixa, uma unidade de comprimento que ela não reconhece. Os campos numéricos aceitam ponto ou vírgula decimal. Ao salvar, um número ou tamanho de caixa inválido, uma taxa de câmbio igual a 0, uma moeda de conta que não seja um código de 3 letras, ou um nome ou ordem de classificação inválidos são informados e não são salvos; o campo mantém o valor anterior e os demais campos são salvos (The other settings were saved.). Um peso mínimo maior que o máximo também é informado, e os dois pesos mantêm os valores anteriores.

Geral

As configurações se aplicam a todas as zonas geográficas. A FedEx é oferecida no checkout como uma única opção de envio: o serviço FedEx mais barato, ou o preço fixo quando a FedEx não retorna uma tarifa.

Enable/Disable: ativa ou desativa o envio pela FedEx no checkout. Padrão: desativado.

Name: o nome do método de envio exibido ao cliente no checkout, com no máximo 64 caracteres, sem < > ; = # { }. Padrão: FedEx. Obrigatório.

Tax class: a classe de imposto do custo de frete, ou No tax (padrão). Com uma classe de imposto, o OpenCart acrescenta imposto ao custo de frete, então é usado o valor da FedEx sem impostos. Com No tax, o valor líquido da FedEx é usado como está.

Sort order: a posição da FedEx entre os métodos de envio no checkout. Um número inteiro.

API da FedEx (tarifas em tempo real)

A seção traz um link para o FedEx Developer Portal. Sem chaves, são usados os preços fixos.

Sandbox: usa o sandbox da FedEx (apis-sandbox.fedex.com) com chaves de teste. Desative para obter 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. Limpá-la também remove a Secret Key salva.

Secret Key: a Secret Key (client_secret) do mesmo projeto. Após salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Clearing the API Key removes it too. Digite um novo valor somente para alterá-la.

FedEx account number: a conta de envio FedEx de 9 dígitos vinculada ao projeto. As tarifas de 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, sobretaxa residencial). Desative se você envia principalmente para empresas. Padrão: ativado.

Box size (L x W x H): dimensões opcionais da caixa na unidade de comprimento da loja indicada no nome do campo, por exemplo 30x20x15. A FedEx então aplica o peso dimensional. Deixe vazio para cotar somente 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 consultada para cotar também na moeda padrão da loja.

Exchange rate: só é necessária quando a FedEx retorna tarifas apenas na moeda da conta e a moeda padrão da sua loja é diferente: o preço de 1 unidade da moeda da conta na moeda padrão da sua loja, por exemplo 0.92. Sem ela, essas tarifas não são usadas, e um valor em outra moeda nunca é mostrado como se fosse a sua moeda.

Cache: o botão Clear cached FedEx token and rates esvazia o cache imediatamente. Os tokens da FedEx ficam em cache até expirar, as tarifas por 1 hora e as solicitações com falha por 5 a 10 minutos.

Ship from

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

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

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

City: a cidade de origem do envio.

ZIP / postal code: o CEP de origem. A FedEx precisa dele para cotar as tarifas. O OpenCart não tem CEP da loja, então informe-o aqui.

Preços fixos

Usados quando nenhuma chave de API é informada e como alternativa quando a FedEx não retorna uma tarifa (API fora do ar, chaves erradas, nenhum serviço). Deixe os dois campos vazios para ocultar o método nesse caso.

Country prices: uma lista de países de destino e preços na moeda padrão da sua loja, sem impostos. Clique em Add row para adicionar uma linha e no botão × para removê-la. Escolha * Any other country para um preço usado em qualquer país sem linha própria. Linhas sem país ou preço válidos 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 o método.

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

Condições

Free shipping from: o subtotal dos produtos que precisam de envio (depois do cupom, antes dos impostos) a partir do qual este método é grátis. Nesse caso, nenhuma solicitação é enviada à FedEx. Deixe vazio para nunca oferecer frete grátis.

Minimum subtotal: mostra o método somente se o mesmo subtotal for pelo menos este valor. Deixe vazio para sempre mostrá-lo.

Min weight (kg): o peso mínimo do carrinho para o método aparecer. 0 significa sem limite (padrão).

Max weight (kg): o peso máximo do carrinho. O método fica oculto se for ultrapassado. 0 significa sem limite (padrão).

Default product weight (kg): o peso usado para produtos sem peso, nas tarifas da FedEx e nos limites de peso acima. Padrão: 0.5; um campo vazio também significa 0.5 kg. Os pesos dos produtos são convertidos a partir da classe de peso de cada produto.

Geo zone: oferece a FedEx somente para endereços desta zona geográfica. All zones (padrão) significa sem limite. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones. Não é usada quando Ignore shipping zones está ativado.

Disponibilidade sem zonas de envio

Ignore shipping zones: não verifica a zona geográfica; oferece o método para os países abaixo. Padrão: desativado.

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

Avançado

Debug log: grava as solicitações à API e os cálculos de tarifas em storage/logs/vfd_fdx_debug.log.php (no OpenCart 4 system/storage/logs/vfd_fdx_debug.log.php). O arquivo não pode ser lido pela web. Os erros da API são sempre registrados, mesmo com o log desativado. Chaves, tokens, o número da conta e os endereços dos clientes nunca são registrados. Quando o arquivo chega a 5 MB, ele é movido para vfd_fdx_debug.old.log.php e um novo log é iniciado.

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

Remove data on uninstall: quando ativado, desinstalar a extensão apaga as configurações da FedEx, os tokens e tarifas em cache e o log. Quando desativado (padrão), tudo é mantido para uma reinstalação. As tarifas da FedEx dos pedidos realizados são sempre mantidas.

Importar / Exportar

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A Secret Key não é exportada.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações, por exemplo em outra loja. Os valores são verificados como em um salvamento normal. A Secret Key salva é mantida.

Como funciona no checkout

Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço da FedEx. Se uma Geo zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, a FedEx não é oferecida. Só contam os produtos com Requires Shipping definido como Yes: os demais não somam peso e não entram no subtotal. O subtotal é o preço desses produtos depois do desconto do cupom e antes dos impostos; vales-presente, pontos de fidelidade e crédito da loja não são considerados. Em seguida, a extensão verifica 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 solicitação é enviada à FedEx.

Caso contrário, se a API Key, a Secret Key e o número da conta estiverem definidos, a extensão obtém um token OAuth e envia à Rate API da FedEx o endereço de origem, o endereço de destino, o peso do carrinho (em kg, ou em lb para lojas cuja classe de peso seja lb ou oz), o tamanho da caixa se estiver definido, e a sua moeda padrão como moeda preferida. Para países com Postcode Required ativado no OpenCart, a solicitação só é feita depois que o cliente informa um CEP. Para envios internacionais, é enviado o valor aduaneiro do carrinho. Códigos de estado são enviados somente para os EUA e o Canadá.

A FedEx retorna os serviços disponíveis. Para cada serviço, a extensão pega a tarifa de conta ou de tabela 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. É usado o serviço mais barato. O preço é arredondado para as casas decimais da sua moeda padrão e mostrado ao cliente na moeda dele, com o imposto da Tax class selecionada.

O token fica em cache até expirar e é solicitado novamente automaticamente quando a FedEx o rejeita. As cotações ficam em cache por 1 hora. Uma solicitação de tarifa com falha fica lembrada por 10 minutos, e uma solicitação de token com falha por 5 minutos, para que uma queda não atrase cada atualização do checkout. O tempo limite da API é de 15 segundos. Se a FedEx não responder, o cliente não vê nenhum erro: é usado o preço fixo, ou o método fica oculto. O motivo é gravado no log de depuração.

A extensão apenas calcula tarifas. Ela não cria envios FedEx, não imprime etiquetas, não agenda coletas, não rastreia encomendas e não permite que os clientes escolham uma unidade FedEx. Ela mostra uma opção (o serviço mais barato), não várias, e não há empacotamento em caixas: o carrinho é cotado como um único pacote.

No OpenCart 4, o cliente clica em Choose no bloco de métodos de envio da página de checkout e escolhe a FedEx na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.

Pedidos

Quando um pedido com a FedEx é feito, a tarifa mostrada ao cliente é salva com o pedido. Em Sales > Orders, a página do pedido tem um painel FedEx shipping. Ele mostra o FedEx service da tarifa (para tarifas em tempo real), o 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 congelados quando o pedido é feito: alterações posteriores nas configurações não os modificam. No OpenCart 4, para o checkout é mantido um único pedido, que é atualizado sempre que o cliente confirma novamente: a tarifa da FedEx salva é atualizada junto com ele e removida quando o cliente muda para outro método de envio.

Chave de licença

A extensão funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox FedEx é o primeiro bloco em Extensions > Extensions > Shipping > VibeFox FedEx > Edit, 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 aparecem a linha Product: opencart-shipping-fedex e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do administrativo (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 com uma data. Depois que o endereço da loja mudar, ou depois de liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um único domínio: o endereço da loja na configuração do OpenCart. Remover a chave da loja não libera a sua vaga de domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, o método de envio FedEx não é mostrado aos clientes no checkout e nenhuma tarifa é calculada. Um usuário administrador que esteja conectado ao administrativo no mesmo navegador ainda vê o método na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 essa prévia não está disponível: a loja não enxerga o login do administrativo, por isso, sem uma chave ativa, o método fica oculto para todos. Depois de abrir a página Edit uma vez, um lembrete aparece no Dashboard do administrativo. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente automaticamente quando você abre o Dashboard do administrativo ou a página Edit: uma vez por dia nos primeiros 14 dias após informar a chave e, depois, uma vez por semana. Não é preciso nenhum cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

A FedEx não aparece no checkout: verifique se a licença está ativa e se Enable/Disable está ativado. Verifique Geo zone, ou Ignore shipping zones e Countries. Verifique os avisos no topo da página da extensão, os limites de peso e Minimum subtotal. Sem tarifa em tempo real, o método precisa de um preço por país, de uma linha * Any other country ou de um Fallback cost. Verifique se os produtos têm Requires Shipping definido como Yes.

As tarifas em tempo real não aparecem: ative Debug log, recarregue o checkout e veja o campo Log na página da extensão. Ali são registrados chaves erradas, o ambiente incorreto (chaves de teste com Sandbox desativado, ou chaves de produção com ele ativado), um CEP de entrega ausente e os códigos de erro da FedEx.

Minha loja não está em USD: a FedEx é consultada para a tarifa na moeda padrão da sua loja. Se a sua conta retornar apenas a moeda dela, defina FedEx account currency e Exchange rate. Sem taxa de câmbio, essas tarifas são ignoradas e o preço fixo é usado, de modo que um valor em USD nunca é mostrado como euro.

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

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

A página diz "Warning: You do not have permission to modify VibeFox FedEx!": o seu grupo de usuários administradores pode apenas visualizar as configurações. Conceda ao grupo a permissão de modificação para extension/shipping/vfd_fedex (OpenCart 3) ou extension/vfd_fedex/shipping/vfd_fedex (OpenCart 4) em System > Users > User Groups.

Para desenvolvedores: outras extensões podem alterar o endereço da API, os serviços FedEx permitidos e a solicitação de tarifa pelos eventos do OpenCart vfd_fedex/api_base_url, vfd_fedex/allowed_services e vfd_fedex/rate_request (registrados como catalog/vfd_fedex/...); a configuração vfd_fdx_api_url substitui o endereço da API para testes e não tem campo na página de configurações.

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox FedEx. O OpenCart sempre redefine Enable/Disable, Sort order, Tax class e Geo zone. Os tokens e tarifas em cache são sempre removidos. Se Remove data on uninstall estiver ativado, as configurações da FedEx e o log de depuração também são excluídos. Se estiver desativado, as demais configurações são mantidas e voltam a ser usadas quando você reinstalar a extensão. As tarifas da FedEx dos pedidos realizados são mantidas nos dois casos, e os pedidos mantêm o método e o custo de envio.

No OpenCart 4, para remover também os arquivos da extensão, vá em Extensions > Installer depois da desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox FedEx na lista de extensões instaladas e, em seguida, em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

A FedEx é uma marca de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela FedEx.