VibeFox UPS for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior, com a extensão cURL. O módulo não é instalado em versões antigas do PHP nem sem cURL.
Aplicativo no UPS Developer Portal (somente para tarifas em tempo real): acesse o UPS Developer Portal (developer.ups.com), crie um aplicativo com o produto "Rating", vincule sua conta UPS e copie o Client ID e o Client Secret. O módulo usa OAuth 2.0. Não é preciso Access Key, nome de usuário nem senha. Para tarifas negociadas, você também precisa do número de conta UPS de 6 caracteres. Sem credenciais, são usados somente 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 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, depois, encontre VibeFox UPS 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. Insira o Client ID e o Client Secret, o número da sua conta UPS (para tarifas negociadas) e o endereço Ship from: o código postal e, para os EUA e o Canadá, o estado com 2 letras.
5. Se a moeda da sua conta UPS for diferente da moeda padrão da sua loja, insira UPS account currency e Exchange rate.
6. Opcionalmente, insira preços fixos como alternativa e clique em Save.
Na instalação, o módulo cria a transportadora UPS com o texto de prazo de entrega UPS 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 ficam na página do módulo: Modules > Module Manager > VibeFox UPS > 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 limpa o token e as tarifas da UPS em cache. Você também pode clicar em Clear cached UPS token and rates na seção UPS API.
Os avisos acima das configurações informam quando apenas um entre Client ID e Client Secret está preenchido, quando não há credenciais nem preços fixos (nesse caso a transportadora nunca é exibida), quando faltam o código postal ou o estado de origem, quando tarifas da conta são escolhidas sem número de conta, quando falta a taxa de câmbio ou quando o módulo não reconhece a unidade de peso ou de dimensão da loja. Números inválidos, um tamanho de caixa incorreto e um Min weight acima de Max weight são informados ao salvar, e o valor antigo é mantido.
Geral
Enable UPS shipping: liga ou desliga a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Name: o nome da transportadora mostrado ao cliente no checkout. Padrão: UPS. Obrigatório, no máximo 64 caracteres.
Tax status: a regra de imposto da transportadora, ou None. As tarifas da UPS são cotadas sem impostos. Com uma regra de imposto, a loja acrescenta o próprio imposto sobre o frete.
API da UPS (tarifas em tempo real)
Test mode: usa o ambiente de teste da UPS. Tarifas de teste não são preços reais. Desative para tarifas reais. Padrão: off.
Client ID: o Client ID do seu aplicativo no UPS Developer Portal. Limpar esse campo também remove o Client Secret salvo.
Client Secret: o Client Secret do mesmo aplicativo. Depois de salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas para alterá-lo.
UPS account number: seu número de remetente UPS de 6 caracteres, por exemplo A1B2C3. Necessário para tarifas da conta (negociadas), opcional para tarifas públicas.
Rates: quais preços da UPS são usados.
Measurement units: as unidades enviadas à UPS. Pesos e dimensões da loja são convertidos.
Residential delivery: calcula os endereços dos clientes como residenciais, com a sobretaxa residencial da UPS. Desative se você envia principalmente para empresas. Padrão: on.
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 vazio para cotar apenas 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: necessário apenas quando a moeda da conta UPS é diferente da moeda padrão da loja. Informe o preço de 1 unidade da moeda da conta na moeda padrão da sua loja, por exemplo 0.92. Sem ele, 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 coleta ou onde você entrega os pacotes; usado nas tarifas em tempo real)
Country: o país de onde você envia. Por padrão, é o país da sua loja.
State / province code: o código de 2 letras, obrigatório para os EUA e o Canadá, por exemplo NY, CA ou ON.
City: a cidade de onde você envia.
ZIP / postal code: o código postal 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 os dois campos vazios para ocultar a transportadora nesse caso)
Country prices: preços na moeda padrão da loja, sem impostos, por país de destino. Clique em Add country para adicionar uma linha e no botão de remover para excluir uma. O país * 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. 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 rejeitados com uma mensagem.
Fallback cost: um preço fixo na moeda padrão da loja, quando nenhum preço por país corresponde. Deixe vazio para ocultar a transportadora nesse caso.
Fixed price is: Per order cobra o preço uma vez, pelo peso de todo o carrinho. Per item (each item priced by its own weight x quantity) calcula cada produto pelo próprio peso (o peso padrão, se ele não tiver) e multiplica pela quantidade. Se um produto não tiver preço fixo, a transportadora fica oculta. 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 (produtos que precisam de envio, após descontos, antes dos impostos) a partir do qual esta transportadora é grátis. Nesse caso, nenhuma solicitação é enviada à UPS. Deixe vazio para nunca oferecer frete grátis.
Minimum subtotal: mostra a transportadora apenas quando o subtotal do carrinho for de pelo menos este valor. Deixe vazio para sempre mostrá-la.
Min weight: o peso mínimo do carrinho em kg para que esta transportadora apareça. 0 significa sem limite.
Max weight: a transportadora fica oculta acima deste peso do carrinho em kg. Padrão: 70, o limite da UPS por pacote (70 kg / 150 lbs). 0 significa sem limite, vazio significa 70. Min weight não pode ser maior que Max weight.
Default product weight: o peso em kg usado para produtos sem peso, nas tarifas da UPS, nas colunas de peso e nos limites de peso. Padrão: 0.5.
Disponibilidade sem zonas de envio
Normalmente, a transportadora é oferecida nas zonas às quais está atribuída em Shipping > Carriers.
Ignore shipping zones: oferece a transportadora para os países abaixo, qualquer que seja a zona correspondente. Ao salvar, a transportadora é adicionada a todas as zonas, inclusive às criadas depois. Desativar remove essas zonas novamente.
Countries: os países de destino para este modo. Deixe vazio para usar todos os países ativos 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 logs/vfd_upsx_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros da API são sempre registrados, mesmo com esta opção desativada. Credenciais, 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 exclui as configurações, a transportadora, os tokens e tarifas em cache, o registro e os serviços da UPS salvos com os pedidos. Os próprios pedidos são mantidos. 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 UPS. 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: os países de 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 à UPS.
O módulo obtém da UPS um token OAuth e o mantém até que expire. Um token rejeitado pela UPS é renovado automaticamente. Em seguida, pede à API Rating da UPS todos os serviços do seu endereço de origem até o endereço do cliente, para o carrinho como um único pacote. Para países com códigos postais, a solicitação aguarda até que o cliente tenha informado o seu. Para envios dos EUA ao Canadá ou a Porto Rico, o valor da mercadoria é enviado, como a UPS exige.
O cliente vê uma única opção com o serviço UPS mais barato. O preço é calculado na moeda padrão da loja e depois exibido na moeda do carrinho do cliente. O UPS Access Point Economy não é cotado, porque o módulo não coleta um endereço de Access Point.
Cada cotação fica em cache por 1 hora. Uma solicitação com falha é lembrada por 10 minutos, e uma solicitação de token com falha por 5 minutos, para que uma queda não deixe lenta cada atualização da finalização de compra. O tempo limite HTTP é de 15 segundos.
Se a UPS não retornar nenhuma tarifa (API fora do ar, credenciais erradas, nenhum serviço, outra moeda sem taxa de câmbio), o preço vem de Country prices e, depois, de Fallback cost. Se nenhum dos dois se aplicar, a transportadora fica oculta. O cliente nunca vê textos de erro da UPS.
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 apenas calcula 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 pacotes. Ele mostra uma opção, não vários serviços da UPS. Não há empacotamento em caixas: o carrinho é cotado como um único pacote. As taxas de câmbio não são automáticas.
Pedidos
Quando um pedido é feito com uma tarifa em tempo real da UPS, o serviço da UPS é salvo com o pedido. A página do pedido no back office mostra um bloco UPS com o UPS service, por exemplo UPS Ground, e a Live rate (excl. tax). Alterações posteriores no carrinho pelo back office não a modificam. Pedidos com preço fixo ou frete grátis não têm esse bloco.
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 UPS é o primeiro bloco de Modules > Module Manager > VibeFox UPS > 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 ficam a linha Product: presta-shipping-ups e o link Manage licenses and domains in your account, que abre a sua conta 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 com 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 vibefox.net.
Sem uma chave ativa, a transportadora UPS 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ê: 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 inserção da chave, depois uma vez por semana. Não é necessário nenhum cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A UPS não aparece na finalização de compra: verifique se a licença está ativa e se Enable UPS shipping está ligado. Em Shipping > Carriers, confira se a transportadora cobre a zona do país do cliente e o grupo de clientes, ou ative Ignore shipping zones e verifique Countries. Confira os limites de peso e o Minimum subtotal. Sem credenciais da UPS funcionando, a transportadora precisa de um preço fixo (Country prices ou Fallback cost). Além disso, produtos podem ser limitados a determinadas transportadoras na página do produto.
As tarifas em tempo real não aparecem: confira os avisos no topo da página Configure. Ative o Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo. 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.
A página avisa que a unidade de peso ou de dimensão da loja não é conhecida: os pesos são então lidos como kg e o tamanho da caixa como cm. Defina uma unidade padrão (kg, g, lb ou oz; cm, mm, m ou in) em International > Localization, seção Local units.
As tarifas parecem desatualizadas após uma alteração: clique em Save na página do módulo ou em Clear cached UPS token and rates.
A página informa que a transportadora UPS não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.
Para desenvolvedores: os hooks actionVfdUpsxAllowedServices e actionVfdUpsxExcludedServices restringem os serviços da UPS que podem ser exibidos. actionVfdUpsxRateRequest altera a requisição de tarifa, actionVfdUpsxApiBaseUrl o endereço da API e actionVfdUpsxCurrencyCodes mapeia os códigos de moeda retornados pela UPS.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox UPS e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. O token e as tarifas da UPS 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 registro e os serviços da UPS salvos com os pedidos são removidos. Se estiver desativado, a transportadora é apenas desabilitada e as configurações são mantidas. Reinstalar o módulo ou fazer um Reset devolve à transportadora o status que ela tinha antes.
A UPS é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela UPS.