VibeFox USPS for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e posterior (testado na 4.1.0.3).
PHP: 8.0 ou superior, com a extensão cURL.
Aplicativo no Portal de Desenvolvedores da USPS (somente para tarifas em tempo real): faça login no Portal de Desenvolvedores da USPS (developers.usps.com) com uma conta comercial gratuita da USPS, crie um aplicativo e copie o seu Consumer Key e o seu Consumer Secret. A extensão usa as APIs atuais da USPS com OAuth 2.0. O antigo Web Tools User ID não funciona com elas. Sem as chaves, apenas os preços fixos são usados.
CEP de origem: as tarifas em tempo real exigem o CEP dos Estados Unidos de 5 dígitos de onde os pacotes são enviados.
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_usps-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_usps.ocmod.zip. Instale apenas o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.
OpenCart 3
1. No admin, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_usps-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. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox USPS 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 em License key no bloco de licença no topo da página Edit e clique em Activate (veja License key).
5. Informe o Consumer Key e o Consumer Secret, o Ship from ZIP code de 5 dígitos e escolha os Services. Se a moeda padrão da sua loja não for USD, informe o USD exchange rate.
6. Opcionalmente, informe preços fixos como alternativa, ative Enable USPS shipping e clique em Save.
OpenCart 4
1. No admin, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_usps.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. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox USPS, 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 nos passos 4 a 6 do OpenCart 3. A página de configurações e os campos são iguais nas duas versões.
Após a instalação, o método fica desativado até que você ative Enable USPS shipping e salve. Se você instalar a extensão novamente depois de uma desinstalação, as configurações da USPS 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 USPS > Edit. As seções são listadas à esquerda. Um botão Save no final salva a página inteira sem recarregá-la. Cada salvamento limpa o token e as tarifas da USPS em cache. Somente administradores com a permissão de modificação desta extensão podem salvar as configurações, limpar o cache ou limpar o log.
Um valor inválido não é salvo: a página indica o campo, restaura o valor anterior e mostra The other settings were saved. Isso vale para um nome vazio, longo demais ou com caracteres proibidos, um número negativo ou não numérico, um CEP que não tenha 5 dígitos, um tamanho de caixa incorreto, um Min weight (kg) acima de Max weight (kg) (ambos os limites mantêm seus valores), uma ordem de classificação que não seja um número inteiro, e uma classe de imposto ou zona geográfica desconhecida. Preços por país que não são números são apagados e listados. Os avisos acima das configurações indicam quando apenas uma das duas chaves está preenchida, quando não há chaves nem preços fixos (nesse caso o método nunca é exibido), quando o CEP está faltando, quando nenhum serviço está selecionado, quando a taxa de câmbio em USD está faltando, quando o ambiente de teste está ativo ou quando a unidade de peso ou de comprimento da loja não é reconhecida pela extensão.
Geral
As configurações se aplicam a todas as zonas geográficas. A USPS é oferecida como uma única opção de envio na finalização de compra.
Enable USPS shipping: oferece o envio pela USPS na finalização de compra. Padrão: desativado.
Name: o nome do método de envio exibido ao cliente na finalização de compra. Padrão: USPS. Obrigatório, no máximo 64 caracteres, sem < > ; = # { }.
Tax class: a classe de imposto do custo de envio. As tarifas da USPS não incluem impostos. No tax (padrão) significa que o envio não é tributado.
Sort order: a posição da USPS entre os métodos de envio na finalização de compra. Um número inteiro.
API da USPS (tarifas em tempo real)
Consumer Key: o Consumer Key (client_id) do seu aplicativo de desenvolvedor da USPS. Apagá-lo também remove o Consumer Secret salvo.
Consumer Secret: o Consumer Secret (client_secret) do mesmo aplicativo. Depois de salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Clearing the Consumer Key removes it too. Digite um novo valor somente se quiser alterá-lo.
Test environment: use o USPS Testing Environment para remetentes. Somente para aplicativos que tenham acesso a ele. Deixe desativado para obter preços reais. Padrão: desativado.
Prices: qual tabela de preços da USPS é usada.
Services: os serviços da USPS que podem ser cotados. É exibido o serviço selecionado mais barato que a USPS oferece para o pacote. Escolha entre USPS Ground Advantage, Priority Mail / Priority Mail International, Priority Mail Express / Priority Mail Express International, First-Class Package International Service, Media Mail (books and media only) e Library Mail (libraries and schools only). Padrão: Ground Advantage, Priority Mail e First-Class Package International. As tarifas Flat Rate, Cubic, Hold for Pickup e Sunday nunca são usadas. Se nenhum serviço estiver selecionado, as tarifas em tempo real não são usadas.
USD exchange rate: os preços da USPS estão em USD. Se a moeda padrão da sua loja não for USD, informe o preço de 1 USD na sua moeda, por exemplo 0.92. Ele deve ser maior que 0. Sem ele, as tarifas em tempo real não são usadas e valem os preços fixos. Se a moeda da sua loja for USD, ele não é necessário. A taxa não é atualizada automaticamente.
Cache: as cotações ficam em cache por 1 hora e uma cotação com falha por 10 minutos. Após um tempo limite, erro de servidor, limite de requisições ou chaves recusadas, a USPS não é consultada por 5 minutos. Clique em Clear cached USPS token and rates para limpar o cache imediatamente.
Envio e pacote (os preços da USPS dependem do CEP de origem, do peso e do tamanho do pacote; o carrinho é cotado como um único pacote)
Ship from ZIP code: o CEP dos Estados Unidos de 5 dígitos de onde os pacotes são enviados. O ZIP+4 é reduzido para 5 dígitos. O OpenCart não tem um CEP da loja, por isso informe-o aqui.
Box size (L x W x H): dimensões opcionais da caixa na unidade de comprimento da sua loja (exibida no nome do campo), por exemplo 30x20x15. Deixe vazio para usar as dimensões do produto: o maior comprimento, a maior largura e as alturas empilhadas. Produtos sem dimensões são cotados como uma caixa de 10 x 8 x 4 polegadas.
Default product weight (kg): o peso usado para produtos sem peso, nas tarifas da USPS, nos limites de peso e nas faixas de peso. Padrão: 0.5. Vazio também significa 0,5 kg.
Preços fixos (preços na moeda padrão da sua loja, sem impostos; usados quando nenhuma chave de API é informada e como alternativa quando a USPS não retorna nenhuma tarifa; deixe ambos vazios para ocultar o método nesse caso)
Country prices: preços por país de destino e peso do carrinho. Clique em Add country para adicionar uma linha e no botão de remover para excluir uma. As faixas de peso são XS até 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg e XL acima de 5 kg. Uma faixa vazia ou 0 usa Price. * Default (any other country) se aplica a todos os outros países.
Fallback cost: um preço fixo 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 única vez, pelo peso de todo o carrinho. Per item (each item priced by its own weight x quantity) precifica cada produto pelo seu próprio peso multiplicado pela quantidade. As tarifas em tempo real da USPS são sempre cotadas para o pacote inteiro.
Condições
Free shipping from: o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) a partir do qual este método é gratuito. Nesse caso, nenhuma requisição é enviada à USPS. Deixe vazio para nunca oferecer frete grátis.
Minimum subtotal: exibir o método somente quando o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) for pelo menos este valor. Deixe vazio para exibi-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: 30. Vazio significa 30 kg, 0 significa sem limite. A USPS aceita até 70 lb (31,7 kg): pacotes mais pesados recebem os preços fixos.
Geo zone: oferecer a USPS 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 para os países abaixo.
Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países. Este campo só é usado quando Ignore shipping zones está ativo.
Avançado
Debug log: registra as requisições à API e o cálculo das tarifas em storage/logs/vfd_usps_debug.log.php (no OpenCart 4 system/storage/logs/vfd_usps_debug.log.php). O arquivo não pode ser lido pela web. Erros da API são sempre registrados, mesmo quando esta opção está desativada. Chaves, tokens, CEPs e endereços de clientes nunca são registrados. Quando o arquivo chega a 5 MB, ele é movido para vfd_usps_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 limpá-lo.
Remove data on uninstall: quando ativo, desinstalar a extensão apaga as configurações da USPS e o log. As tarifas em cache são sempre removidas. Os serviços da USPS dos pedidos feitos são sempre mantidos. Quando desativado, as configurações são mantidas para uma reinstalação.
Importação / Exportação
Export: clique em Download JSON para salvar as configurações em um arquivo JSON. O Consumer Secret não é exportado.
Import: cole o 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 Consumer Secret salvo é mantido.
Como funciona na finalização de compra
Quando o OpenCart exibe os métodos de envio, ele pede à extensão o preço da USPS. Se uma Geo zone estiver definida e o endereço estiver fora dela, a USPS não é oferecida (com Ignore shipping zones, a lista de países é que decide). Só contam os produtos com Requires Shipping definido como Yes: os demais não somam peso e não entram no subtotal. Vale-presente, pontos de recompensa e crédito da loja não são considerados. A extensão entã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 à USPS.
A extensão obtém um token OAuth da USPS e o mantém até pouco antes de expirar. Para destinos nos Estados Unidos e em seus territórios (Porto Rico, Ilhas Virgens Americanas, Guam, Samoa Americana, Ilhas Marianas do Norte, Micronésia, Ilhas Marshall e Palau), ela pede as tarifas nacionais e precisa do CEP de 5 dígitos do cliente: sem ele, não há requisição. Para os demais países, pede as tarifas internacionais.
A requisição contém o CEP de origem, o peso do carrinho, o tamanho do pacote e o tipo de preço. Pacotes acima de 70 lb recebem os preços fixos. O cliente vê uma única opção com o serviço selecionado mais barato. O preço em USD é convertido para a sua moeda padrão, arredondado conforme as casas decimais dela e exibido na moeda do cliente com o imposto da Tax class selecionada.
Cada cotação fica em cache por 1 hora. Uma cotação com falha é lembrada por 10 minutos. Após um tempo limite, erro de servidor, limite de requisições ou chaves recusadas, a USPS não é consultada por 5 minutos. O tempo limite HTTP é de 10 segundos.
Se a USPS não retornar nenhuma tarifa, o preço vem de Country prices e depois de Fallback cost. Se nenhum dos dois se aplicar, o método fica oculto. O cliente nunca vê textos de erro da USPS. O motivo é gravado no log de depuração.
A extensão calcula apenas tarifas. Ela não compra selos ou etiquetas de envio, não agenda coletas, não rastreia pacotes e não permite que o cliente escolha uma agência ou um ponto de retirada. Ela exibe uma única opção, e não vários serviços da USPS. Não há embalagem em caixas: o carrinho é cotado como um único pacote. Seguro e outros serviços extras não estão incluídos.
No OpenCart 4, o cliente clica em Choose no bloco do método de envio da página de finalização de compra e escolhe a USPS na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.
Pedidos
Quando um pedido é feito com a USPS, a extensão salva como o preço do envio foi obtido. A página do pedido em Sales > Orders mostra um painel USPS com o USPS service (para uma tarifa em tempo real, por exemplo USPS Ground Advantage), a Price source (USPS live rate, Fixed price ou Free shipping) e o Calculated price (excl. tax). Esses valores são salvos quando o pedido é feito.
O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza sempre que o cliente confirma novamente. Os valores salvos são atualizados junto com ele. Se o cliente mudar para outro método de envio, eles são removidos do pedido. No OpenCart 4, o painel USPS é 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 USPS é o primeiro bloco de Extensions > Extensions > Shipping > VibeFox USPS > 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-usps e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do admin (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, a extensão continua funcionando com o último status conhecido.
Uma chave funciona em um único domínio: o endereço da loja nas configurações do OpenCart. Remover a chave da loja não libera a vaga de domínio dela. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, a USPS não é exibida aos clientes na finalização de compra e nenhuma tarifa é calculada. Um usuário administrador conectado ao admin 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 admin, então, sem uma chave ativa, o método fica oculto para todos. Depois que você abrir a página Edit uma vez, um lembrete aparece no Dashboard do admin. 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 de novo automaticamente quando você abre o Dashboard do admin ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser informada 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 USPS não aparece na finalização de compra: verifique se a licença está ativa e se Enable USPS shipping está ativado. Confira a Geo zone ou ative Ignore shipping zones e confira Countries. Confira os limites de peso e o Minimum subtotal. Sem chaves da USPS funcionando, 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.
As tarifas em tempo real não aparecem: confira os avisos no topo da página Edit: as duas chaves, o CEP, pelo menos um serviço e, para lojas que não usam USD, a taxa de câmbio. Clientes dos Estados Unidos precisam informar um CEP. Ative o Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão.
As tarifas não são preços reais: desative o Test environment.
A página avisa sobre a unidade de peso ou de comprimento: 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 da loja é tratada como cm. Use cm, mm, m ou in como classe de comprimento da loja (System > Settings, aba Option).
As tarifas parecem desatualizadas após uma mudança: clique em Save na página da extensão ou em Clear cached USPS token and rates.
A página exibe "Warning: You do not have permission to modify VibeFox USPS!": 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_usps (OpenCart 3) ou extension/vfd_usps/shipping/vfd_usps (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: o endereço da API da USPS pode ser substituído pela configuração vfd_usps_api_url (para testes); ela 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 USPS. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable USPS shipping, Sort order, Tax class e Geo zone. O token e as tarifas da USPS em cache são sempre removidos. Se Remove data on uninstall estiver ativo, as configurações da USPS 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 quando você instalar a extensão novamente. Os dados da USPS dos pedidos feitos 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, vá em Extensions > Installer depois da desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox USPS na lista de extensões instaladas e, em seguida, em Delete (o botão vermelho de lixeira) para remover o pacote enviado.
A USPS é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela USPS.