VibeFox Servientrega for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões anteriores do PHP.
Conta Servientrega (apenas para tarifas em tempo real): as tarifas em tempo real usam o Cotizador Corporativo da Servientrega (API de cotação corporativa). Você precisa de uma conta corporativa (de crédito) da Servientrega com acesso a ele. São necessários três dados: o usuário, a senha e o código de faturamento (código de facturación, geralmente começa com SER). São as suas credenciais do SISCLINET, fornecidas pelo seu consultor comercial da Servientrega. Se você usar apenas preços fixos, não precisa de uma conta Servientrega.
Acesso do servidor (apenas para tarifas em tempo real): o seu servidor deve conseguir alcançar web.servientrega.com via HTTP na porta 8058 (API de cotação) e na porta 8081 (serviço web de criptografia de senha).
Chave de licença VibeFox: 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 envio terminar, clique em Configure ou encontre depois o VibeFox Servientrega na lista de módulos e clique em Configure.
3. Insira 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. Para tarifas em tempo real, informe o usuário, a senha e o código de faturamento, escolha o produto Servientrega, informe o código DANE de origem e, se a moeda da sua loja não for COP, a taxa de conversão de moeda. Clique em Add Colombian departments se a sua loja ainda não tiver (veja Configuração).
5. Opcionalmente, adicione preços fixos por país e peso e um custo alternativo, depois clique em Save.
Na instalação, o módulo cria a transportadora Servientrega com o texto de prazo de entrega Servientrega courier delivery. 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, logo 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 Servientrega > Configure. Elas valem para todas as zonas. Cada seção tem seu próprio botão Save, que salva a página inteira. Cada salvamento limpa as cotações da Servientrega em cache e o token de login.
Se as tarifas em tempo real não puderem funcionar com as configurações salvas, um aviso acima do formulário informa o motivo: usuário, senha ou código de faturamento ausente, taxa de conversão ausente ou código DANE de origem ausente. Um aviso também aparece se a unidade de peso ou de dimensões da sua loja (International > Localization, Local units) não for reconhecida pelo módulo; nesse caso, os pesos são lidos em kg e as dimensões em cm. Ao salvar, um valor que não é número, um número negativo, uma taxa de conversão de 0, um peso mínimo acima do peso máximo, um preço errado na tabela ou um título de método com mais de 64 caracteres é recusado com um erro, e nada é salvo.
Geral
Enable Servientrega: liga ou desliga a transportadora em todas as zonas de uma vez. É a mesma chave do status da transportadora em Shipping > Carriers.
Method title: o nome da transportadora mostrado ao cliente no carrinho e na finalização da compra. Padrão: Servientrega. Obrigatório, no máximo 64 caracteres.
API Servientrega (tarifas em tempo real para a Colômbia) (opcional; sem credenciais, apenas os preços fixos são usados)
User (login): seu usuário Servientrega / SISCLINET. Limpar esse campo também remove a senha salva.
Password: sua senha Servientrega / SISCLINET, como você a digita. O módulo a faz criptografar pelo serviço web da Servientrega antes do login. Depois de salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo apenas para alterá-la.
Billing code: o código de facturación da sua conta Servientrega, mostrado no SISCLINET. Geralmente começa com SER.
Os três campos são necessários para as tarifas em tempo real. As tarifas em tempo real são solicitadas apenas para destinos na Colômbia. Os demais países usam os preços fixos.
Servientrega product: o serviço do seu contrato com a Servientrega que é cotado.
O peso tarifado é o maior entre o peso real e o peso volumétrico.
Currency conversion rate: a Servientrega cota em COP. Se a moeda padrão da sua loja não for COP, informe o valor de 1 COP na moeda da sua loja, por exemplo 0.00023. O valor declarado do pacote é convertido para COP da mesma forma. Deixe vazio se a moeda da sua loja for COP. Se a sua loja usar outra moeda e este campo estiver vazio, as tarifas em tempo real não são usadas e valem os preços fixos. O módulo não busca cotações de câmbio. Tanto o ponto quanto a vírgula são aceitos como separador decimal.
Colombian departments: o departamento ajuda a distinguir municípios com o mesmo nome. O PrestaShop não tem departamentos colombianos por padrão; sem eles, só são reconhecidos nomes de cidades que são únicos na Colômbia. Clique em Add Colombian departments para adicionar os 33 departamentos como estados da Colômbia (códigos ISO ANT, DC…), ative Contains states para a Colômbia e adicione o campo de departamento ao formulário de endereço colombiano. Departamentos que já existem não são adicionados duas vezes. Quando tudo estiver pronto, o campo mostra quantos departamentos os endereços colombianos têm.
Envio de (usado para as tarifas em tempo real)
Origin city (DANE code): o código DANE de 8 dígitos do município de onde você envia, por exemplo 11001000 Bogotá, 05001000 Medellín, 76001000 Cali ou 08001000 Barranquilla. Um código municipal de 5 dígitos também é aceito. Se estiver vazio e o endereço da sua loja em Shop Parameters > Contact > Stores estiver na Colômbia, usa-se o município do endereço da loja.
Preços fixos (usados quando não há tarifa em tempo real: sem credenciais, destino fora da Colômbia, município desconhecido, taxa de conversão ausente, erro da API ou falta de cobertura para a rota)
Price per country: uma tabela de países e preços na moeda padrão da sua loja, sem imposto. Clique em Add country para adicionar uma linha e no ícone de lixeira para remover uma. Price vale para qualquer peso. As colunas de peso XS ≤1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg e XL >5 kg o substituem para aquele peso quando são maiores que 0. A linha * Default vale para todos os países sem linha própria. Uma linha sem nenhum preço não é salva.
Fallback cost: usado quando não há tarifa em tempo real e nenhuma linha da tabela corresponde. Deixe vazio para ocultar a transportadora nesse caso.
Fixed price applies: como os preços fixos são cobrados.
As tarifas Servientrega em tempo real são sempre por remessa.
Condições
Minimum weight: oculta a transportadora quando o carrinho pesa menos, em kg. 0 significa sem limite.
Maximum weight: oculta a transportadora quando o carrinho pesa mais, em kg. Padrão: 50. 0 significa sem limite.
Minimum order amount: mostra a transportadora somente quando o subtotal do carrinho (após descontos, antes dos impostos) atinge este valor. Deixe vazio para mostrá-la sempre.
Free shipping from: a entrega é grátis quando o subtotal do carrinho (após descontos, antes dos impostos) atinge este valor, e nenhuma requisição é enviada à Servientrega. Vale para todos os destinos onde a transportadora é oferecida, inclusive países sem linha na tabela de preços. Deixe vazio para nunca oferecer frete grátis.
Tax: a regra de imposto da transportadora, ou No tax. As cotações da Servientrega (ValorTotal) já incluem as taxas da transportadora. Escolha No tax se não quiser adicionar imposto por cima.
Disponibilidade sem zonas de entrega
Normalmente a transportadora é oferecida nas zonas atribuídas a ela em Shipping > Carriers.
Ignore shipping zones: oferece a Servientrega para os países abaixo, mesmo que a transportadora não esteja atribuída à zona deles. Nesse caso, a transportadora é atribuída a todas as zonas, inclusive às zonas que você criar depois. Desligar a opção devolve à transportadora as zonas anteriores.
Countries: os países de destino para esse modo. Deixe vazio para usar todos os países ativos da sua loja. Este campo só é usado quando Ignore shipping zones está ativado.
Avançado
Debug log: grava os cálculos de tarifas e os erros da API em logs/vfd_svtg_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Credenciais, tokens e endereços de clientes não são registrados. Com o log desligado, nada é gravado, nem mesmo os erros da API. Desligue o log quando terminar.
Log: mostra o tamanho e as últimas entradas do log de depuração. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativado, desinstalar o módulo apaga todas as configurações da Servientrega, a transportadora, as cotações em cache e os logs. Pedidos anteriores mantêm a sua transportadora. Quando desativado, tudo é mantido para uma reinstalação.
Como funciona na finalização da compra
Na etapa de entrega, o PrestaShop pede ao módulo o preço da Servientrega. Só contam os produtos físicos: produtos virtuais não somam peso e não entram no valor do pedido. O módulo verifica primeiro as condições: o país de entrega (com Ignore shipping zones), o peso do carrinho e o valor mínimo do pedido. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada à Servientrega. Em seguida, busca um preço: a tarifa em tempo real da Servientrega, depois a tabela de preços e, por fim, o custo alternativo. Se não houver preço, a transportadora fica oculta para aquele carrinho.
Para um destino na Colômbia com credenciais preenchidas, o módulo encontra o código DANE do município do cliente. Ele usa um código DANE digitado no lugar do CEP ou no campo cidade, ou compara o departamento e a cidade com a tabela integrada de cerca de 1.130 municípios. Acentos e "D.C." são ignorados. Um nome de cidade que existe em apenas um departamento é encontrado mesmo sem o departamento.
Depois, o módulo envia à Servientrega uma peça por pedido: o peso total convertido da unidade da sua loja para kg, e uma caixa com o comprimento e a largura do item maior e o volume total de todos os itens, convertido para cm. Produtos sem dimensões contam como 10 × 10 × 10 cm. O valor declarado é o subtotal do carrinho convertido para COP, com mínimo de 6.000 COP. A Servientrega devolve o total em COP. O módulo converte para a moeda padrão da sua loja, e o cliente vê o valor na moeda do carrinho.
O token de login é mantido até expirar, no máximo 4 dias. Um token recusado é renovado automaticamente uma vez. Cada cotação fica em cache por 1 hora por rota e pacote, para que o mesmo carrinho não dispare uma nova requisição. Uma requisição com falha (criptografia, login ou cotação) fica em cache por 10 minutos, para que a finalização da compra não espere pela Servientrega a cada atualização. O tempo limite é de 10 segundos por requisição.
O cliente nunca vê um erro da API. O motivo é gravado no log de depuração quando ele está ativado.
Se você editar a transportadora em Shipping > Carriers depois que ela tiver pedidos, o PrestaShop a salva como uma nova versão da transportadora. O módulo acompanha a nova versão automaticamente.
O módulo apenas calcula tarifas. Ele não gera guias (guías), etiquetas ou adesivos, não solicita coletas, não rastreia nem cancela remessas e não permite que os clientes escolham uma agência da Servientrega (Centro de Soluciones). Crie a guia no SISCLINET ou no seu portal da Servientrega. O pagamento na entrega (logística de recaudo) não é cotado. As cotações em tempo real valem apenas para envios nacionais dentro da Colômbia. Os demais países usam os preços fixos.
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 Servientrega é o primeiro bloco em Modules > Module Manager > VibeFox Servientrega > Configure, 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 aparecem a linha Product: presta-shipping-servientrega e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente funcionários com a permissão Configure do 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, a transportadora Servientrega não é mostrada aos clientes na finalização da compra, e nenhuma tarifa é solicitada ou calculada. A vitrine do PrestaShop não sabe que você fez login no back office, então a transportadora também fica oculta para você: você pode configurar o módulo antes de comprar uma chave, mas não testá-lo na finalização da 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 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. Não é necessário nenhum cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A Servientrega não aparece na finalização da compra: confirme que a licença está ativa e que Enable Servientrega está ligado. Em Shipping > Carriers, confirme que a transportadora cobre a zona do país do cliente e o grupo do cliente, ou ative Ignore shipping zones e verifique Countries. Confira os limites de peso e o Minimum order amount. Sem tarifa em tempo real, confirme que o país ou a linha * Default tem preço, ou que Fallback cost está definido. 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 da compra e veja o campo Log na página do módulo. Motivos comuns: taxa de conversão ausente (a moeda da loja não é COP), nenhum código DANE de origem, o departamento ou a cidade do cliente ainda não foram informados ou não são um município conhecido, credenciais incorretas ou falta de cobertura para a rota. Os preços fixos cobrem esses casos se você os tiver definido.
O login falha: confira o usuário, a senha e o código de faturamento com o seu consultor comercial da Servientrega. Depois de um login com falha, o módulo espera 10 minutos antes da próxima tentativa. Salve as configurações para tentar novamente imediatamente.
A cidade do cliente não é reconhecida: clique em Add Colombian departments para que os clientes possam escolher o departamento. Para grafias incomuns, o cliente pode digitar o código DANE de 8 dígitos no lugar do CEP.
As tarifas parecem desatualizadas após uma mudança: clique em Save na página do módulo. Isso limpa as cotações da Servientrega em cache e o token.
A página diz que a transportadora Servientrega não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.
Para desenvolvedores: os hooks actionVfdSvtgDaneCode e actionVfdSvtgQuoteRequest permitem alterar o código DANE de destino e a requisição de cotação.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Servientrega e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. As cotações em cache, os tokens e a senha criptografada são sempre removidos. Se Remove data on uninstall estiver ativado, a transportadora é excluída (os pedidos mantêm o histórico) e as configurações e o log são removidos. Se estiver desativado, a transportadora apenas é desativada e todas as configurações são mantidas. Reinstalar o módulo, ou usar Reset, devolve à transportadora o status que ela tinha antes.
A Servientrega é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela Servientrega.