VibeFox Andreani 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), com o tema padrão.
PHP: 8.0 ou superior.
Conta na Andreani (somente para cotações em tempo real): as cotações em tempo real usam a API de cotação da Andreani. A Andreani fornece a clientes empresariais credenciais de API, um código de cliente e números de contrato, normalmente a partir de cerca de 300 envios por mês. Consulte developers.andreani.com ou escreva para ventapyme@andreani.com. Você precisa do nome de usuário e da senha da API, do código de cliente (código de cliente) e do número do contrato. A Andreani emite um contrato separado para cada serviço (entrega em domicílio, retirada em filial). Sem acesso à API, use preços fixos. O seletor de filial funciona sem credenciais.
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 o README.txt, o pacote do OpenCart 3 vfd_andreani-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_andreani.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 administrador, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_andreani-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. Localize VibeFox Andreani 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. Informe 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 Chave de licença).
5. Defina o nome, a origem das tarifas, os preços por país (por exemplo AR=5000) e, para cotações em tempo real, as credenciais da API, o código de cliente e o número do contrato (veja Configuração). Clique em Save.
OpenCart 4
1. No administrador, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_andreani.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir 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. Localize VibeFox Andreani, clique em Install (o botão verde +) e depois em Edit (o botão de 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 campos são iguais nas duas versões.
Após a instalação, Enable/Disable e Enable second option ficam desativados, e a Andreani não é oferecida na finalização de compra até que você ative uma opção e clique em Save. Se você instalar a extensão novamente após uma desinstalação, as configurações da Andreani que você manteve voltam a ser usadas, mas as duas opções ficam desativadas: ative-as e clique em Save.
Configuração
Todas as configurações ficam na página da extensão: Extensions > Extensions > Shipping > VibeFox Andreani > Edit. As seções aparecem à esquerda. Um único botão Save salva a página inteira sem recarregá-la. Depois de salvar, você verá Settings saved. Cached token, branches and rates were cleared. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações.
No topo da página aparecem avisos sobre configurações que faltam: cotações da API selecionadas sem o nome de usuário e a senha da API ou sem número de contrato, ausência de ARS exchange rate quando a moeda da loja não é ARS, ou ausência de preço para a Argentina em Country prices. Um aviso também aparece se a unidade de peso ou de comprimento da loja não for reconhecida pela extensão (os pesos são então lidos em kg, e as dimensões em cm).
Ao salvar, são recusados, sem salvar nada, um nome vazio, um nome com mais de 64 caracteres ou com algum dos caracteres < > ; = # { }, um Min weight (kg) maior que Max weight (kg), ou um Sort order que não seja um número inteiro. Um valor que não seja número, um número negativo ou um ARS exchange rate igual ou menor que 0 não são salvos, e um aviso indica o campo.
Geral
A Andreani tem duas opções na finalização de compra: a opção principal, configurada aqui e em Andreani API e Delivery and rates, e a Second option. Ambas aparecem sob o título Andreani na etapa de método de envio.
Enable/Disable: ativa ou desativa a opção principal da Andreani. Padrão: desligado. A segunda opção tem um interruptor próprio.
Name: o nome da opção principal mostrado ao cliente na finalização de compra. Padrão: Andreani. Obrigatório.
Tax status: None (the API rate is taken with IVA) (padrão), ou uma das suas classes de imposto. Com uma classe de imposto, o OpenCart acrescenta imposto ao custo do envio, então a tarifa da API é usada sem IVA. Com None, a tarifa da API é usada com o IVA incluído. Vale para as duas opções.
Sort order: a posição da Andreani entre os métodos de envio na finalização de compra. Um número inteiro.
Andreani API (necessária para cotações em tempo real)
Environment: Sandbox / QA (apisqa.andreani.com) (padrão) ou Production (apis.andreani.com). Use o ambiente ao qual pertencem as suas credenciais.
API username: seu nome de usuário da API da Andreani.
API password: sua senha da API da Andreani. Depois de salvar, o campo fica vazio e mostra Saved - leave empty to keep it. Clearing the API username removes it too. Digite um valor novo somente se quiser alterá-la.
Client code: o código de cliente (código de cliente) fornecido pela Andreani, por exemplo CL0000000.
Contract number: o contrato do serviço usado para as tarifas, por exemplo entrega em domicílio. A segunda opção pode usar outro contrato, por exemplo para retirada em filial.
Origin branch code: filial de origem opcional (sucursalOrigen) para as cotações. Deixe vazio para usar a filial configurada no seu contrato.
Entrega e tarifas
Delivery modality: a modalidade da opção principal. A primeira parte indica de onde a Andreani retira o pacote (o seu endereço ou uma filial onde você o deixa). A segunda parte indica onde o cliente o recebe.
Rate source: como o preço é calculado.
Country prices: um preço fixo por país de destino na moeda padrão da loja, sem impostos, uma linha por país no formato CC=PREÇO, por exemplo AR=5000. Usado no modo fixo e como alternativa quando a API falha. Países sem linha não recebem preço fixo. Linhas em outro formato são ignoradas, e um aviso as lista ao salvar.
ARS exchange rate: a Andreani cota em pesos argentinos. Só é necessário se a moeda padrão da loja não for ARS: o valor de 1 ARS na moeda da loja, por exemplo 0.001. Sem ele, as tarifas da API não são usadas.
Default product weight (kg): usado para produtos sem peso ao solicitar tarifas à API e ao verificar os limites de peso. Vazio significa 0,5 kg.
Calculation type: Per order (padrão) cobra o preço uma vez. Per item (price x number of items) multiplica o preço fixo de Country prices pelo número de itens do carrinho. Uma tarifa da Andreani em tempo real já é para o carrinho inteiro e não é multiplicada.
Disponibilidade
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 ele for excedido. Padrão: 100. Vazio significa 100 kg, 0 significa sem limite.
Minimum subtotal: mostra o método somente quando o subtotal do carrinho (produtos que precisam de envio, após o cupom, sem impostos, na moeda padrão da loja) é pelo menos este valor. Deixe vazio para sempre mostrá-lo.
Geo zone: oferece a Andreani 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 é usada quando Ignore shipping zones está ativo.
Ignore shipping zones: oferece a Andreani para os países listados abaixo, independentemente da zona geográfica. Padrão: desligado.
Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países. Usado somente quando Ignore shipping zones está ativo.
Frete grátis
Free shipping: ativa o limite para frete grátis. Padrão: desligado.
Free shipping from: o subtotal do carrinho (na moeda padrão da loja) a partir do qual o envio é grátis. Requer que Free shipping esteja ativo.
Segunda opção
Uma segunda opção da Andreani com nome, modalidade de entrega e contrato próprios, por exemplo "a domicilio" na opção principal e "retiro en sucursal" aqui, para oferecer as duas. Todas as outras configurações são compartilhadas.
Enable second option: oferece a segunda opção na finalização de compra. Padrão: desligado.
Second option name: o nome desta opção na finalização de compra. Padrão: Andreani - branch pickup. Obrigatório.
Delivery modality: Use global setting ou uma das quatro modalidades. Padrão: Door to branch (Puerta a Sucursal).
Contract number: a Andreani emite um contrato separado por serviço (entrega em domicílio, retirada em filial). Deixe vazio para usar o contrato global.
Seletor de filial (mostrado para Door to branch e Branch to branch)
Province select width: a largura CSS da lista de estados, por exemplo 100% ou 300px. Padrão: 100%.
Branch select width: a largura CSS da lista de filiais, por exemplo 100% ou 400px. Padrão: 100%.
Avançado
Debug log: registra as requisições à API e os cálculos de tarifas em storage/logs/vfd_andr_debug.log.php. O arquivo não pode ser lido pela web. Erros são sempre registrados. Credenciais e tokens nunca são registrados. Quando o arquivo chega a 5 MB, ele é movido para vfd_andr_debug.old.log.php e um novo log é iniciado.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para limpá-lo.
Remove data on uninstall: quando ativo, desinstalar a extensão apaga todas as configurações da Andreani e o log. Quando desativado (padrão), são mantidos para uma reinstalação. Os dados de filial salvos nos pedidos são sempre mantidos.
Importar / Exportar
Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A senha 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 senha da API salva é mantida.
Como funciona na finalização de compra
Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço de cada opção da Andreani ativa. Se uma Geo zone estiver definida e Ignore shipping zones estiver desligado, a Andreani não é oferecida para endereços fora da zona geográfica. Só contam os produtos com Requires Shipping definido como Yes: os demais não adicionam peso e não entram no subtotal. Em seguida, a extensão verifica os países (quando Ignore shipping zones está ativo), o peso do carrinho (os pesos dos produtos são convertidos para kg, e os produtos sem peso usam Default product weight (kg)) e o Minimum subtotal. O subtotal é o preço dos produtos que precisam de envio, após o desconto do cupom e sem impostos.
No modo fixo, o preço é obtido de Country prices. Nos modos de cotação em tempo real, a extensão faz login na API da Andreani e solicita uma cotação com o CEP de destino, o contrato, o código de cliente, o peso em kg, o volume calculado a partir das dimensões dos produtos e o valor declarado (o subtotal do carrinho em ARS). Uma cotação em tempo real só é solicitada para um CEP argentino válido (4 dígitos, ou um CPA como C1425ABC). O valor em ARS é convertido com ARS exchange rate quando a moeda da loja não é ARS. O preço é calculado na moeda padrão da loja, arredondado para as suas casas decimais e mostrado ao cliente na moeda dele, com o imposto da Tax status selecionada.
O token de login é mantido por até 23 horas e renovado automaticamente quando a Andreani o rejeita. As cotações ficam em cache por 1 hora. Uma chamada à API que falhou não é repetida por 5 minutos. Tudo isso fica armazenado no cache do OpenCart, então uma entrada nunca é mantida por mais tempo que a duração do cache do OpenCart (1 hora por padrão) e é então solicitada novamente. Erros da API nunca são mostrados ao cliente: a opção fica oculta, ou o preço fixo é usado no modo de contingência. O motivo é gravado no log.
Se Free shipping estiver ativo e o subtotal do carrinho atingir Free shipping from, o preço é 0. O frete grátis se aplica somente quando a opção tem preço: se a API da Andreani não retornar tarifa e não houver preço fixo de contingência, a opção não é mostrada.
A extensão não cria envios da Andreani, não imprime etiquetas e não rastreia pacotes. Para isso, use o portal web da Andreani.
No OpenCart 4, o cliente clica em Choose no bloco de método de envio da página de finalização de compra e escolhe uma opção da Andreani na janela Shipping method options. As opções funcionam do mesmo modo que no OpenCart 3; a seleção de filial é descrita em Pontos de retirada.
Pontos de retirada
Quando é oferecida uma opção com Door to branch ou Branch to branch, logo abaixo dela, na etapa de método de envio, aparecem uma lista de estados e uma lista de filiais. O estado é pré-selecionado a partir da região do endereço de entrega. A lista de filiais vem da API pública de filiais da Andreani e fica em cache por até 12 horas (dentro da duração do cache do OpenCart). Filiais que não recebem pacotes não são listadas. A etapa de entrega em si nunca espera pela Andreani: se a lista ainda não estiver em cache, ela é carregada em segundo plano e o cliente vê brevemente Loading Andreani branches.... Se não houver filiais disponíveis, o cliente vê No Andreani branches available right now. Please try again later or choose another shipping method.
A escolha é salva assim que o cliente a faz. Somente uma filial da lista atual da Andreani é aceita. Sem uma filial, Continue na etapa de entrega não avança, e o cliente vê Please select an Andreani pickup branch. O servidor verifica a filial novamente quando o cliente continua. Se a filial não estiver mais na lista, o cliente vê The selected Andreani branch is not available. Please choose another one.
No OpenCart 4, a lista de estados e a lista de filiais aparecem na janela Shipping method options, logo abaixo da opção da Andreani com filial, com os mesmos textos e verificações. Continue na janela sem filial é bloqueado com a mensagem Please select an Andreani pickup branch. sob a opção. Se a loja recusar a filial quando o cliente continuar, a mensagem aparece no topo da página de finalização de compra e a janela permanece aberta. O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza a cada confirmação; a filial do pedido é atualizada junto com ele, e é removida quando o cliente muda o pedido para outro método de envio.
Uma filial escolhida em uma opção da Andreani não pertence a um pedido feito com outra opção ou outro método de envio.
O seletor foi feito para a finalização de compra de página única do tema padrão do OpenCart 3 e para a finalização de compra do tema padrão do OpenCart 4. Um tema com outra estrutura na etapa de entrega pode precisar de ajustes no script do seletor.
Pedidos
O pedido guarda a modalidade de entrega e, para as modalidades com filial, a filial escolhida.
Shipping method of the order: a filial é acrescentada ao texto do método de envio, por exemplo Andreani - branch pickup: e o nome da filial. Se o nome da opção não mencionar uma filial, o texto Pickup branch: (ou Andreani pickup branch: quando o nome não contém Andreani) é acrescentado antes do nome da filial, por exemplo Andreani - Pickup branch: e o nome da filial. Esse texto aparece nos e-mails de pedido ao cliente e à loja, no histórico de pedidos do cliente, na fatura e na página do pedido no administrador. O OpenCart limita o texto a 128 caracteres; os dados completos da filial são mantidos pela extensão. A página de sucesso do pedido do OpenCart não mostra o método de envio.
Admin order page: em Sales > Orders, abra um pedido. Um painel Andreani mostra Andreani modality e, para as modalidades com filial, Andreani branch (nome, ID e estado). Clique em Edit, escolha outro estado e outra filial e clique em Save para alterá-la. Você verá Branch updated., e a filial no texto do método de envio do pedido também é substituída. Somente filiais da lista da Andreani podem ser salvas. Se a lista não estiver disponível, você verá The Andreani branch list is not available right now - the branch cannot be changed. Alterar a filial exige a permissão de modificação para sale/order e acesso a extension/shipping/vfd_andreani (OpenCart 3) ou extension/vfd_andreani/shipping/vfd_andreani (OpenCart 4). O painel também é mostrado para pedidos já feitos com a Andreani enquanto a extensão estiver desativada.
Enquanto a extensão estiver desativada, o painel Andreani não é mostrado. Os dados da filial continuam salvos e o texto do método de envio do pedido não muda. Os pedidos existentes mantêm os próprios dados de filial.
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 Andreani é o primeiro bloco em Extensions > Extensions > Shipping > VibeFox Andreani > 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 ficam a linha Product: opencart-shipping-andreani 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 administrador (inglês e russo estão incluídos).
Se a chave não for aceita, o bloco mostra 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 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 na configuração do OpenCart. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, as opções de envio da Andreani não são mostradas aos clientes na finalização de compra e nenhuma cotação é calculada. Um usuário administrador conectado ao administrador 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 no administrador, 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 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 precisam de renovação. O status é verificado de novo automaticamente 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 informada e, 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 Andreani não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado (para a segunda opção, também Enable second option) e se você clicou em Save após a instalação. Verifique Geo zone, ou Ignore shipping zones e Countries. Confirme que Country prices tem uma linha para o país (para preços fixos ou como alternativa), os limites de peso e o Minimum subtotal. Leia os avisos no topo da página Edit. Confirme que os produtos têm Requires Shipping definido como Yes.
As cotações em tempo real não aparecem: ative Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão. Ele mostra o motivo: credenciais ou número de contrato ausentes, falha de login (nome de usuário, senha ou ambiente incorretos), ainda não há um CEP argentino válido, não há cotação de câmbio ou há um erro HTTP da Andreani. Com Andreani API, fixed price if the API fails, os clientes continuam recebendo o preço fixo enquanto você corrige o problema.
Minha loja não está em pesos argentinos: defina ARS exchange rate com o valor de 1 ARS na moeda padrão da sua loja.
O imposto do envio parece errado: com uma classe de imposto em Tax status, a tarifa da Andreani sem IVA é usada e o OpenCart acrescenta o próprio imposto. Com None, a tarifa com IVA é usada e nenhum imposto é acrescentado. Verifique se os impostos estão ativados nas configurações da loja e se a classe de imposto tem alíquotas para a Argentina.
Nenhuma filial na lista: a API de filiais da Andreani não respondeu. Uma requisição que falhou é repetida após 5 minutos. Verifique o log.
O estado errado está pré-selecionado: o estado é lido a partir da região do endereço de entrega. O cliente sempre pode escolher outro estado.
As tarifas parecem desatualizadas após uma mudança: clique em Save na página da extensão. Isso limpa o token, a lista de filiais e as tarifas em cache.
A página diz "Warning: You do not have permission to modify VibeFox Andreani!": 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_andreani (OpenCart 3) ou extension/vfd_andreani/shipping/vfd_andreani (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: os hosts da API da Andreani podem ser substituídos pela configuração vfd_andr_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 Andreani. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine o status, Sort order, Tax status e Geo zone. A extensão sempre remove seus manipuladores das páginas de finalização de compra e de pedido, além do token, da lista de filiais e das tarifas em cache. Se Remove data on uninstall estiver ativo, todas as configurações da Andreani 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 dados de filial salvos nos pedidos nunca são apagados, 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 após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Andreani na lista de extensões instaladas, depois em Delete (o botão vermelho de lixeira) para remover o pacote enviado.
Andreani é uma marca de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela Andreani.