VibeFox Estafeta for OpenCart — Ajuda

Requisitos

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

PHP: 8.0 ou superior com a extensão cURL.

Conta na DrEnvio (somente para tarifas em tempo real): as tarifas em tempo real da Estafeta vêm da DrEnvio, parceira da Estafeta no México. Crie uma conta em drenvio.com, habilite a Estafeta, configure lá o seu endereço de coleta e copie a chave de API do seu painel da DrEnvio. É a mesma chave que o plugin oficial da DrEnvio usa. Se você usar apenas os seus próprios preços, não precisa de conta na DrEnvio.

Produtos: os produtos precisam ter peso para as tarifas em tempo real.

Chave de licença VibeFox: comprada 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 README.txt, o pacote do OpenCart 3 vfd_estafeta-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_estafeta.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, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_estafeta-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 instalador, 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 Estafeta 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. 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 Chave de licença).

5. Informe a DrEnvio API key e, opcionalmente, o Origin postcode. Se a moeda padrão não for MXN, informe o MXN exchange rate. Defina um preço para o país MX ou um Fallback cost se o método deve continuar visível quando a DrEnvio não tiver tarifa. Ative Enable/Disable e clique em Save.

OpenCart 4

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

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

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

No topo da página, a extensão mostra avisos: falta a chave de API da DrEnvio, a moeda padrão não é MXN e não há taxa de câmbio, não há preço para o país MX e não há custo de reserva (o método fica oculto quando não há tarifa em tempo real, ou nunca aparece sem chave de API), ou não há classe de peso com a unidade kg (os pesos dos produtos são então convertidos pelo nome da unidade da sua classe de peso, e unidades desconhecidas são tratadas como kg; adicione uma classe kg em System > Localisation > Weight Classes). Os campos numéricos aceitam ponto ou vírgula decimal. Ao salvar, um valor inválido é informado e apagado ou redefinido como descrito em cada campo, o formulário mostra o valor salvo, e as demais configurações são salvas normalmente (The other settings were saved.).

Geral

O método é oferecido para a zona geográfica abaixo (ou para todos os endereços), ou para os países de Availability without shipping zones.

Enable/Disable: ativa ou desativa o envio pela Estafeta. Padrão: desativado.

Name: o nome do método de envio exibido ao cliente no checkout. Padrão: Estafeta. Obrigatório: de 1 a 64 caracteres, sem < > ; = # { }. Um nome inválido é informado e o nome anterior é mantido.

Tax class: a classe de imposto acrescentada ao custo do frete, ou No tax (padrão). Se os preços da DrEnvio incluem IVA depende da sua conta na DrEnvio. Se já incluem, escolha No tax.

Geo zone: oferece a Estafeta somente para endereços dessa zona geográfica, por exemplo uma zona "México". All zones (padrão) significa sem limite. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones. Não é usada quando Ignore shipping zones está ativado.

Sort order: a posição da Estafeta entre os métodos de envio no checkout. Um número inteiro.

Tarifas em tempo real (API da DrEnvio)

A seção explica onde obter a chave. É oferecido o serviço Estafeta mais barato para o endereço. Sem chave, são usados os preços de Prices without a live rate.

DrEnvio API key: a chave de API do seu painel da DrEnvio. Depois de salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-la.

Remove the saved API key: aparece somente enquanto há uma chave salva. Ative e salve para excluir a chave. Depois disso, são usados apenas Country prices e o Fallback cost. Uma chave digitada no campo acima substitui a salva.

Origin country: o código de país de duas letras do endereço de coleta. Padrão: MX. É enviado somente junto com o CEP de origem. Um código inválido é informado e volta para MX.

Origin postcode: o CEP de 5 dígitos do endereço de coleta. Deixe vazio para usar o endereço de origem salvo na sua conta da DrEnvio. Um CEP que não tenha 5 dígitos é apagado e informado ao salvar.

MXN exchange rate: a DrEnvio cotiza em pesos mexicanos. É necessário somente se a moeda padrão não for MXN: o valor de 1 MXN na sua moeda padrão, por exemplo 0.05. Sem ele, as tarifas em tempo real não são usadas. Deve ser maior que 0. Se a moeda da loja for MXN, deixe vazio.

Preços sem tarifa em tempo real

Usados quando não há chave de API ou a DrEnvio não devolve nenhuma tarifa da Estafeta (API indisponível, CEP desconhecido, CEP ainda não informado). Os preços estão na moeda padrão da loja, sem impostos.

Country prices: um país de destino por linha, no formato CC:PREÇO, por exemplo MX:150. Use ponto ou vírgula decimal, sem separador de milhar. As partes em outro formato são ignoradas e informadas ao salvar.

Fallback cost: o preço quando não há tarifa em tempo real nem preço por país. Deixe vazio para ocultar o método; 0 significa frete grátis.

Calculation type: Per order (padrão) cobra o preço uma vez. Per item (price x number of items) o multiplica pelo número de itens no carrinho. Isso se aplica a Country prices e ao Fallback cost. Uma tarifa em tempo real da DrEnvio é sempre o preço de toda a encomenda.

Condições

Free shipping from: o frete é grátis quando o subtotal dos produtos que precisam de envio (depois do cupom, antes dos impostos) atinge este valor. Nesse caso, nenhuma solicitação é enviada à DrEnvio. Deixe vazio para nunca oferecer frete grátis.

Minimum subtotal: mostra o método somente se o mesmo subtotal for pelo menos este valor. Deixe vazio para sempre mostrá-lo.

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

Max weight (kg): o peso máximo do carrinho. O método fica oculto se for ultrapassado. Padrão: 30. 0 significa sem limite.

Se Min weight for maior que Max weight, ao salvar aparece um erro e os dois pesos permanecem sem alteração. Os pesos dos produtos são convertidos para kg pela classe de peso de cada produto.

Disponibilidade sem zonas de envio

Ignore shipping zones: oferece o método para os países abaixo sem verificar a zona geográfica. Padrão: desativado.

Countries: os países de destino para esse modo. Deixe vazio para todos os países. Usado somente quando Ignore shipping zones está ativado.

Avançado

Debug log: grava as solicitações à API e os cálculos de tarifas em storage/logs/vfd_est_debug.log.php (no OpenCart 4 system/storage/logs/vfd_est_debug.log.php). O arquivo não pode ser lido pela web. Os erros da API são sempre registrados, mesmo com o log desativado. A chave de API e os endereços dos clientes nunca são registrados. Desative o log quando terminar. Quando o arquivo chega a 5 MB, ele é movido para vfd_est_debug.old.log.php e um novo log é iniciado.

Log: mostra o tamanho e as entradas mais recentes do log de depuração. Clique em Clear log para esvaziá-lo.

Remove data on uninstall: quando ativado, desinstalar a extensão apaga todas as suas configurações e o log. Quando desativado (padrão), tudo é mantido para uma reinstalação. Os serviços da Estafeta salvos nos pedidos são sempre mantidos.

Importar / Exportar

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A chave de 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 de API salva é mantida.

Como funciona no checkout

Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço da Estafeta. Se uma Geo zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, a Estafeta não é oferecida. Só contam os produtos com Requires Shipping definido como Yes: os demais não somam peso e não entram no subtotal. O subtotal é o preço desses produtos depois do desconto do cupom e antes dos impostos; vales-presente, pontos de fidelidade e crédito da loja não são considerados. Em seguida, a extensão verifica as condições: a lista Countries (quando Ignore shipping zones está ativado), 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 à DrEnvio.

Caso contrário, a extensão envia à DrEnvio o país e o CEP de destino, o peso do carrinho, o número de itens e o subtotal em MXN, além do CEP de origem, se você tiver definido um. Os CEPs mexicanos devem ter 5 dígitos; até que o cliente informe um endereço de entrega com esse formato, nenhuma solicitação é feita. A DrEnvio devolve cotações de todas as transportadoras da sua conta. A extensão usa somente as cotações da Estafeta, ignora preços zerados, escolhe a mais barata e a converte para a sua moeda padrão. O preço é arredondado para as casas decimais dessa moeda e mostrado ao cliente na moeda dele, com o imposto da Tax class selecionada.

Cada resposta fica em cache por 1 hora. Uma solicitação com falha ou uma rota sem tarifa da Estafeta é lembrada por 5 minutos, para que uma API lenta ou com defeito nunca atrase cada atualização do checkout. O tempo limite da API é de 12 segundos. Nesses casos, o cliente não vê nenhum erro: é usado o preço por país ou o custo de reserva, ou o método fica oculto se nenhum dos dois estiver definido. O motivo é gravado no log.

O cliente vê somente o nome do método e o preço. A extensão apenas calcula as tarifas. Ela não cria envios, não imprime etiquetas (guías) e não rastreia encomendas; crie o envio na sua conta da DrEnvio ou da Estafeta. O cliente não pode escolher um serviço específico da Estafeta nem uma agência da Estafeta, e os câmbios não são atualizados automaticamente.

No OpenCart 4, o cliente clica em Choose no bloco de métodos de envio da página de checkout e escolhe a Estafeta na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.

Pedidos

Quando um pedido com a Estafeta é feito, a extensão salva a tarifa mostrada ao cliente, sem uma nova solicitação à DrEnvio. Alterações posteriores do pedido no administrativo não a modificam. No OpenCart 4, o checkout mantém um único pedido e o atualiza sempre que o cliente confirma novamente, por isso a tarifa salva é substituída pela tarifa mais recente do checkout. Se o cliente mudar para outro método de envio, o painel deixa de ser mostrado para esse pedido.

A página do pedido em Sales > Orders mostra um painel Estafeta:

Estafeta service: o serviço da Estafeta da cotação da DrEnvio e o seu prazo de entrega. Mostrado somente para tarifas em tempo real.

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

Shipping cost: o preço do frete calculado no checkout na moeda padrão da loja, sem impostos.

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 Estafeta é o primeiro bloco em Extensions > Extensions > Shipping > VibeFox Estafeta > Edit, acima das configurações. Cole 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-estafeta e o link Manage licenses and domains in your account, que abre a sua conta na 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 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 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 único 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 dela. Libere a vaga na sua conta da vibefox.net.

Sem uma chave ativa, a Estafeta não é mostrada aos clientes no checkout e nenhuma tarifa é calculada. Um usuário administrador conectado ao 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 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 de novo automaticamente quando você abre o Dashboard do administrativo 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 é 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 Estafeta não aparece no checkout: verifique se a licença está ativa e se Enable/Disable está ativado. Verifique Geo zone, ou Ignore shipping zones e Countries. Verifique os avisos no topo da página da extensão, os limites de peso e Minimum subtotal. Sem chave de API, ou quando a DrEnvio não tem tarifa da Estafeta, o método precisa de um preço por país para o destino ou de um custo de reserva. Verifique se os produtos têm Requires Shipping definido como Yes.

As tarifas em tempo real não aparecem: ative Debug log, recarregue o checkout e veja o campo Log na página da extensão. Ele mostra o motivo: sem chave de API, sem taxa de câmbio para uma loja cuja moeda padrão não é MXN, CEP ausente ou inválido, chave de API rejeitada (HTTP 401 ou 403 da DrEnvio; verifique a chave de API), nenhuma tarifa da Estafeta para a rota (o log lista as transportadoras que a DrEnvio devolveu), ou uma tarifa em moeda diferente de MXN.

O preço inclui IVA? Isso depende da sua conta na DrEnvio. Se os preços da DrEnvio já incluem IVA, defina Tax class como No tax.

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

A página do pedido não tem o painel da Estafeta: o painel é mostrado somente para pedidos feitos com a Estafeta enquanto a extensão estava instalada e ativada.

A página diz "Warning: You do not have permission to modify VibeFox Estafeta!": o seu grupo de usuários administradores só pode visualizar as configurações. Conceda ao grupo a permissão de modificação para extension/shipping/vfd_estafeta (OpenCart 3) ou extension/vfd_estafeta/shipping/vfd_estafeta (OpenCart 4) em System > Users > User Groups.

Para desenvolvedores: o endereço da API da DrEnvio pode ser substituído pela configuração vfd_est_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 Estafeta. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable/Disable, 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 Estafeta e o log de depuração também são excluídos. Se estiver desativado, as demais configurações são mantidas e voltam a ser usadas quando você reinstalar a extensão. Os serviços da Estafeta salvos nos pedidos são mantidos nos dois casos, e os pedidos mantêm o método e o custo de envio.

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

Estafeta e DrEnvio são marcas de seus respectivos proprietários. Esta extensão não é afiliada nem endossada pela Estafeta ou pela DrEnvio.