VibeFox Andreani for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões mais antigas do PHP.
Conta Andreani (apenas para tarifas em tempo real): as tarifas em tempo real usam a API de cotações 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 e do número do contrato. A Andreani emite um contrato separado para cada serviço (entrega em casa, retirada em filial). Sem acesso à API, use preços fixos. O seletor de filial funciona sem credenciais.
VibeFox license key: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No back office, vá em Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.
2. Quando o upload terminar, clique em Configure ou, depois, encontre VibeFox Andreani na lista de módulos e clique em Configure.
3. Informe sua chave de licença VibeFox em License key, no bloco de licença no topo da página Configure, e clique em Activate (veja Chave de licença).
4. Defina o nome, a fonte das tarifas, os preços por país (por exemplo AR=5000) e, para as tarifas em tempo real, as credenciais da API, o código de cliente e o número do contrato (veja Configuração). Clique em Save.
Ao instalar, o módulo cria duas transportadoras:
As duas transportadoras são atribuídas à zona da Argentina e a todos os grupos de clientes. Você pode alterar zonas, grupos de clientes, prazo de entrega, logotipo e limites de tamanho em Shipping > Carriers. Não defina preços ali: o preço sempre vem do módulo.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Andreani > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Depois de salvar, você vê Settings saved. Cached token, branches and rates were cleared. Os avisos sobre configurações ausentes (credenciais da API, número do contrato, taxa de câmbio ARS, nenhum preço para a Argentina, uma transportadora excluída) aparecem no topo da página. Um aviso também aparece se o módulo não reconhecer a unidade de peso ou de dimensão da loja (nesse caso, os pesos são lidos como kg e as dimensões como cm). Ao salvar, um nome com mais de 64 caracteres ou um Min weight (kg) maior que Max weight (kg) são recusados, e nada é salvo. Um valor que não é número, um número negativo ou uma ARS exchange rate igual ou menor que 0 não é salvo, e um aviso indica o campo.
General
Enable/Disable: liga ou desliga o envio pela Andreani. É o mesmo interruptor do status da transportadora principal em Shipping > Carriers. A segunda opção tem seu próprio interruptor.
Name: o nome da transportadora mostrado ao cliente na finalização de compra. Padrão: Andreani. Obrigatório.
Tax status: None, ou Taxable com uma das suas regras de imposto. Com uma regra de imposto, a loja adiciona o imposto ao custo do envio, então a tarifa da API é usada sem IVA. Com None, a tarifa da API é usada com IVA incluído. A configuração é salva nas duas transportadoras da Andreani.
Andreani API (necessário para tarifas em tempo real)
Environment: Sandbox / QA (apisqa.andreani.com) (padrão) ou Production (apis.andreani.com). Use o ambiente ao qual suas credenciais pertencem.
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 novo valor apenas para alterá-lo.
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 casa. A segunda opção pode usar outro contrato, por exemplo para a 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 transportadora principal. A primeira parte indica onde a Andreani pega a encomenda (seu endereço ou uma filial onde você a deixa). A segunda parte indica onde o cliente a recebe.
Rate source: como o preço é calculado.
Country prices: um preço fixo por país de destino na moeda padrão da sua loja, sem impostos, uma linha por país no formato CC=PRICE, por exemplo AR=5000. Usado pelo 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 sua loja não for ARS: o preço de 1 ARS na moeda da sua 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 da API e ao verificar os limites de peso. Vazio significa 0,5 kg.
Calculation type: Per order cobra o preço uma única 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 em tempo real da Andreani já vale para o carrinho inteiro e não é multiplicada.
Disponibilidade
Min weight (kg): o peso mínimo do carrinho para a transportadora aparecer. 0 significa sem limite.
Max weight (kg): o peso máximo do carrinho. A transportadora fica oculta se for ultrapassado. Vazio significa 100 kg, 0 significa sem limite.
Minimum subtotal: mostra a transportadora somente quando o subtotal do carrinho (produtos que precisam de envio, após descontos, sem impostos) é pelo menos este valor. Deixe vazio para sempre mostrá-la.
Ignore shipping zones: oferece a Andreani para os países abaixo sem configurar zonas. Ao ativar, as duas transportadoras são vinculadas a todas as zonas, e uma zona criada depois é vinculada imediatamente. Ao desativar, as transportadoras recuperam as zonas anteriores.
Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países. Usado somente quando Ignore shipping zones está ativado.
Frete grátis
Free shipping: ativa o limite para frete grátis.
Free shipping from: o subtotal do carrinho a partir do qual o envio é grátis. Requer que Free shipping esteja ativado.
Segunda opção
Uma segunda transportadora da Andreani com nome, modalidade de entrega e contrato próprios, por exemplo "a domicilio" na transportadora principal e "retiro en sucursal" aqui, para oferecer as duas. Todas as outras configurações são compartilhadas.
Enable second option: liga ou desliga a segunda transportadora. É o mesmo interruptor do status dela em Shipping > Carriers. Padrão: desligado.
Second option name: o nome dessa 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 casa, retirada em filial). Deixe vazio para usar o contrato global.
Seletor de filial na finalização de compra (exibido para door to branch e branch to branch)
Province select width: a largura CSS da lista de províncias, 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 logs/vfd_andr_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros são sempre registrados. Credenciais e tokens nunca são registrados.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativado, desinstalar o módulo exclui todas as suas configurações e as transportadoras. Quando desativado, desinstalar apenas desativa as transportadoras. Os dados de filial salvos nos pedidos são sempre mantidos.
Como funciona na finalização de compra
Na etapa de entrega, o PrestaShop pede ao módulo o preço de cada transportadora da Andreani. Só contam os produtos físicos: produtos virtuais não somam peso e não entram no subtotal. O módulo verifica os países (quando Ignore shipping zones está ativado), o peso do carrinho (os pesos dos produtos são convertidos para kg, e produtos sem peso usam Default product weight (kg)) e o Minimum subtotal.
No modo fixo, o preço é obtido em Country prices. Nos modos em tempo real, o módulo 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 tarifa em tempo real só é solicitada para um CEP argentino válido. O valor em ARS é convertido com o ARS exchange rate quando a moeda da sua loja não é ARS. O preço é calculado na moeda padrão da loja e depois exibido na moeda do carrinho do cliente.
O token de login fica em cache por 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. Erros da API nunca são mostrados ao cliente: a transportadora fica oculta, ou o preço fixo é usado no modo de alternativa. O motivo é registrado no log.
Se Free shipping estiver ativado e o subtotal do carrinho atingir Free shipping from, o preço é 0. O frete grátis se aplica somente onde a transportadora tem um preço: se a API da Andreani não retornar tarifa e não houver preço fixo para usar como alternativa, a transportadora não é mostrada.
Se você editar uma transportadora em Shipping > Carriers depois que ela tiver pedidos, o PrestaShop a salva como uma nova versão da transportadora. O módulo segue a nova versão automaticamente.
O módulo não cria envios da Andreani, não imprime etiquetas e não rastreia encomendas. Use o portal web da Andreani para isso.
Pontos de retirada
Quando uma transportadora com Door to branch ou Branch to branch está selecionada, uma lista de províncias e uma lista de filiais aparecem abaixo dela na etapa de entrega. A província é pré-selecionada a partir do endereço de entrega. A lista de filiais vem da API pública de filiais da Andreani e fica em cache por 12 horas. Filiais que não entregam encomendas não são listadas. Se nenhuma filial estiver disponível, o cliente vê No Andreani branches available right now. Please try again later or choose another shipping method.
A escolha é salva no carrinho assim que o cliente a seleciona. Só é aceita uma filial da lista atual da Andreani. Sem filial, o Continue na etapa de entrega e o botão de pedido na etapa de pagamento não avançam, e o cliente vê Please select an Andreani pickup branch. O servidor verifica a filial de novo 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.
Uma filial escolhida na Andreani antes de o cliente mudar para outra transportadora não pertence ao pedido.
Pedidos
O pedido guarda a modalidade de entrega e, para as modalidades com filial, a filial escolhida.
Admin order page: um bloco Andreani mostra a modalidade e a filial (nome, ID e província). Clique em Edit, escolha outra província e outra filial e clique em Save para alterar. Você verá Branch updated. Só podem ser salvas filiais da lista da Andreani. Se a lista não estiver disponível, a filial não pode ser alterada.
Cliente: a filial é exibida como Andreani pickup branch: na página de confirmação do pedido e na página de detalhes do pedido.
E-mails: no e-mail de confirmação do pedido e no e-mail de novo pedido enviado à loja (módulo Mail alerts), a filial é adicionada ao nome da transportadora. O e-mail da loja também mostra o ID da filial.
Pedidos existentes mantêm seus dados de filial.
Chave de licença
O módulo funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Andreani é o primeiro bloco da página Modules > Module Manager > VibeFox Andreani > Configure, 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-shipping-andreani e o link Manage licenses and domains in your account, que abre sua conta vibefox.net. Somente funcionários com a permissão Configure para o módulo podem alterar a chave. Os textos do bloco seguem o idioma do back office (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 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, o módulo continua funcionando com o último status conhecido.
Uma chave funciona em um domínio: o domínio da loja principal, também em uma configuração multiloja. 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 transportadoras da Andreani não são mostradas aos clientes na finalização de compra e nenhuma tarifa é calculada. A vitrine do PrestaShop não sabe que você está conectado ao back office, então as transportadoras também ficam ocultas para você: você pode configurar o módulo antes de comprar uma chave, mas não pode testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Pedidos existentes não são afetados.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser inserida e depois uma vez por semana. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo 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 e se Enable/Disable está ligado (para a segunda transportadora, também Enable second option). Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo de clientes, ou ative Ignore shipping zones e confira Countries. Verifique se Country prices tem uma linha para o país (para preços fixos ou como alternativa), e confira os limites de peso e o Minimum subtotal. Leia os avisos no topo da página Configure. Além disso, os produtos podem ser limitados a determinadas transportadoras na página do produto.
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 do módulo. Ele mostra o motivo: credenciais ou número de contrato ausentes, falha no login (usuário, senha ou ambiente errados), ainda não há um CEP argentino válido, não há taxa de câmbio ou ocorreu um erro HTTP da Andreani. Com Andreani API, fixed price if the API fails, os clientes continuam recebendo o preço fixo enquanto você resolve 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 regra de imposto em Tax status, é usada a tarifa da Andreani sem IVA e o PrestaShop adiciona o próprio imposto. Com None, é usada a tarifa com IVA e nenhum imposto é adicionado. Verifique se os impostos estão ativados e se a regra de imposto está configurada 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.
As tarifas parecem desatualizadas depois de uma mudança: clique em Save na página do módulo. Isso limpa o token, a lista de filiais e as tarifas em cache.
A página diz que uma transportadora da Andreani não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Andreani e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. O token, a lista de filiais e as tarifas em cache também são sempre removidos. Se Remove data on uninstall estiver ativado, as transportadoras são excluídas (os pedidos mantêm o histórico), e as configurações, o log e as escolhas de filial dos carrinhos sem pedido são removidos. Se estiver desativado, as transportadoras são apenas desativadas e todas as configurações são mantidas. Instalar o módulo novamente, ou um Reset do módulo, devolve às duas transportadoras o status anterior. Os dados de filial salvos nos pedidos nunca são excluídos.
Andreani é uma marca comercial de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Andreani.