VibeFox Estafeta for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior com a extensão cURL. O módulo não é instalado em versões mais antigas do PHP nem sem o cURL.

Conta da 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, ative a Estafeta, configure lá o seu endereço de coleta e copie a chave de API do seu painel da DrEnvio. É a mesma chave usada pelo módulo oficial da DrEnvio. Se você usa 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 do VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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 envio terminar, clique em Configure ou, depois, encontre VibeFox Estafeta na lista de módulos e clique em Configure.

3. Informe a sua chave de licença do 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. Informe a DrEnvio API key e, opcionalmente, o Origin postcode. Se a moeda padrão da sua loja não for o MXN, informe o MXN exchange rate. Defina um preço por país para MX ou uma Fallback cost se a transportadora deve continuar visível quando a DrEnvio não tiver tarifa. Clique em Save.

Na instalação, o módulo cria a transportadora Estafeta com o texto de prazo de entrega Estafeta courier (Mexico). A transportadora é atribuída a todas as zonas 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 Estafeta > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa o cache das tarifas da DrEnvio.

No topo da página, o módulo exibe avisos: falta a chave de API da DrEnvio; a moeda padrão não é o MXN e não há taxa de câmbio; não há preço por país para MX nem custo de reserva (nesse caso a transportadora fica oculta quando não há tarifa em tempo real, ou nunca aparece sem chave de API); ou há uma unidade de peso da loja que o módulo não reconhece (os pesos dos produtos são então tratados como kg; defina a unidade em International > Localization, Local units). Os campos numéricos aceitam ponto ou vírgula como separador decimal. Um valor que não é um número válido é apagado e informado ao salvar; as demais configurações são salvas normalmente.

Geral

Zonas, grupos de clientes e limites de tamanho da transportadora são definidos em Shipping > Carriers. Essas configurações valem para todas as zonas.

Enable/Disable: liga ou desliga o envio pela Estafeta. É a mesma chave do status da transportadora em Shipping > Carriers.

Name: o nome da transportadora exibido ao cliente na finalização de compra. Padrão: Estafeta. Obrigatório. Um nome inválido é informado e o nome anterior é mantido.

Tax: a regra de imposto da transportadora, ou No tax. A loja soma esse imposto ao custo do envio. Se os preços da DrEnvio incluem IVA depende da sua conta na DrEnvio. Se já incluírem, escolha No tax.

Tarifas em tempo real (API da DrEnvio)

É oferecido o serviço da Estafeta mais barato para o endereço. Sem chave, são usados os preços da seção seguinte.

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 valor novo somente se quiser alterá-la.

Remove the saved API key: aparece apenas enquanto há uma chave salva. Defina como Yes e salve para excluir a chave. Então só são usados os Country prices e a 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 código postal de origem.

Origin postcode: o código postal 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 código postal que não tenha 5 dígitos é apagado e informado ao salvar.

MXN exchange rate: a DrEnvio cota em pesos mexicanos. Só é necessário se a moeda padrão da sua loja não for o 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.

Preços sem tarifa em tempo real

Usados quando não há chave de API ou quando a DrEnvio não retorna tarifa da Estafeta (API indisponível, código postal desconhecido, código postal ainda não informado). Os preços são na moeda padrão da loja, sem impostos.

Country prices: um país de destino por linha, no formato CC:PRICE, por exemplo MX:150. Use ponto ou vírgula como separador decimal, sem separador de milhares. 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 a transportadora; 0 significa frete grátis.

Calculation type: Per order cobra o preço uma vez. Per item (price x number of items) multiplica pelo número de itens do carrinho. Vale para os Country prices e para a Fallback cost. Uma tarifa em tempo real da DrEnvio é sempre o preço do pacote inteiro.

Condições

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

Minimum subtotal: exibe a transportadora somente quando o subtotal do carrinho (após descontos, antes dos impostos) é pelo menos este valor. Deixe vazio para exibi-la sempre.

Min weight: o peso mínimo do carrinho, em kg, para a transportadora aparecer. 0 significa sem limite.

Max weight: o peso máximo do carrinho, em kg. A transportadora fica oculta 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 da unidade de peso da sua loja para kg.

Disponibilidade sem zonas de envio

Ignore shipping zones: oferece a transportadora para os países indicados sem configurar zonas para ela. Enquanto estiver ativo, a transportadora recebe todas as zonas, inclusive as que você criar depois. Desativá-lo devolve à transportadora as suas próprias zonas.

Countries: os países de destino para esse modo, escolhidos entre os países ativos da sua loja. Deixe vazio para todos os países. É usado somente quando Ignore shipping zones está ativo.

Avançado

Debug log: grava as solicitações à API e os cálculos de tarifas em logs/vfd_est_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros da API são sempre registrados. A chave de API e os endereços dos clientes nunca são registrados. Desative o log quando terminar.

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

Remove data on uninstall: se ativado, ao desinstalar o módulo são apagadas todas as configurações do módulo, a transportadora, os serviços da Estafeta salvos dos pedidos e o log. Se desativado, tudo é mantido para uma reinstalação.

Como funciona na finalização de compra

Na etapa de envio, o PrestaShop pede ao módulo o preço da Estafeta. Só produtos físicos contam: produtos virtuais não somam peso e não entram no subtotal. O módulo verifica primeiro as condições: a lista Countries (quando Ignore shipping zones está ativo), 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, o módulo envia à DrEnvio o país e o código postal de destino, o peso do carrinho, o número de itens e o subtotal em MXN, além do código postal de origem, se você tiver definido um. Os códigos postais mexicanos devem ter 5 dígitos; até que o cliente informe um endereço de entrega com um código assim, nenhuma solicitação é feita. A DrEnvio devolve cotações de todas as transportadoras da sua conta. O módulo usa somente as cotações da Estafeta, ignora preços zero, escolhe o mais barato e o converte para a moeda padrão da loja. O preço é então exibido na moeda do carrinho do cliente.

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

Se você editar a transportadora em Shipping > Carriers depois que ela já 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 calcula somente tarifas. Ele não cria envios, não imprime etiquetas (guías) nem rastreia pacotes; 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 as taxas de câmbio não são atualizadas automaticamente.

Pedidos

Quando um pedido com a transportadora Estafeta é feito, o módulo guarda a tarifa calculada para o carrinho. Recálculos posteriores, por exemplo na página do pedido no back office, não a alteram.

A página de pedidos em Orders > Orders mostra um bloco 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.

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

Chave de licença

O módulo funciona com uma chave de licença do VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Estafeta é o primeiro bloco de Modules > Module Manager > VibeFox Estafeta > Configure, 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 deles estão a linha Product: presta-shipping-estafeta e o link Manage licenses and domains in your account, que abre a sua conta do 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 único 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 do vibefox.net.

Sem uma chave ativa, a transportadora Estafeta não é exibida 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 a transportadora também fica oculta para você: é possível configurar o módulo antes de comprar uma chave, mas não testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de 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 informada, 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 Estafeta não aparece na finalização de compra: verifique se a licença está ativa e se Enable/Disable está ligado. Em Shipping > Carriers, confira se a transportadora cobre a zona do país do cliente e o grupo do cliente (ou se Ignore shipping zones está ativo e o país é permitido). Verifique os avisos no topo da página do módulo, os limites de peso e o Minimum subtotal. Sem chave de API, ou quando a DrEnvio não tem tarifa da Estafeta, a transportadora precisa de um preço por país para o destino ou de um custo de reserva. Os produtos também podem ser limitados a certas 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: não há chave de API; não há taxa de câmbio para uma loja cuja moeda padrão não é o MXN; o código postal está ausente ou é inválido; a chave de API foi rejeitada (HTTP 401 ou 403 da DrEnvio, verifique a chave de API); não há tarifa da Estafeta para a rota (o log lista as transportadoras que a DrEnvio retornou); ou há uma tarifa em moeda diferente do MXN.

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

As tarifas parecem desatualizadas após uma mudança: clique em Save na página do módulo. Isso limpa o cache das tarifas da DrEnvio.

A página diz que a transportadora Estafeta não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para recriá-la. O mesmo vale para a mensagem The settings were saved, but the carrier could not be updated.

A página do pedido não tem o bloco Estafeta: o bloco só aparece nos pedidos feitos com a transportadora Estafeta enquanto o módulo estava instalado. Desinstalar com Remove data on uninstall ativo exclui os serviços salvos.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Estafeta e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. O cache das tarifas é sempre removido. Se Remove data on uninstall estiver ativo, a transportadora é excluída (os pedidos mantêm o histórico), e as configurações, os serviços da Estafeta salvos dos pedidos e o log são removidos. Se estiver desativado, a transportadora apenas é desabilitada, e as configurações e os serviços salvos dos pedidos são mantidos. Ao instalar o módulo novamente, a transportadora recupera o status que tinha antes da desinstalação.

Estafeta e DrEnvio são marcas comerciais de seus respectivos titulares. Este módulo não é afiliado nem endossado pela Estafeta ou pela DrEnvio.