VibeFox UPS for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e posteriores (testado na versão 4.1.0.3).
PHP: 8.0 ou superior, com a extensão 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 a sua conta UPS e copie o Client ID e o Client Secret. A extensão usa OAuth 2.0. Não são necessários Access Key, nome de usuário nem senha. Para as 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: adquirida 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_ups-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_ups.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, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_ups-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 Installer, você pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.
2. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox UPS e clique em Install (o botão verde +).
3. Clique em Edit (o botão com o lápis) para abrir a página de configurações.
4. Informe a sua chave de licença VibeFox no campo License key, no bloco de licença no topo da página Edit, e clique em Activate (veja License key).
5. Informe 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 padrão da loja, informe a UPS account currency e a Exchange rate.
7. Opcionalmente, informe preços fixos como alternativa, ative o Enable UPS shipping e clique em Save.
OpenCart 4
1. No administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_ups.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão pelo 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. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox UPS, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).
4. Informe a chave de licença e as configurações como nas etapas 4 a 7 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões.
Após a instalação, o método fica desativado até que você ative o Enable UPS shipping e salve. O país de Ship from começa como o país da sua loja. Se você reinstalar a extensão depois de uma desinstalação, as configurações da UPS mantidas voltam a ser usadas.
Configuração
Todas as configurações estão na página da extensão: Extensions > Extensions > Shipping > VibeFox UPS > Edit. As seções ficam listadas à esquerda. Um botão Save no final salva a página inteira sem recarregá-la. Cada salvamento limpa o token da UPS e as tarifas em cache. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações, limpar o cache ou apagar o log.
Se o nome, a classe de imposto, a ordem de exibição ou a zona geográfica não forem válidos, nada é salvo e a página mostra o motivo, por exemplo Enter a valid name (64 characters max, without < > ; = # { }). Nothing was saved. Números inválidos (por exemplo, negativos), um tamanho de caixa incorreto, um Min weight (kg) acima de Max weight (kg) e células de preço que não são números são informados ao salvar: esse campo mantém o valor antigo e o restante é salvo. 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 o método nunca é mostrado), quando faltam o CEP ou o estado de origem, quando tarifas de conta são escolhidas sem número de conta, quando falta a taxa de câmbio, ou quando a unidade de peso ou de comprimento da loja não é reconhecida pela extensão.
Geral
As configurações valem para todas as zonas geográficas. A UPS é oferecida como uma única opção de envio na finalização de compra.
Enable UPS shipping: mostra ou oculta a UPS na finalização de compra. Padrão: desativado.
Name: o nome do método de envio mostrado ao cliente na finalização de compra. Padrão: UPS. Obrigatório, no máximo 64 caracteres, sem < > ; = # { }.
Tax class: a classe de imposto do custo de envio, ou None (padrão). As tarifas da UPS são cotadas sem impostos. Com uma classe de imposto, o OpenCart soma por cima o seu imposto de envio.
Sort order: a posição da UPS entre os métodos de envio na finalização de compra. Um número inteiro.
API da UPS (tarifas em tempo real)
Test mode: usa o ambiente de testes da UPS. 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. Limpá-lo 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 valor novo somente para alterá-lo.
UPS account number: o seu número de remetente UPS de 6 caracteres, por exemplo A1B2C3. Necessário para as tarifas de conta (negociadas); opcional para as tarifas publicadas.
Rates: quais preços da UPS são usados.
Measurement units: as unidades enviadas à UPS. Pesos e medidas da loja são convertidos.
Residential delivery: cota os endereços dos clientes como residenciais, com o adicional residencial da UPS. 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 sua loja (mostrada no nome do campo), por exemplo 30x20x15. A UPS aplica então o peso dimensional. Deixe vazio 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: necessária somente 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 sua moeda padrão, 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.
Cache: os tokens da UPS ficam em cache até expirarem (no máximo o tempo de vida do cache do OpenCart), as tarifas por 1 hora e as requisições com falha por 5 a 10 minutos. Clique em Clear cached UPS token and rates para limpar o cache de imediato.
Ship from (o endereço de onde a UPS coleta ou onde você entrega as encomendas; 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: a sigla de 2 letras, obrigatória para os EUA e o Canadá, por exemplo NY, CA ou ON. É enviada à UPS somente para esses dois países.
City: a cidade de onde você envia.
ZIP / postal code: o CEP de onde você envia. A UPS 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 credencial de API é informada e como alternativa quando a UPS não retorna tarifa; deixe ambos vazios para ocultar o método 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. * Default (all other countries) vale para qualquer outro país. Uma coluna de peso (XS até 1 kg, S de 1 a 2 kg, M de 2 a 3 kg, L de 3 a 5 kg, XL acima de 5 kg) substitui o Price para aquele peso do carrinho. Células vazias usam o Price. 0 significa frete grátis. Uma linha de país sem valor para o peso passa para a linha *. Linhas sem nenhum preço não são salvas.
Fallback cost: um preço fixo na moeda padrão da loja, quando nenhum preço por país corresponde. Deixe vazio para ocultar o método nesse caso.
Fixed price is: Per order (padrão) cobra o preço uma vez, pelo peso de todo o carrinho. Per item (each item priced by its own weight x quantity) precifica cada produto pelo próprio peso (o peso padrão, se não tiver um) e multiplica pela quantidade. As tarifas da UPS em tempo real são sempre cotadas pelo peso de todo o carrinho.
Condições
Free shipping from: o subtotal do carrinho (produtos que precisam de envio, após o cupom, antes dos impostos) a partir do qual este método é gratuito. Nenhuma requisição é enviada à UPS nesse caso. Deixe vazio para nunca oferecer frete grátis.
Minimum subtotal: mostra o método somente quando o subtotal do carrinho atinge pelo menos este valor. Deixe vazio para mostrá-lo sempre.
Min weight (kg): o peso mínimo do carrinho para que este método apareça. 0 significa sem limite (padrão).
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, vazio significa 70.
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. Vazio também significa 0.5.
Geo zone: ofereça a UPS somente para endereços nesta zona geográfica. All zones (padrão) significa sem limite. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones. Não é usado com Ignore shipping zones.
Disponibilidade sem zonas de envio
Ignore shipping zones: não verifica a zona geográfica. O método é oferecido nos países listados abaixo.
Countries: os países de destino para esse modo. Deixe vazio para usar todos os países habilitados da loja. Este campo é usado somente quando o Ignore shipping zones está ativo.
Avançado
Debug log: registra as requisições à API e o cálculo das tarifas em storage/logs/vfd_upsx_debug.log.php (no OpenCart 4, system/storage/logs/vfd_upsx_debug.log.php). O arquivo não pode ser lido pela web. Erros da API são sempre registrados, mesmo com esta opção desativada. Credenciais, tokens e endereços dos clientes nunca são registrados. Quando o arquivo chega a 5 MB, ele é movido para vfd_upsx_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 ativada, desinstalar a extensão apaga as configurações da UPS, os tokens e tarifas em cache e o log. Os serviços da UPS salvos com os pedidos são sempre mantidos. Quando desativada, tudo é mantido para uma reinstalação.
Importar / Exportar
Export: clique em Download JSON para salvar as configurações em um arquivo JSON. O Client Secret não é exportado.
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. O Client Secret salvo é mantido.
Como funciona na finalização de compra
Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço da UPS. Se uma Geo zone estiver definida e o endereço estiver fora dela, a UPS não é oferecida (com Ignore shipping zones, a lista de países decide). Somente produtos com Requires Shipping definido como Yes são considerados: os demais não adicionam peso e não entram no subtotal. O subtotal é o preço desses produtos após o desconto do cupom e antes dos impostos. Vales-presente, pontos de fidelidade e crédito da loja não são considerados. Depois, a extensão verifica as condições: peso do carrinho e subtotal mínimo. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada à UPS.
A extensão obtém da UPS um token OAuth e o mantém até expirar. Um token rejeitado pela UPS é renovado automaticamente e a requisição é repetida uma vez. Em seguida, ela pede à UPS Rating API 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 em que o OpenCart exige CEP, a requisição aguarda até que o cliente informe um. Para envios dos EUA ao Canadá ou a Porto Rico, o valor das mercadorias é 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, arredondado conforme as casas decimais dela e mostrado na moeda do cliente com o imposto da Tax class selecionada. A UPS Access Point Economy não é cotada, porque a extensão 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 indisponibilidade não atrase cada atualização da finalização de compra. O tempo limite HTTP é de 15 segundos.
Se a UPS não retornar tarifa (API indisponível, credenciais incorretas, nenhum serviço, outra moeda sem taxa de câmbio), 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 motivo é gravado no log de depuração.
A extensão apenas calcula tarifas. Ela não oferece a seleção de um ponto UPS Access Point, não cria etiquetas nem envios UPS, não agenda coletas e não rastreia encomendas. Mostra 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. As taxas de câmbio não são automáticas.
No OpenCart 4, o cliente clica em Choose no bloco de métodos de envio da página de finalização de compra e escolhe a UPS na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.
Pedidos
Quando um pedido é feito com uma tarifa UPS em tempo real, o serviço da UPS é salvo com o pedido. A página do pedido em Sales > Orders mostra um painel UPS com o UPS service, por exemplo UPS Ground, e a Live rate (excl. tax). Esses valores são salvos quando o pedido é feito. Pedidos com preço fixo ou frete grátis não têm esse painel.
O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza sempre que o cliente confirma novamente. O serviço da UPS salvo é atualizado junto com ele. Se o cliente mudar para outro método de envio, ou se o preço passar a ser um preço fixo ou frete grátis, o serviço salvo é removido do pedido. No OpenCart 4, o painel UPS é exibido acima da seção History.
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 UPS é o primeiro bloco de Extensions > Extensions > Shipping > VibeFox UPS > 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 deles ficam a linha Product: opencart-shipping-ups e o link Manage licenses and domains in your account, que abre a sua conta 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 seguido de 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. Você gerencia suas licenças e domínios na sua conta vibefox.net.
Sem uma chave ativa, a UPS não é mostrada aos clientes na finalização de compra e nenhuma tarifa é calculada. Um usuário administrador conectado ao administrativo no mesmo navegador ainda vê o método na loja, marcado com (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 administrador, então 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 precisam de renovação. O status é verificado novamente de forma automática quando você abre a Dashboard ou a página Edit do administrativo: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é necessário nenhum cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.
Solução de problemas
UPS does not appear at checkout: verifique se a licença está ativa e se o Enable UPS shipping está ligado. Confira Geo zone, ou ative o Ignore shipping zones e confira Countries. Verifique os limites de peso e o Minimum subtotal. Sem credenciais válidas da UPS, o método precisa de um preço fixo (Country prices ou Fallback cost). Verifique se os produtos têm Requires Shipping definido como Yes.
Live rates do not appear: confira os avisos no topo da página Edit. Ative o Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão. Ele mostra erros de OAuth (verifique o Client ID, o Client Secret e o Test mode), mensagens de erro da UPS e problemas de moeda.
The rate is in USD but the store is not: a UPS retorna tarifas na moeda da conta do remetente. Defina a UPS account currency e a Exchange rate. Sem a 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 o Measurement units em Automatic (by ship-from country), ou escolha as unidades que a UPS espera para o seu país de origem.
The page warns about the weight or length unit: sem uma classe de peso com a unidade kg, unidades de peso desconhecidas são lidas como kg. Adicione uma classe de peso em kg em System > Localisation > Weight Classes. Uma unidade de comprimento desconhecida na loja faz o Box size ser lido como cm. Use cm, mm, m ou in como classe de comprimento da loja (System > Settings, aba Option).
Rates look outdated after a change: clique em Save na página da extensão ou em Clear cached UPS token and rates.
The page says "Warning: You do not have permission to modify VibeFox UPS!": o seu grupo de usuários administradores pode apenas visualizar as configurações. Dê ao grupo a permissão de modificação para extension/shipping/vfd_ups (OpenCart 3) ou extension/vfd_ups/shipping/vfd_ups (OpenCart 4) em System > Users > User Groups.
For developers: a extensão dispara eventos do OpenCart que outras extensões podem escutar: vfd_ups/allowed_services e vfd_ups/excluded_services restringem os serviços da UPS que podem ser mostrados, vfd_ups/rate_request altera a requisição de tarifa, vfd_ups/api_base_url o endereço da API e vfd_ups/currency_codes mapeia os códigos de moeda retornados pela UPS.
Desinstalação
Acesse Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox UPS. O OpenCart sempre redefine o Enable UPS shipping, o Sort order, o Tax class e o Geo zone. O token e as tarifas da UPS em cache são sempre removidos. Se o Remove data on uninstall estiver ativado, as configurações da UPS e o log de depuração também são apagados. Se estiver desativado, as demais configurações são mantidas e voltam a ser usadas ao reinstalar a extensão. Os serviços da UPS salvos com os pedidos nunca são removidos, e os pedidos existentes mantêm o método de envio e o custo.
No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox UPS na lista de extensões instaladas, depois em Delete (o botão vermelho de lixeira) para remover o pacote enviado.
A UPS é marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pela UPS.