VibeFox Servientrega for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e posteriores (testado na versão 4.1.0.3).
PHP: 8.0 ou superior.
Conta da Servientrega (somente 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 SISCLINET, emitidas pelo seu consultor comercial da Servientrega. Se você usa apenas preços fixos, não precisa de conta na Servientrega.
Acesso ao servidor (somente para tarifas em tempo real): o seu servidor precisa alcançar web.servientrega.com por HTTP na porta 8058 (API de cotação) e na porta 8081 (serviço web de criptografia de senhas).
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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_servientrega-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_servientrega.ocmod.zip. Instale apenas o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.
OpenCart 3
1. No admin, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_servientrega-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ê também pode copiar o conteúdo da pasta upload do pacote para a pasta raiz da sua loja.
2. Vá em Extensions > Extensions, escolha o tipo de extensão Shipping, encontre VibeFox Servientrega 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 em License key, no bloco de licença no topo da página Edit, e clique em Activate (veja Chave de licença).
5. Para as tarifas em tempo real, informe o usuário, a senha e o código de faturamento, escolha o produto da Servientrega, informe o código DANE da origem e, se a moeda da sua loja não for o COP, a taxa de conversão de moeda.
6. Opcionalmente, adicione preços fixos por país e peso e um custo de contingência, ative Enable Servientrega e clique em Save.
OpenCart 4
1. No admin, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_servientrega.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão pelo 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, escolha o tipo de extensão Shipping, encontre VibeFox Servientrega, 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 a 6 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é você ativar Enable Servientrega e salvar. Se você reinstalar a extensão depois de desinstalá-la, as configurações da Servientrega que você manteve serão usadas novamente.
Configuração
Todas as configurações ficam na página da extensão: Extensions > Extensions > Shipping > VibeFox Servientrega > Edit. As seções são listadas à esquerda. Elas valem para todas as zonas geográficas. Um botão Save no final salva a página inteira sem recarregá-la. Cada salvamento limpa as cotações da Servientrega em cache e o token de login. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações.
Se as tarifas em tempo real não puderem funcionar com as configurações salvas, um aviso acima das configurações informa o motivo: falta o usuário, a senha ou o código de faturamento, falta a taxa de conversão ou falta o código DANE da origem. Um aviso também aparece se a loja não tiver uma classe de peso em kg ou uma classe de comprimento em cm e a unidade padrão dela não for conhecida pela extensão; nesse caso, os pesos são lidos como kg e as dimensões como 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 máximo, um preço errado na tabela, um título de método vazio, com mais de 64 caracteres ou contendo < > ; = # { }, ou uma ordem de classificação que não é um número inteiro é recusado com erro, e nada é salvo.
Geral
Enable Servientrega: mostra ou oculta a Servientrega na finalização de compra. Padrão: desativado.
Method title: o nome do método de envio mostrado ao cliente no carrinho e na finalização de compra. Padrão: Servientrega. Obrigatório, no máximo 64 caracteres.
Sort order: a posição da Servientrega entre os métodos de envio na finalização de compra. Um número inteiro.
API Servientrega (tarifas em tempo real para a Colômbia) (opcional; sem credenciais, somente os preços fixos são usados)
User (login): o seu usuário Servientrega / SISCLINET. Limpá-lo também remove a senha salva.
Password: a sua senha Servientrega / SISCLINET, como você a digita. A extensão a deixa criptografada 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 novo valor somente para alterá-la.
Billing code: o código de faturamento (código de facturación) da sua conta Servientrega, como aparece 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 somente para destinos na Colômbia. Os demais países usam os preços fixos.
Servientrega product: o serviço do seu acordo com a Servientrega que é cotado.
O peso faturado é 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 o 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. Se a moeda da sua loja for o COP, o campo indica que não é necessária conversão: deixe-o vazio. Se a sua loja usa outra moeda e este campo estiver vazio, as tarifas em tempo real não são usadas e valem os preços fixos. A extensão não busca taxas de câmbio. Tanto o ponto quanto a vírgula são aceitos como separador decimal.
Ship from (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 de município de 5 dígitos também é aceito. O endereço da loja no OpenCart é texto livre, então a origem nunca é obtida dele: sem este campo não há tarifas em tempo real.
Fixed prices (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 sem cobertura para a rota)
Price per country: uma tabela de países e preços na moeda padrão da sua loja, sem impostos. Clique em Add country para adicionar uma linha e no botão de remover para excluir uma. Price vale para qualquer peso. As colunas de peso XS (até 1 kg), S (1–2 kg), M (2–3 kg), L (3–5 kg) e XL (acima de 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 nova linha começa como * Default. 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 o método nesse caso.
Fixed price applies: como os preços fixos são cobrados.
As tarifas em tempo real da Servientrega são sempre por envio.
Conditions
Minimum weight (kg): oculta o método abaixo deste peso do carrinho. 0 significa sem limite (padrão).
Maximum weight (kg): oculta o método acima deste peso do carrinho. Padrão: 50. 0 significa sem limite.
Minimum order amount: mostra o método somente quando o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) atinge este valor. Deixe vazio para mostrá-lo sempre.
Free shipping from: a entrega é gratuita quando esse subtotal atinge este valor, e nenhuma requisição é enviada à Servientrega. Vale para qualquer destino em que o método seja oferecido, inclusive países sem linha na tabela de preços. Deixe vazio para nunca oferecer frete grátis.
Tax class: a classe de imposto do custo de envio, ou No tax (padrão). As cotações da Servientrega (ValorTotal) já incluem as cobranças da transportadora. Escolha No tax se não quiser adicionar imposto por cima.
Geo zone: ofereça a Servientrega 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 é verificada quando Ignore shipping zones está ativado.
Availability without geo zone
Normalmente o método é oferecido na zona geográfica selecionada em Conditions, ou em todas as zonas.
Ignore shipping zones: oferece a Servientrega para os países abaixo, independentemente da zona geográfica.
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.
Advanced
Debug log: grava os cálculos de tarifas e os erros da API em storage/logs/vfd_svtg_debug.log.php. O arquivo não pode ser lido pela web. Credenciais, tokens e endereços de clientes não são registrados. Quando o log está desativado, nada é gravado, inclusive os erros da API. Quando o arquivo chega a 5 MB, ele é movido para vfd_svtg_debug.old.log.php e um novo log é iniciado. Desative 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 a extensão apaga todas as configurações da Servientrega e o log. Quando desativado (padrão), elas são mantidas para uma reinstalação. As cotações em cache são sempre removidas.
Import / Export
Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A senha 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 passam pelas mesmas verificações de um salvamento normal. A senha salva é mantida enquanto o usuário estiver definido.
Como funciona na finalização de compra
Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço da Servientrega. Se houver uma Geo zone definida e o endereço estiver fora dela, a Servientrega não é oferecida (a menos que Ignore shipping zones esteja ativado). Somente produtos com Requires Shipping definido como Yes contam: os demais não somam peso nem entram no valor do pedido. O valor do pedido é o preço desses produtos após o desconto do cupom e antes dos impostos. Vales-presente e pontos de fidelidade não são considerados. A extensão primeiro verifica 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, procura um preço: a tarifa em tempo real da Servientrega, depois a tabela de preços e, por último, o custo de contingência. Se não houver preço, o método fica oculto para aquele carrinho.
Para um destino na Colômbia com credenciais configuradas, a extensão encontra o código DANE do município do cliente. Ela usa um código DANE digitado no campo de CEP ou cidade, ou relaciona o departamento e a cidade com a tabela integrada de cerca de 1.130 municípios. O departamento é a Region / State do endereço: o OpenCart já tem os 33 departamentos colombianos. Acentos e "D.C." são ignorados. Uma cidade que existe em apenas um departamento é encontrada mesmo sem o departamento.
Depois, a extensão envia à Servientrega uma peça por pedido: o peso total convertido da classe de peso do produto para kg, e uma caixa com o comprimento e a largura do maior item 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 valor do pedido convertido para COP, com um mínimo de 6.000 COP. A Servientrega devolve o total em COP. A extensão o converte para a moeda padrão da sua loja e o arredonda para as casas decimais dela. O cliente o vê na moeda dele com o imposto da Tax class selecionada.
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, então o mesmo carrinho não gera 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 de 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.
A extensão calcula apenas tarifas. Ela não cria guias (guías), etiquetas ou adesivos, não solicita coletas, não rastreia nem cancela envios e não permite que o cliente escolha 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 somente para envios nacionais dentro da Colômbia. Ela não acrescenta nada aos pedidos: o pedido mostra o nome do método e o custo do envio como qualquer outro método de envio do OpenCart.
No OpenCart 4, o cliente clica em Choose no bloco de métodos de envio da página de finalização de compra e escolhe a Servientrega na janela Shipping method options, onde o nome do método é exibido com o preço. O método funciona da mesma forma que no OpenCart 3.
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 Servientrega é o primeiro bloco de Extensions > Extensions > Shipping > VibeFox Servientrega > 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-servientrega e o link Manage licenses and domains in your account, que abre a sua conta na vibefox.net. Somente usuários administradores com a permissão de modificação da extensão podem alterar a chave. Os textos do bloco seguem o idioma do admin (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 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 nas configurações do OpenCart. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta da vibefox.net.
Sem uma chave ativa, o método de envio da Servientrega não é mostrado aos clientes na finalização de compra e nenhuma tarifa é solicitada ou calculada. Um usuário administrador conectado ao admin 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 admin, 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 admin. 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 novamente de forma automática ao abrir o Dashboard ou a página Edit do admin: uma vez por dia nos primeiros 14 dias após a chave ser informada e, depois, uma vez por semana. Não é preciso 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 Servientrega não aparece na finalização de compra: verifique se a licença está ativa e se Enable Servientrega está ligado. Confira Geo zone, ou ative Ignore shipping zones e confira Countries. Confira os limites de peso e o Minimum order amount. Sem tarifa em tempo real, verifique se o país ou * Default tem um preço, ou se Fallback cost está definido. Verifique se os produtos têm Requires Shipping definido como Yes.
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 da extensão. Motivos comuns: taxa de conversão ausente (a moeda da loja não é o COP), falta o código DANE da origem, o departamento ou a cidade do cliente ainda não foram informados ou não são um município conhecido, credenciais erradas, nenhuma cobertura para a rota, ou o servidor não consegue alcançar web.servientrega.com nas portas 8058 e 8081. Os preços fixos cobrem esses casos, se você os configurar.
O login falha: confira o usuário, a senha e o código de faturamento com o seu consultor comercial da Servientrega. Após um login com falha, a extensão aguarda 10 minutos antes da próxima tentativa. Salve as configurações para tentar de novo imediatamente.
A cidade do cliente não é reconhecida: o cliente deve escolher o departamento no campo Region / State. Para grafias raras, o cliente pode digitar o código DANE de 8 dígitos como CEP.
As tarifas parecem desatualizadas após uma mudança: clique em Save na página da extensão. Isso limpa as cotações da Servientrega em cache e o token.
A página diz "Warning: You do not have permission to modify VibeFox Servientrega!": o 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_servientrega (OpenCart 3) ou extension/vfd_servientrega/shipping/vfd_servientrega (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: os eventos do OpenCart vfd_servientrega/dane_code e vfd_servientrega/quote_request permitem que outra extensão altere o código DANE de destino e a requisição de cotação.
Desinstalação
Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Servientrega. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable Servientrega, Sort order, Tax class e Geo zone. As cotações em cache, os tokens e a senha criptografada são sempre removidos. Se Remove data on uninstall estiver ativado, as demais configurações e o log também são apagados. Se estiver desativado, são mantidos e usados de novo quando você reinstalar a extensão. 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 Servientrega na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.
Servientrega é uma marca comercial de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela Servientrega.