VibeFox Shippo for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e posteriores (testado na 4.1.0.3).

PHP: 8.0 ou superior.

Conta Shippo: crie uma conta na Shippo, conecte ou ative as transportadoras (USPS, UPS, FedEx, DHL e outras) e copie o token de API em Shippo > Settings > Advanced > API. A Shippo cobra pelas etiquetas compradas, não pelas consultas de tarifas. Contas novas na Shippo podem precisar ser verificadas pela Shippo antes que tarifas em tempo real sejam retornadas. Sem token, apenas os preços de contingência são usados.

Produtos: os produtos devem ter peso e dimensões. Produtos sem dimensões usam o tamanho de caixa padrão.

Chave de licença VibeFox: obtida 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 para OpenCart 3 vfd_shippo-oc3-(version).ocmod.zip e o pacote para OpenCart 4 vfd_shippo.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 painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_shippo-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 do pacote para a pasta raiz da sua loja.

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

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

4. Insira sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Edit e clique em Activate (veja License key).

5. Cole seu token de API da Shippo e preencha o endereço de Ship from. O CEP (código postal) é obrigatório para as tarifas em tempo real.

6. Escolha a Shippo rate currency (USD se você envia dos EUA) e, se a moeda padrão da sua loja for diferente, informe a Exchange rate.

7. Opcionalmente, informe preços de contingência, ative Enable Shippo shipping e clique em Save.

OpenCart 4

1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_shippo.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 Shippo, clique em Install (o botão verde +) e depois em Edit (o botão com lápis).

4. Insira a chave de licença e as configurações como nos passos 4 a 7 do OpenCart 3. A página de configurações e seus campos são iguais nas duas versões.

Após a instalação, o método fica desativado até que você ative Enable Shippo shipping e salve. Se você instalar a extensão novamente depois de desinstalá-la, as configurações da Shippo 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 Shippo > Edit. As seções ficam listadas à esquerda. Um botão Save salva a página inteira sem recarregá-la. Cada salvamento também limpa as tarifas da Shippo em cache. Somente administradores com a permissão de modificação para esta extensão podem salvar as configurações.

Avisos no topo da página informam quando o método nunca poderá ser exibido ou quando as tarifas em tempo real não podem ser usadas: token de API ausente, CEP ou país de origem ausentes, taxa de câmbio ausente, ou uma unidade de peso ou de comprimento da loja que a extensão não reconhece (use kg, g, lb ou oz e cm, mm, m ou in em System > Settings, aba Local). Um aviso lembra quando um token de teste está definido. Ao salvar, um nome inválido, um valor que não é número, um número ou uma célula de preço negativos, um Minimum weight (kg) maior que Maximum weight (kg) ou uma ordem de exibição que não é um número inteiro são informados como erro, e nada é salvo até que você corrija.

Geral

Enable Shippo shipping: oferece o método na finalização de compra. Este é o status da extensão em Extensions > Extensions > Shipping.

Name: o nome do método de envio mostrado ao cliente na finalização de compra. Padrão: Shippo Shipping. Obrigatório, no máximo 64 caracteres, sem os caracteres < > ; = # { }.

Tax class: a classe de imposto do custo de envio, ou No tax. As tarifas da Shippo não incluem imposto sobre vendas. No tax as mostra como cotadas; uma classe de imposto acrescenta imposto sobre o envio conforme as suas regras fiscais.

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

Conta Shippo

API token: seu token de API da Shippo. Use o token ativo (shippo_live_...) para tarifas reais na loja em produção, ou um token de teste (shippo_test_...) para as tarifas de teste da Shippo. O token é enviado somente à Shippo e nunca é registrado. Após salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente para alterá-lo.

Remove the saved API token: ative e salve para excluir o token salvo.

Allowed carriers / services: opcional, separado por vírgulas. Digite uma transportadora como a Shippo a chama (USPS, UPS, FedEx, DHL Express) ou um token de nível de serviço da Shippo (usps_priority, ups_ground). É exibida a tarifa permitida mais barata. Deixe vazio para mostrar a tarifa mais barata de qualquer transportadora.

Ship from (o endereço de onde seus pacotes são enviados)

Quando o país de envio é o país da sua loja, um nome de remetente e um estado vazios são obtidos do nome da loja e da região em System > Settings. O OpenCart não tem rua, cidade ou CEP estruturados para a loja, então informe-os aqui.

Sender name / company: o nome do remetente. Ele também é usado para assinar a declaração alfandegária. Se estiver vazio, o nome da loja é usado.

Street address: a rua do remetente.

City: a cidade do remetente.

State / province: o código do estado com duas letras, por exemplo CA ou NY. Algumas transportadoras precisam dele.

Postal / ZIP code: obrigatório para as tarifas em tempo real, por exemplo 94105.

Country: o país de onde você envia. Padrão: Estados Unidos.

Tarifas

Parcels: como o carrinho é enviado à Shippo.

Default box size: comprimento x largura x altura na unidade de comprimento da sua loja (mostrada no nome do campo), por exemplo 30 x 20 x 10. A Shippo precisa do tamanho da caixa. Ele é usado quando um produto do carrinho não tem dimensões. Deixe vazio para usar 30 x 20 x 10 cm. Um valor que não pode ser lido é ignorado com um aviso após salvar, e as demais configurações são salvas.

Shippo rate currency: a moeda em que a Shippo cota suas transportadoras, que é a moeda do país de envio: USD (EUA), CAD (Canadá), GBP (Reino Unido), EUR (zona do euro) ou AUD (Austrália). Padrão: USD. As tarifas que a Shippo retorna na moeda padrão da sua loja são sempre usadas como estão.

Exchange rate: o preço de 1 unidade da moeda das tarifas da Shippo na moeda padrão da sua loja, por exemplo 0.92. Não é necessário se as duas forem iguais. Sem ele, as tarifas na outra moeda não são usadas e valem os preços de contingência. A extensão não converte moedas automaticamente.

Preços de contingência (usados quando não há tarifa em tempo real: sem token de API, Shippo inacessível, token recusado ou sem tarifas de transportadoras para o endereço; preços na moeda padrão da loja, sem imposto; deixe os dois campos vazios para ocultar o método nesse caso)

Country prices: uma tabela de preços por país e peso do carrinho. Clique em Add country para adicionar uma linha. As colunas são Price e as faixas de peso XS (até 1 kg), S (de 1 a 2 kg), M (de 2 a 3 kg), L (de 3 a 5 kg) e XL (acima de 5 kg). Uma faixa vazia ou 0 usa a coluna Price. A linha * Default se aplica aos países sem linha própria. Uma linha salva com todas as células vazias cobra 0, então exclua as linhas que você não vai preencher.

Other countries: o preço para os países que não estão na tabela acima (quando não há linha * Default). Deixe vazio para ocultar o método para esses países.

Condições

Free shipping from: o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) a partir do qual o frete é grátis. Nenhuma requisição é feita à Shippo nesse caso. Deixe vazio para desativar.

Minimum subtotal: exibe o método somente se 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.

Minimum weight (kg): o peso mínimo do carrinho para exibir o método. 0 significa sem limite (padrão).

Maximum weight (kg): o método é ocultado acima deste peso de carrinho. Padrão: 30. 0 significa sem limite. Um campo vazio é salvo como 30.

Disponibilidade sem zonas de envio

Normalmente, a geo zone decide onde o método é oferecido. Alternativamente, ele pode ser oferecido por país, independentemente da geo zone.

Geo zone: oferece o método somente para endereços nesta geo zone. All zones (padrão) significa sem limite. Não é usada enquanto Ignore shipping zones estiver ativado. As geo zones são gerenciadas em System > Localisation > Geo Zones.

Ignore shipping zones: oferece o método para os países abaixo, estejam ou não na geo zone.

Countries: os países de destino para esse 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 à Shippo em storage/logs/vfd_shpo_debug.log.php (no OpenCart 4, system/storage/logs/vfd_shpo_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. O token de API e os endereços dos clientes nunca são registrados. Quando o arquivo chega a 5 MB, ele é movido para vfd_shpo_debug.old.log.php e um novo log é iniciado.

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

Remove data on uninstall: quando ativado, desinstalar a extensão apaga as configurações da Shippo e o log. Quando desativado (padrão), elas são mantidas para uma reinstalação. As tarifas em cache são sempre removidas. A transportadora e o serviço salvos com os pedidos fazem parte do histórico de pedidos e são mantidos.

Importação / Exportação

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. O token de API 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 token de API salvo não é alterado.

Como funciona na finalização de compra

Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço da Shippo. 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. Somente produtos com Requires Shipping definido como Yes contam: os demais não somam peso e não entram no subtotal. Em seguida, a extensão verifica as condições: os países de Ignore shipping zones, o peso do carrinho e o subtotal mínimo. Vales-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 à Shippo.

A extensão então envia à Shippo o endereço de envio da loja, o endereço do cliente e o pacote. Para países em que o OpenCart exige um CEP, a requisição aguarda até que o cliente o tenha informado. Para envios internacionais, é adicionada uma declaração alfandegária com os nomes dos itens (com as opções escolhidas), quantidades, pesos e valores. A Shippo retorna as tarifas das suas transportadoras, e a extensão usa a tarifa permitida mais barata. O preço é calculado na moeda padrão da sua loja, arredondado para as casas decimais dela e mostrado ao cliente na moeda dele, com o imposto da Tax class selecionada.

No modo por pedido, os itens são empilhados em uma caixa: o lado mais longo e o intermediário dos itens maiores, e os lados menores de todas as unidades somados. Se algum produto não tiver dimensões, o tamanho de caixa padrão é usado para o pacote inteiro. No modo por item, cada produto é tarifado como um pacote próprio e a tarifa é multiplicada pela quantidade.

Cada resposta fica em cache por 1 hora por endereço e pacote. Quando a Shippo responde sem uma tarifa utilizável, o endereço é lembrado por 10 minutos. Após um tempo limite, um token recusado, um erro de servidor ou um limite de requisições, a extensão pausa as requisições por 5 minutos e usa os preços de contingência. O tempo limite da requisição é de 10 segundos.

Se não houver tarifa em tempo real, o preço vem da tabela de contingência e, depois, de Other countries. Se nenhum dos dois se aplicar, o método fica oculto. O cliente nunca vê um erro. O motivo é gravado no log de depuração.

A extensão calcula somente tarifas. Ela não compra etiquetas, não rastreia pacotes, não valida endereços, não oferece pontos de retirada ou entrega, seguro, opções de assinatura ou etiquetas de devolução. Somente a tarifa permitida mais barata é exibida, e não uma lista de todos os serviços. Não há empacotamento em caixas além do empilhamento descrito acima, nem acréscimo sobre a tarifa ou 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 a Shippo na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.

Pedidos

Quando um pedido é feito com uma tarifa Shippo em tempo real, a extensão mantém a Carrier / service escolhida e, para um pacote por pedido, os Estimated delivery days. Abra o pedido em Sales > Orders: eles aparecem no painel Shippo, acima do histórico do pedido, para que você possa comprar a etiqueta correspondente na Shippo. Os dados são salvos com o pedido: alterações posteriores no carrinho ou nas configurações não os modificam. O painel também é exibido após você desativar o método. Pedidos com preço de contingência ou frete grátis não têm painel da Shippo.

O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza sempre que o cliente confirma novamente. A tarifa da Shippo salva é atualizada junto. Se o cliente mudar para outro método de envio, ou se agora valer o preço de contingência, a tarifa salva é removida do 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 Shippo é o primeiro bloco de Extensions > Extensions > Shipping > VibeFox Shippo > 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 ficam a linha Product: opencart-shipping-shippo 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 administrador (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 de alterar 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 puder ser acessado, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o endereço da loja da configuração do OpenCart. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, o método de envio Shippo não é mostrado aos clientes na finalização de compra e nenhuma tarifa é calculada. Um administrador conectado ao painel administrativo 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 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 administrador. 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 exigem uma renovação. O status é verificado novamente de forma automática quando você abre o Dashboard do administrador ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser inserida e, 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

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

As tarifas em tempo real não aparecem: ative o Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão. Motivos comuns: falta o token de API ou o CEP de origem; a moeda padrão da loja é diferente da moeda das tarifas da Shippo sem uma taxa de câmbio; o cliente ainda não informou o CEP; nenhuma transportadora da sua conta Shippo atende o endereço; ou a conta Shippo ainda não foi verificada.

Tarifas de teste na loja em produção: um token de teste (shippo_test_...) retorna tarifas de teste da Shippo. Use o token ativo (shippo_live_...).

Frete grátis para países inesperados: verifique a tabela de preços em busca de uma linha vazia, principalmente uma linha * Default vazia. Uma linha com todas as células vazias cobra 0.

Pesos ou tamanhos de caixa incorretos: se a página avisar sobre uma unidade de peso ou de comprimento desconhecida, defina uma classe de peso em kg, g, lb ou oz e uma classe de comprimento em cm, mm, m ou in em System > Settings, aba Local.

As tarifas parecem desatualizadas após uma alteração: clique em Save na página da extensão. Isso limpa as tarifas da Shippo em cache.

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

Para desenvolvedores: o endereço da API da Shippo pode ser substituído pela configuração vfd_shpo_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 Shippo. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable Shippo shipping, Sort order, Tax class e Geo zone. As tarifas em cache são sempre removidas. Se Remove data on uninstall estiver ativado, as configurações da Shippo 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ê reinstalar a extensão. Os pedidos existentes mantêm o método de envio, o custo e os dados de transportadora e serviço da Shippo.

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

Shippo é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pela Shippo.