VibeFox FedEx for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

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 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. Chaves de teste funcionam somente com Sandbox ativado; chaves de produção, somente com ele desativado. O plugin 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ê usa apenas preços fixos, não precisa das chaves FedEx.

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

Instalação

1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta vfd_fedex para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox FedEx, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Digite a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Digite a API Key, a Secret Key, o número da conta FedEx de 9 dígitos e o endereço Ship from (CEP e, para os EUA e o Canadá, a sigla de 2 letras do estado). Desative Sandbox ao usar chaves de produção.

6. Adicione o VibeFox FedEx a uma zona de envio em WooCommerce > Settings > Shipping > Shipping zones, ou ative Ignore shipping zones e escolha os países.

7. Opcionalmente, digite preços fixos como alternativa.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Shipping > VibeFox FedEx. Elas valem para todas as zonas de envio. Quando você adiciona o método a uma zona, a janela da zona tem apenas um campo:

Title (zone): o nome desta opção na finalização de compra. Deixe em branco para usar o Name global.

No topo da página, o plugin mostra avisos: só 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 é exibido), falta o CEP de origem, falta o estado de origem para os EUA ou o Canadá, ou a moeda da loja é diferente da moeda da conta FedEx sem uma taxa de câmbio. Sempre que você salva as configurações, o token da FedEx e as tarifas em cache são limpos. Os campos numéricos aceitam ponto ou vírgula decimal. Um número inválido não é salvo e é informado.

General

Enable/Disable: ativa ou desativa o envio FedEx em todas as zonas de uma vez. Padrão: ativado.

Name: o nome do método de envio exibido ao cliente na finalização de compra. Padrão: FedEx.

Tax status: Taxable permite que o WooCommerce adicione imposto ao custo do envio, então é usada a cobrança FedEx sem impostos. None usa a cobrança líquida da FedEx como está. Padrão: Taxable.

API FedEx (tarifas em tempo real)

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

Sandbox: usa o sandbox da FedEx com chaves de teste. Desative para obter tarifas reais 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.

FedEx account number: a conta de envio FedEx de 9 dígitos vinculada ao projeto.

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 residencial). Desative se você envia principalmente para empresas. Padrão: ativado.

Box size: dimensões opcionais da caixa na unidade de medida 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 da loja.

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

Envio de

O endereço de onde a FedEx coleta os pacotes ou onde você os deixa. É 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.

Preços fixos

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

Country prices: o preço na moeda da sua loja por país de destino, uma linha por país no formato CC=PREÇO, por exemplo US=12.99 ou CA=19,99. Use * para qualquer outro país, por exemplo *=29.99. Linhas em outro formato são ignoradas e informadas ao salvar.

Fallback cost: um preço fixo quando nenhum preço por país corresponde. Deixe em branco para ocultar o método.

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

Condições

Free shipping from: o subtotal do carrinho a partir do qual este método é gratuito. Deixe em branco para nunca oferecer frete grátis.

Minimum subtotal: exibe o método somente se o subtotal do carrinho for pelo menos este valor. Deixe em branco para exibi-lo sempre.

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

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

Default product weight (kg): o peso usado para produtos sem peso, para as tarifas FedEx e para os limites de peso acima. Padrão: 0.5.

Excluded shipping classes: oculta o método se o carrinho tiver um produto de qualquer uma destas classes de envio do WooCommerce.

Disponibilidade sem zonas de envio

Ignore shipping zones: oferece o método para os países abaixo mesmo sem ele ser adicionado a uma zona de envio. Um método de zona desativado na sua zona continua desativado.

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

Avançado

Debug log: registra as requisições à API e o cálculo das tarifas em WooCommerce > Status > Logs, origem vfd-fedex. Erros da API são sempre registrados. Chaves, tokens e endereços de clientes nunca são registrados.

Remove data on uninstall: quando ativado, excluir o plugin remove todas as suas configurações e métodos de zona. Desativar o plugin nunca apaga configurações.

Como funciona na finalização de compra

Quando o cliente informa um endereço de entrega, o WooCommerce pede uma tarifa ao plugin. O plugin verifica primeiro o peso do carrinho, o subtotal mínimo e as classes de envio excluídas. Se o frete grátis se aplicar, o cliente vê o método como FedEx (Free) e nenhuma requisição é enviada à FedEx.

Caso contrário, o plugin 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 em lb para lojas que usam lb ou oz), o tamanho da caixa, se definido, e a moeda da sua loja como moeda preferencial. Para países que usam 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 retorna os serviços disponíveis. Para cada serviço, o plugin pega a tarifa da conta ou de lista que você escolheu, prefere uma tarifa na moeda da sua loja, 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 é exibido sob o nome do seu método, e o nome dele é salvo na linha de envio do pedido.

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 indisponibilidade 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 o método é ocultado.

O método funciona na finalização de compra clássica e na finalização de compra em blocos. É compatível com o WooCommerce High-Performance Order Storage (HPOS).

O plugin calcula apenas as 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.

Chave de licença

O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Shipping > VibeFox FedEx. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa e o seu domínio. Use Check now para verificar o status novamente, Change key para digitar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta na vibefox.net.

Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga de domínio. Libere a vaga na sua conta na vibefox.net.

Sem uma chave ativa, a FedEx não é exibida aos clientes na finalização de compra. Os gerentes da loja conectados ainda a veem, marcada como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática em segundo plano.

Solução de problemas

A FedEx não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o método foi adicionado à zona do país do cliente (ou se Ignore shipping zones está ativado e o país é permitido). Confira os avisos no topo da página de configurações, os limites de peso, Minimum subtotal e Excluded shipping classes. Sem tarifa em tempo real, o método precisa de um preço por país, de uma linha * ou de um Fallback cost.

As tarifas em tempo real não aparecem: ative o Debug log, recarregue a finalização de compra e abra WooCommerce > Status > Logs, origem vfd-fedex. Ali são registrados as chaves erradas, o ambiente errado (chaves de teste com Sandbox desativado, ou chaves de produção com ele ativado) e os códigos de erro da FedEx.

Minha loja não está em USD: a FedEx é consultada para uma tarifa na moeda da loja. Se a sua conta retorna 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, então um valor em USD nunca é exibido em euros.

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

As tarifas parecem desatualizadas depois de uma mudança: depois de alterar as chaves, o cache é limpo automaticamente. Você também pode clicar em Clear cached FedEx token and rates.

Somente alguns serviços devem ser oferecidos: desenvolvedores podem restringir os serviços com o filtro vfd_fdx_allowed_services.

O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta na vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave para o novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todas as configurações e apenas limpa os tokens e as tarifas em cache. Para removê-lo, desative e exclua-o na página Plugins. A chave de licença e o status da licença deste plugin, os tokens e as tarifas em cache e os arquivos de log antigos são sempre removidos. As configurações e os métodos de zona são removidos somente se Remove data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação posterior. Os pedidos existentes mantêm suas linhas de envio.

FedEx é uma marca comercial de seu respectivo proprietário. Este plugin não é afiliado à FedEx nem endossado por ela.