VibeFox UPS 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.
Aplicativo no UPS Developer Portal (somente para tarifas em tempo real): faça login no UPS Developer Portal (developer.ups.com), crie um aplicativo com o produto "Rating", vincule a sua conta UPS e copie o Client ID e o Client Secret. O plugin usa OAuth 2.0. Não são necessários Access Key, nome de usuário ou senha. Para as tarifas negociadas, você também precisa do número de conta UPS de 6 caracteres. Sem credenciais, são usados apenas os preços fixos.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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_ups para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox UPS, ou clique em Settings embaixo do nome do plugin na página de 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 o Client ID e o Client Secret, o número da sua conta UPS (para tarifas negociadas) e o endereço Ship from: o CEP e, para os Estados Unidos e o Canadá, a sigla do estado com 2 letras.
6. Se a moeda da sua conta UPS for diferente da moeda da loja, informe UPS account currency e Exchange rate.
7. Adicione VibeFox UPS a uma zona de envio em WooCommerce > Settings > Shipping > Shipping zones, ou ative Ignore shipping zones e escolha os países.
8. Opcionalmente, informe preços fixos como alternativa.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Shipping > VibeFox UPS. Elas valem para todas as zonas de envio. Ao adicionar 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.
Sempre que você salvar as configurações, o token da UPS e as tarifas em cache são apagados. Você também pode clicar em Clear cached UPS token and rates na seção UPS API. Os avisos acima das configurações indicam quando apenas um entre Client ID e Client Secret está preenchido, quando não há credenciais nem preços fixos, quando faltam o CEP ou o estado de origem do envio, quando as tarifas da conta são escolhidas sem número de conta ou quando falta a taxa de câmbio.
General
Enable/Disable: ativa ou desativa o método em todas as zonas ao mesmo tempo.
Name: o nome do método de envio exibido na finalização de compra. Padrão: UPS.
Tax status: Taxable faz o WooCommerce somar o imposto de envio dele, None não soma. As tarifas da UPS são cotadas sem impostos, portanto o imposto não é cobrado duas vezes.
UPS API (tarifas em tempo real)
Test mode: usa o ambiente de teste da UPS. As tarifas de teste não são preços reais. Desative para tarifas em tempo real. Padrão: desativado.
Client ID: o Client ID do seu aplicativo no UPS Developer Portal.
Client Secret: o Client Secret do mesmo aplicativo.
UPS account number: o seu número de remetente UPS de 6 caracteres, por exemplo A1B2C3. Necessário para as tarifas da conta (negociadas) e opcional para as tarifas públicas.
Rates: quais preços da UPS são usados.
Measurement units: as unidades enviadas à UPS. Os pesos e tamanhos da loja são convertidos.
Residential delivery: cota os endereços dos clientes como residenciais, com a sobretaxa residencial da UPS. Desative se você envia principalmente para empresas. Padrão: ativado.
Box size: dimensões opcionais da caixa na unidade de dimensão da sua loja, por exemplo 30x20x15. A UPS então aplica o peso dimensional. Deixe em branco para cotar somente pelo peso.
UPS account currency: a UPS cota na moeda do país da conta do remetente, por exemplo USD para os EUA, CAD para o Canadá ou EUR para a zona do euro. Padrão: USD.
Exchange rate: só é necessária quando a moeda da conta UPS é diferente da moeda da loja. Informe 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 e valem os preços fixos. As taxas de câmbio não são atualizadas automaticamente.
Endereço de origem (o endereço de onde a UPS retira os pacotes ou onde você os entrega; usado para as tarifas em tempo real)
Country: o país de onde você envia. Por padrão, é o país da sua loja.
State / province code: a sigla com 2 letras, obrigatória para os Estados Unidos e o Canadá, por exemplo NY, CA ou ON.
City: a cidade de onde você envia.
ZIP / postal code: o CEP de onde você envia. A UPS precisa dele para cotar as tarifas.
Preços fixos (usados quando nenhuma credencial de API é informada e como alternativa quando a UPS não retorna nenhuma tarifa; deixe ambos vazios para ocultar o método nesse caso)
Country prices: preços na moeda da sua loja por país de destino. Clique em + Add country para adicionar uma linha e no X para remover uma. A linha * Default vale para qualquer outro país. Uma coluna de peso (XS até 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL acima de 5 kg) substitui o Price para esse peso do carrinho. Células vazias usam o Price. 0 significa frete grátis. Linhas sem nenhum preço são removidas ao salvar, e valores que não são números são recusados com uma mensagem.
Fallback cost: um preço fixo na moeda da sua loja quando nenhum preço por país corresponde. Deixe em branco para ocultar o método nesse caso.
Fixed price is: Per order cobra o preço uma única vez. Per item (each item priced by its own weight x quantity) precifica cada item pelo seu próprio peso (o peso padrão, se ele não tiver) e multiplica pela quantidade. As tarifas em tempo real da UPS 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. O cliente vê o nome do método com "(Free)" e nenhuma requisição é enviada à UPS. Deixe em branco para nunca oferecer frete grátis.
Minimum subtotal: exibe o método somente quando o subtotal do carrinho é pelo menos este valor. Deixe em branco para exibi-lo sempre.
Min weight (kg): o peso mínimo do carrinho para este método aparecer. 0 significa sem limite.
Max weight (kg): o método fica oculto acima deste peso do carrinho. Padrão: 70, o limite da UPS por pacote (70 kg / 150 lbs). 0 significa sem limite.
Default product weight (kg): o peso usado para produtos sem peso, nas tarifas da UPS, nas colunas de peso e nos limites de peso. Padrão: 0.5.
Excluded shipping classes: oculta o método se o carrinho contiver 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 tê-lo adicionado a uma zona de envio.
Countries: os países de destino para este modo. Deixe em branco para usar todos os países de envio da loja. Este campo só é usado quando Ignore shipping zones está ativado.
Avançado
Debug log: registra as requisições à API e o cálculo de tarifas em WooCommerce > Status > Logs, origem vfd-ups. Erros de API são sempre registrados, mesmo com esta opção desativada. Credenciais, 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 nunca apaga as 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 as condições: peso do carrinho, subtotal mínimo e classes de envio excluídas. Se o frete grátis se aplicar, o método é exibido como gratuito e nenhuma requisição é enviada à UPS.
O plugin obtém um token OAuth da UPS e o mantém até expirar. Um token rejeitado pela UPS é renovado automaticamente. Em seguida, ele consulta a API Rating da UPS para todos os serviços, do seu endereço de origem até o endereço do cliente, com o carrinho como um único pacote. Para países com CEP, a requisição aguarda até o cliente informar um. Nos envios dos Estados Unidos para o Canadá ou Porto Rico, o valor da mercadoria é enviado, como exige a UPS.
O cliente vê uma única opção com o serviço UPS mais barato, convertida para a moeda da sua loja. O UPS Access Point Economy não é cotado, porque o plugin não coleta um endereço de Access Point.
Cada tarifa fica em cache por 1 hora. Uma requisição com falha é lembrada por 10 minutos, e uma requisição de token com falha por 5 minutos, para que uma instabilidade não atrase cada atualização da finalização de compra. O tempo limite HTTP é de 15 segundos. Desativar o plugin apaga o token e as tarifas em cache.
Se a UPS não retornar uma tarifa (API fora do ar, credenciais erradas, nenhum serviço), o preço vem de Country prices e, depois, de Fallback cost. Se nenhum se aplicar, o método fica oculto. O cliente nunca vê mensagens de erro da UPS.
O método funciona na finalização de compra clássica e nos blocos Carrinho e Finalização de compra. Ele é compatível com o WooCommerce High-Performance Order Storage (HPOS).
O plugin calcula apenas tarifas. Ele não oferece a seleção de UPS Access Point, não cria etiquetas de envio nem envios da UPS, não agenda coletas e não rastreia encomendas. Ele exibe uma única opção, não vários serviços da UPS. Não há empacotamento em caixas: o carrinho é cotado como um único pacote. Taxas de câmbio não são automáticas.
Pedidos
Para uma tarifa em tempo real, a linha de envio do pedido armazena o UPS service, por exemplo UPS Ground. O gerente da loja o vê na tela do pedido no painel administrativo.
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 UPS. 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 informar 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 único domínio. Remover a chave de um site não libera a vaga de domínio. Libere-a na sua conta da vibefox.net.
Sem uma chave ativa, a UPS não é exibida aos clientes na finalização de compra. Os gerentes da loja logados 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 de Plugins e nas páginas do WooCommerce. 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 UPS não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se o método foi adicionado à zona do país do cliente (ou se Ignore shipping zones está ativo e o país é permitido). Confira os limites de peso, o Minimum subtotal e as Excluded shipping classes. Sem credenciais válidas da UPS, o método precisa de um preço fixo (Country prices ou Fallback cost).
As tarifas em tempo real não aparecem: verifique os avisos no topo da página de configurações. Ative o Debug log e abra WooCommerce > Status > Logs, origem vfd-ups. Ele mostra erros de OAuth (confira o Client ID, o Client Secret e o Test mode), mensagens de erro da UPS e problemas de moeda.
A tarifa está em USD, mas a loja não: a UPS retorna tarifas na moeda da conta do remetente. Defina UPS account currency e Exchange rate. Sem taxa de câmbio, essas tarifas são ignoradas e o preço fixo é usado.
"This measurement system is not valid for the selected country": deixe Measurement units em Automatic, ou escolha as unidades que a UPS espera para o país de origem do envio.
As tarifas parecem desatualizadas após uma alteração: salve a página de configurações ou clique em Clear cached UPS token and rates.
Para desenvolvedores: os filtros vfd_upsx_allowed_services e vfd_upsx_excluded_services restringem os serviços da UPS que podem ser exibidos. vfd_upsx_rate_request altera a requisição de tarifa, vfd_upsx_api_base_url o endereço da API e vfd_upsx_currency_codes mapeia os códigos de moeda retornados pela UPS.
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 da vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no 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 as configurações e apaga apenas o token e as tarifas em cache. Para removê-lo, desative e exclua na página Plugins. A chave de licença e o status de licença deste plugin, assim como o token e as tarifas em cache, 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 as suas linhas de envio.
UPS é uma marca de seu respectivo proprietário. Este plugin não é afiliado à UPS nem endossado pela UPS.