VibeFox Servientrega for WooCommerce — Ajuda
Requisitos
WordPress: 5.8 ou superior.
WooCommerce: 5.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.
PHP: 8.0 ou superior.
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, normalmente começa com SER). São as suas credenciais do SISCLINET, emitidas pelo seu consultor comercial da Servientrega. Se você usar apenas preços fixos, não precisa de uma conta Servientrega.
Acesso ao servidor (apenas para tarifas em tempo real): seu servidor precisa conseguir acessar 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 único domínio.
Instalação
1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta vfd_servientrega para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Servientrega, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Para as tarifas em tempo real, informe usuário, senha e 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 (veja Configuração).
6. Opcionalmente, adicione preços fixos por país e peso e um custo alternativo.
7. Adicione VibeFox Servientrega a uma zona de entrega em WooCommerce > Settings > Shipping > Shipping zones, ou ative Ignore shipping zones e escolha os países.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Shipping > VibeFox Servientrega. Elas valem para todas as zonas de entrega. Ao adicionar o método a uma zona, a janela da zona tem apenas um campo:
Title (zone): o nome que os clientes veem nesta zona. Deixe vazio para usar o Method title global.
Sempre que você salvar as configurações, as cotações da Servientrega em cache e o token de login são apagados. Se as tarifas em tempo real não puderem funcionar com as configurações salvas, um aviso acima das configurações informa o motivo: usuário, senha ou código de faturamento ausente, taxa de conversão ausente ou código DANE de origem ausente.
Geral
Enable/Disable: ativa ou desativa o método em todas as zonas de uma vez.
Method title: o nome do método de entrega exibido no carrinho e na finalização de compra. Uma zona pode substituí-lo. Padrão: Servientrega.
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.
Password: sua senha Servientrega / SISCLINET, como você a digita. O plugin a envia criptografada pelo serviço web da Servientrega antes do login, como faz o cliente oficial da Servientrega.
Billing code: o código de faturamento (código de facturación) da sua conta Servientrega, exibido no SISCLINET. Normalmente 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 consultadas 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 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 loja for COP. Se a 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 plugin não busca taxas de câmbio. Tanto o ponto quanto a vírgula são aceitos como separador decimal.
Enviar 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 de município de 5 dígitos também é aceito. Se estiver vazio e o endereço da loja em WooCommerce > Settings > General for 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 da sua loja. Clique em + Add country para adicionar uma linha e no X 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 substituem Price para aquele peso quando forem maiores que 0. A linha * Default vale para todos os países sem linha própria.
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.
Condições
Minimum weight (kg): oculta o método quando o carrinho pesa menos. 0 significa sem limite.
Maximum weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 50. 0 significa sem limite.
Minimum order amount: exibe o método somente quando o subtotal do carrinho (após descontos, antes dos impostos) atinge este valor. Deixe vazio para exibi-lo sempre.
Free shipping from: a entrega é grátis quando o subtotal do carrinho (após descontos, antes dos impostos) atinge este valor. Vale apenas onde o método tem preço: um preço da tabela ou o custo alternativo (nesse caso nenhuma requisição é enviada à Servientrega), ou uma tarifa em tempo real. Deixe vazio para nunca oferecer frete grátis.
Excluded shipping classes: oculta o método quando o carrinho contém um produto de qualquer uma dessas classes de entrega do WooCommerce.
Tax status: Taxable adiciona o imposto do WooCommerce ao valor do frete, None não adiciona. As cotações da Servientrega (ValorTotal) já incluem as taxas da transportadora. Escolha None se não quiser adicionar imposto por cima.
Disponibilidade sem zonas de entrega
Ignore shipping zones: oferece a Servientrega para os países abaixo, mesmo que o método não esteja adicionado a nenhuma zona de entrega.
Countries: os países de destino para esse modo. Deixe vazio para usar todos os países para os quais você entrega. Este campo só é usado quando Ignore shipping zones está ativado.
Avançado
Debug log: registra os cálculos de tarifas e os erros da API no log do WooCommerce: WooCommerce > Status > Logs, origem vfd_servientrega. Credenciais, tokens e endereços dos clientes não são registrados. Desative o log quando terminar.
Remove data on uninstall: quando ativado, excluir o plugin remove todas as configurações da Servientrega, os métodos de zona e as cotações em cache. Desativar o plugin nunca apaga nada.
Como funciona na finalização de compra
Quando o cliente informa um endereço de entrega, o WooCommerce pede uma tarifa ao plugin. O plugin verifica primeiro as condições: país de entrega, peso do carrinho, valor mínimo do pedido e classes de entrega excluídas. Depois procura um preço: a tarifa em tempo real da Servientrega, em seguida a tabela de preços e, por fim, o custo alternativo. Se não houver preço, o método fica oculto. Se o frete grátis se aplicar, o método é exibido com preço 0.
Para um destino na Colômbia com credenciais configuradas, o plugin 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 combina 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.
Em seguida, o plugin envia à Servientrega um único pacote por pedido: o peso total convertido da unidade da sua loja 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 subtotal do carrinho convertido para COP, com mínimo de 6.000 COP. A Servientrega devolve o total em COP, e o plugin o converte para a moeda da sua loja.
O token de login é mantido até expirar, no máximo por 4 dias. Um token rejeitado é 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 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.
Se não houver tarifa em tempo real, o preço vem da tabela de preços fixos e depois do Fallback cost. Se nenhum dos dois se aplicar, o método fica oculto. O cliente nunca vê um erro da API. O motivo é gravado no log de depuração.
O método funciona na finalização de compra clássica e nos blocos Carrinho e Finalização de compra. É compatível com o WooCommerce High-Performance Order Storage (HPOS). Traduções para o espanhol (Colômbia, Espanha) estão incluídas.
O plugin calcula apenas tarifas. Não gera guias (guías), etiquetas ou adesivos, não solicita coletas, não rastreia nem cancela envios 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. Não há cotação para pagamento na entrega (logística de recaudo). As cotações em tempo real valem somente para envios nacionais dentro da Colômbia. Equador, Peru, Panamá e envios internacionais usam os preços fixos.
Chave de licença
O plugin funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Shipping > VibeFox Servientrega. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa e o seu domínio. Use Check now para verificar o status novamente, Change key para inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta no vibefox.net.
Uma chave funciona em um único domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta do vibefox.net.
Sem uma chave ativa, a Servientrega não é exibida aos clientes na finalização de compra. Os gerentes da loja conectados ainda a veem, marcada como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática em segundo plano.
Solução de problemas
A Servientrega não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o método foi adicionado à zona do país do cliente (ou se Ignore shipping zones está ativado e o país está permitido). Confira os limites de peso, Minimum order amount e Excluded shipping classes. Sem tarifa em tempo real, verifique se o país ou * Default tem preço, ou se Fallback cost está definido.
As tarifas em tempo real não aparecem: ative o Debug log, recarregue a finalização de compra e abra WooCommerce > Status > Logs, origem vfd_servientrega. Motivos comuns: taxa de conversão ausente (a moeda da loja não é COP), código DANE de origem ausente, departamento ou cidade do cliente ainda não informados ou não reconhecidos como 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. Após um login malsucedido, o plugin aguarda 10 minutos antes da próxima tentativa. Salve as configurações para tentar novamente imediatamente.
A cidade do cliente não é reconhecida: o departamento e a cidade são comparados com a tabela DANE integrada. Para grafias incomuns, o cliente pode digitar o código DANE de 8 dígitos no lugar do CEP. Desenvolvedores podem associá-lo com o filtro vfd_svtg_dane_code.
As tarifas parecem desatualizadas após uma alteração: salve a página de configurações. Isso limpa as cotações da Servientrega em cache e o token.
Para desenvolvedores: os filtros vfd_svtg_quote_request e vfd_svtg_default_dimensions ajustam a requisição de cotação e as dimensões de produtos que não as têm. vfd_svtg_api_base e vfd_svtg_soap_url alteram os endpoints, por exemplo se a Servientrega fornecer outro servidor.
O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta do vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave para o novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.
Desinstalação
Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status da licença deste plugin são sempre removidos. Configurações, métodos de zona, cotações em cache e tokens são removidos somente se Remove data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas linhas de frete.
A Servientrega é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Servientrega.