VibeFox EasyPost 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 cURL.

Conta EasyPost (somente para tarifas em tempo real): crie uma conta no site da EasyPost, conecte as suas contas de transportadoras (USPS, UPS, FedEx e outras) no painel da EasyPost e copie a chave da API em EasyPost Dashboard > Account Settings > API Keys. A EasyPost cobra pelas etiquetas compradas, e não pelas consultas de tarifas. Se você usar apenas preços alternativos, não precisa de uma conta EasyPost.

Produtos: os produtos precisam de peso e, de preferência, de dimensões.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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 README.txt, o pacote do OpenCart 3 vfd_easypost-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_easypost.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. Na administração, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_easypost-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ê também pode copiar o conteúdo da pasta upload do pacote para a pasta raiz da sua loja.

2. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox EasyPost e clique em Install (o botão verde +).

3. Clique em Edit (o botão de lápis) para abrir a página de configurações.

4. Insira 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 Chave de licença).

5. Cole a sua chave da API da EasyPost e preencha o endereço Ship from. O CEP é obrigatório para as tarifas em tempo real.

6. Se a moeda padrão não for USD, informe a USD exchange rate. Opcionalmente, informe os preços alternativos (veja Configuração). Ative Enable EasyPost shipping e clique em Save.

OpenCart 4

1. Na administração, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_easypost.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão do 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 EasyPost, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).

4. Insira 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 seus campos são iguais nas duas versões.

Depois da instalação, o método fica desativado até você ativar Enable EasyPost shipping e salvar. Se você instalar a extensão novamente após uma desinstalação, as configurações mantidas serão usadas de novo.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Shipping > VibeFox EasyPost > Edit. As seções ficam listadas à esquerda. Um único botão Save salva a página inteira sem recarregá-la. Cada salvamento também limpa as tarifas da EasyPost em cache. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações ou limpar o log.

No topo da página, a extensão mostra avisos quando as tarifas em tempo real não podem ser usadas: sem chave da API (com ou sem preços alternativos), sem CEP ou país de origem do envio, ou uma moeda padrão diferente de USD sem taxa de câmbio. Também aparece uma nota quando uma chave de API de teste está definida, e um aviso quando a unidade de peso ou de comprimento da sua loja (System > Settings > Option) não é uma que a extensão reconhece (kg, g, lb, oz; cm, mm, m, in).

Ao salvar, um nome com mais de 64 caracteres, um Sort order que não é número inteiro, ou uma classe de imposto ou zona geográfica desconhecida impedem o salvamento, e nesse caso nada é salvo. Um valor que não é número (ou é negativo) não é salvo: um aviso indica o campo e o valor anterior é mantido, enquanto as demais configurações são salvas. O mesmo acontece quando a USD exchange rate é 0, ou quando o Minimum weight é maior que o Maximum weight.

Geral

Enable EasyPost shipping: oferece o método na finalização de compra. Este é o estado da extensão em Extensions > Extensions > Shipping. Padrão: desativado.

Name: o nome do método de envio mostrado ao cliente na finalização de compra, no máximo 64 caracteres. Padrão: EasyPost Shipping. Se o nome estiver vazio, o nome padrão é usado. Um nome com os caracteres < > ; = # { } é substituído pelo nome padrão, com um aviso.

Sort order: a posição do método entre os métodos de envio na finalização de compra. Um número inteiro.

Conta EasyPost

API key: a sua chave da API da EasyPost em EasyPost Dashboard > Account Settings > API Keys. Uma chave de produção (começa com EZAK) retorna tarifas reais. Uma chave de teste (começa com EZTK) retorna tarifas de teste da EasyPost; use-a somente para testes. Depois de salvar, o campo fica vazio e mostra a chave salva mascarada, por exemplo Saved key: EZAK******abcd. Leave the field empty to keep it. Digite um novo valor somente para alterá-la. Sem chave, somente os preços alternativos são usados.

Remove the saved API key: ative e clique em Save para apagar a chave salva.

Allowed carriers / services: opcional, separado por vírgulas. Digite uma transportadora (USPS) ou uma transportadora e um serviço (USPS:Priority, UPS:Ground) como a EasyPost os nomeia. A tarifa permitida mais barata é mostrada. Deixe vazio para mostrar a tarifa mais barata de qualquer transportadora.

Origem do envio

O endereço de onde os seus pacotes são enviados. Se o Country for o país da sua loja, o campo vazio Sender name / company é preenchido com o nome da loja e o campo vazio State com a região da loja (System > Settings). O OpenCart não tem CEP para a loja, então o CEP precisa ser informado aqui.

Sender name / company: o nome do remetente ou da empresa. Vazio significa o nome da loja (somente no mesmo país).

Street address: a rua do endereço de origem do envio.

City: a cidade do endereço de origem do envio.

State: o código do estado com duas letras, por exemplo CA ou NY.

ZIP code: o CEP de origem do envio, por exemplo 94105. Obrigatório para as tarifas em tempo real.

Country: o país de onde você envia. Padrão: United States.

Tarifas

Parcels: como o carrinho é enviado à EasyPost.

Os pesos são convertidos da unidade de peso da sua loja para onças (mínimo 1 oz), e as dimensões da unidade de comprimento da loja para polegadas. Se algum produto não tiver dimensões, o pacote é tarifado somente pelo peso.

USD exchange rate: as tarifas da EasyPost são em USD. Informe o preço de 1 USD na moeda padrão da sua loja, por exemplo 0.92. Sem ele, as tarifas em tempo real não são usadas, somente os preços alternativos. Não é necessário quando a moeda padrão é USD. Lojas em USD e CAD pedem à EasyPost que cote na moeda delas. Tanto o ponto quanto a vírgula são aceitos como separador decimal.

Tax class: a classe de imposto aplicada ao envio, ou No tax. As tarifas da EasyPost não incluem imposto sobre vendas.

Preços alternativos

Usados quando não há tarifa em tempo real: sem chave da API, a EasyPost não pode ser acessada, a chave é recusada ou nenhuma transportadora tem tarifa para o endereço. Os preços estão na moeda padrão da loja, sem impostos. Deixe os dois campos vazios para ocultar o método nesse caso.

Country prices: uma linha por país: código do país com duas letras, dois-pontos e o preço, por exemplo US:9.99. Linhas em outro formato são ignoradas e listadas em um aviso ao salvar.

Other countries: o preço para os países que não estão na lista acima. Deixe vazio para ocultar o método para eles.

Condições

Free shipping from: o subtotal do carrinho (produtos a enviar, após o cupom, antes dos impostos, na moeda padrão) a partir do qual o frete é grátis. Nesse caso nenhuma requisição é enviada à EasyPost. Deixe vazio para desativar.

Minimum subtotal: mostra o método somente se o subtotal do carrinho (produtos a enviar, após o cupom, antes dos impostos) for pelo menos este valor. Deixe vazio para mostrá-lo sempre.

Minimum weight: oculta o método quando o carrinho pesa menos, na unidade de peso da sua loja (indicada no rótulo do campo). 0 significa sem limite (padrão).

Maximum weight: oculta o método quando o carrinho pesa mais, na unidade de peso da sua loja. 0 significa sem limite (padrão).

Disponibilidade

Normalmente, a zona geográfica define onde o método é oferecido. Alternativamente, ele pode ser oferecido por país, independentemente da zona geográfica.

Geo zone: oferece o método somente para endereços dentro desta 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.

Ignore shipping zones: oferece o método nos países indicados abaixo, estejam ou não na zona geográfica.

Countries: os países de destino para esse modo. Deixe vazio para usar todos os países habilitados da sua loja. Este campo só é usado quando Ignore shipping zones está ativado.

Avançado

Debug log: grava as requisições da EasyPost em storage/logs/vfd_ep.log.php (no OpenCart 4, system/storage/logs/vfd_ep.log.php). O arquivo não pode ser lido pela web. Quando atinge 5 MB, ele é movido para vfd_ep.old.log.php e um novo log é iniciado. Erros e avisos da API são sempre registrados, mesmo com esta opção desativada. A chave da API e os endereços dos clientes nunca são registrados.

Log: mostra o tamanho e as últimas 100 linhas do log. Clique em Clear log para esvaziá-lo.

Remove data on uninstall: quando ativado, desinstalar a extensão apaga as suas configurações e o log. Os dados da EasyPost dos pedidos feitos são mantidos. Desativar o método nunca apaga as configurações.

Importação / Exportação

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A chave da API não é exportada.

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. A chave da API salva não é alterada.

Como funciona na finalização de compra

Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço da EasyPost. Se uma Geo zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, o método não é oferecido. Só contam os produtos com Requires Shipping definido como Yes: os outros produtos não somam peso e não entram no subtotal. A extensão verifica primeiro as condições: país de destino (com Ignore shipping zones), peso do carrinho e subtotal mínimo. O subtotal é o preço dos produtos que precisam de envio, após o desconto do cupom e antes dos impostos. Vale-presente, pontos de fidelidade e crédito da loja não são considerados. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada à EasyPost.

Caso contrário, a extensão envia à EasyPost o endereço de origem, o endereço de entrega e o pacote, e recebe as tarifas de todas as suas contas de transportadoras. Ela escolhe a tarifa permitida mais barata, converte-a para a moeda padrão da loja e a mostra na moeda do cliente com o imposto da Tax class selecionada. Para os países marcados como Postcode Required em System > Localisation > Countries, a requisição só é feita se o endereço de entrega tiver CEP. Nos dados padrão do OpenCart esse marcador está desativado para os Estados Unidos, então um endereço americano sem ZIP code também é enviado; a EasyPost então retorna um erro e o preço alternativo é usado.

Cada resposta fica em cache por 1 hora para o mesmo endereço e o mesmo pacote. Um endereço sem tarifas utilizáveis é lembrado por 10 minutos. Após um tempo limite, uma chave recusada, um limite de requisições ou um erro do servidor da EasyPost, nenhuma requisição é feita por 5 minutos. O tempo limite da API é de 10 segundos. Em todos esses casos, o cliente não vê erro: o preço alternativo é usado, ou o método fica oculto se não houver preço alternativo. O motivo é gravado no log.

A extensão calcula somente tarifas. Ela não compra etiquetas, não rastreia encomendas, não valida endereços, não oferece pontos de retirada ou de entrega, e não adiciona seguro nem opções de assinatura. Ela mostra uma opção (a tarifa permitida mais barata), não uma lista de serviços. Não há embalagem em caixas além de empilhar os itens em um pacote, e não há acréscimo sobre a tarifa nem taxa de manuseio.

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 o método da EasyPost na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.

Pedidos

Quando um pedido com o método EasyPost é feito, a tarifa mostrada na finalização de compra é guardada com o pedido. A página do pedido na administração (Sales > Orders) mostra o painel EasyPost shipping acima do histórico:

Carrier / service: a transportadora e o serviço da EasyPost da tarifa, por exemplo USPS Priority. No modo um pacote por item, todos os serviços usados são listados.

Estimated delivery days: os dias de entrega retornados pela EasyPost (somente no modo um pacote por pedido, quando a EasyPost os retorna).

Price source: Live EasyPost rate, Fallback price (no live rate) ou Free shipping threshold.

Calculated price (excl. tax): o preço na moeda padrão da loja.

O painel é mostrado mesmo se a extensão for desativada depois. Alterações posteriores do pedido na administração não mudam esses valores. Use-os para comprar a etiqueta na sua conta EasyPost. O OpenCart cria um registro de pedido sempre que a finalização de compra chega à etapa de confirmação; as tarifas salvas desses pedidos não concluídos são removidas após 30 dias.

No OpenCart 4, a finalização de compra mantém um único pedido e o atualiza sempre que o cliente confirma de novo. A tarifa salva é atualizada junto: é a tarifa que o cliente viu na finalização de compra. Se o cliente mudar para outro método de envio, o painel deixa de ser mostrado para esse pedido.

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 EasyPost é o primeiro bloco da página Extensions > Extensions > Shipping > VibeFox EasyPost > Edit, 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: opencart-shipping-easypost e o link Manage licenses and domains in your account, que abre a sua conta em 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 da administração (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 de mudar o endereço da loja, ou depois de liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não estiver acessível, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um 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. Libere-a na sua conta em vibefox.net.

Sem uma chave ativa, o método de envio EasyPost não é mostrado aos clientes na finalização de compra e nenhuma tarifa é calculada. Um usuário administrador conectado à administração 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 vê o login da administração, então sem uma chave ativa o método fica oculto para todos. Depois de abrir a página Edit uma vez, aparece um lembrete no Dashboard da administração. 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 o Dashboard ou a página Edit da administração: uma vez por dia nos primeiros 14 dias após a chave ser inserida, depois uma vez por semana. Não é necessário cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

A EasyPost não aparece na finalização de compra: confira se a licença está ativa e se Enable EasyPost shipping está ativado. Verifique Geo zone (ou Ignore shipping zones e Countries), os limites de peso e o Minimum subtotal. Sem tarifa em tempo real, o método precisa de um preço alternativo para o país ou para Other countries. Confira se os produtos têm Requires Shipping definido como Yes.

As tarifas em tempo real não aparecem: leia os avisos no topo da página da extensão, depois ative o Debug log, recarregue a finalização de compra e veja o campo Log. Motivos comuns: sem chave da API ou CEP de origem, uma loja que não usa USD sem a USD exchange rate, o endereço de entrega ainda não tem CEP, nenhuma transportadora da sua conta EasyPost atende o endereço, ou Allowed carriers / services filtra todas as tarifas.

As tarifas parecem preços de teste: uma chave de teste (EZTK...) está definida. Use uma chave de produção (EZAK...) na loja em funcionamento.

As tarifas pararam por alguns minutos: após um tempo limite, uma chave recusada ou um erro do servidor da EasyPost, a extensão pausa as requisições por 5 minutos e usa os preços alternativos. Confira a chave da API e o log.

O imposto está incluído? As tarifas da EasyPost não incluem imposto sobre vendas. Escolha a classe de imposto em Tax class para adicionar imposto ao frete.

As tarifas parecem desatualizadas depois de uma mudança: clique em Save na página da extensão. Isso limpa as tarifas da EasyPost em cache.

A página mostra "Warning: You do not have permission to modify VibeFox EasyPost!": 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_easypost (OpenCart 3) ou extension/vfd_easypost/shipping/vfd_easypost (OpenCart 4) em System > Users > User Groups.

Para desenvolvedores: outras extensões podem ajustar o corpo da requisição, a tarifa escolhida e a URL base da API com os eventos do OpenCart vfd_easypost/shipment_request, vfd_easypost/selected_rate e vfd_easypost/api_url.

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox EasyPost. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable EasyPost shipping, Sort order, Tax class e Geo zone. A extensão sempre remove os seus eventos e as tarifas em cache. Se Remove data on uninstall estiver ativado, as demais configurações e o log também são apagados. Se estiver desativado, as configurações são mantidas e usadas novamente quando você instalar a extensão de novo. Os dados da EasyPost dos pedidos feitos nunca são apagados, e os pedidos existentes mantêm o seu método de envio e o seu custo.

Para remover também os arquivos da extensão no OpenCart 4, vá em Extensions > Installer depois da desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox EasyPost na lista de extensões instaladas, depois em Delete (o botão vermelho de lixeira) para apagar o pacote enviado.

EasyPost é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela EasyPost.