VibeFox Coordinadora for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e posteriores (testado na 4.1.0.3).

PHP: 8.0 ou superior.

Chave de API da Coordinadora (somente para cotações em tempo real): as cotações em tempo real vêm do Cotizador da Coordinadora pelo serviço WooCommerce da Coordinadora, o mesmo usado pelo plugin oficial da Coordinadora. A Coordinadora emite a chave de API para clientes com acordo comercial ativo. Pergunte ao seu gerente de conta na Coordinadora ou consulte wc.coordinadora.com. Você também precisa do código DANE de 8 dígitos da cidade de onde envia. Sem a chave, o método funciona somente com preços fixos.

Produtos: para uma cotação em tempo real, cada produto no carrinho precisa ter peso e três dimensões (comprimento, largura, altura).

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 README.txt, o pacote do OpenCart 3 vfd_coordinadora-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_coordinadora.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_coordinadora-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ê pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox Coordinadora 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. Digite sua chave de licença VibeFox no campo License key do bloco de licença, no topo da página Edit, e clique em Activate (veja Chave de licença).

5. Informe a chave de API, o código DANE da cidade de origem e, se a moeda padrão da loja não for COP, a taxa de câmbio para COP. Adicione pelo menos um preço fixo para a Colômbia como alternativa (veja Configuração). Ative Enable Coordinadora e clique em Save.

6. Verifique se os seus produtos têm peso e dimensões.

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_coordinadora.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. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox Coordinadora, 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é que você ative Enable Coordinadora e salve. Se você instalar a extensão novamente depois de desinstalá-la, as configurações da Coordinadora que você manteve serão usadas de novo.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Shipping > VibeFox Coordinadora > Edit. As configurações valem para todas as zonas geográficas; você pode limitar o método a uma zona geográfica e a países em Conditions. As seções aparecem à esquerda. Um único botão Save no final salva a página inteira sem recarregá-la. Depois de salvar, você verá Settings saved. Cached Coordinadora rates were cleared. Os números podem ser digitados com ponto ou vírgula (9,99 = 9.99). Somente usuários administradores com permissão de modificação para esta extensão podem salvar as configurações.

Nada é salvo e a página lista os erros se Name estiver vazio ou tiver mais de 64 caracteres, se um número ou um preço da tabela for inválido ou negativo, se COP per 1 unit of store currency for 0, se Min weight (kg) for maior que Max weight (kg) ou se Sort order não for um número inteiro.

A página mostra avisos acima das configurações quando as cotações em tempo real não podem funcionar ou o método ficaria oculto: Origin city (DANE code) está vazio ou é inválido; falta COP per 1 unit of store currency se a moeda padrão não for COP; não há preço fixo para a Colômbia (nem para *); não há chave de API nem preço fixo para a Colômbia, então o método nunca aparece para endereços colombianos. Um aviso também aparece quando a loja não tem uma classe de peso em kg nem uma classe de comprimento em cm e a unidade padrão dela não é reconhecida pela extensão; os pesos dos produtos são então lidos como kg e as dimensões como cm (use kg, g, lb ou oz e cm, mm, m ou in em System > Localisation). Os avisos são atualizados após cada salvamento.

Geral

Enable Coordinadora: mostra ou oculta a Coordinadora na finalização de compra. Padrão: desativado.

Name: o nome do método de envio exibido ao cliente na finalização de compra. Padrão: Coordinadora. Obrigatório, até 64 caracteres.

Sort order: a posição da Coordinadora entre os métodos de envio na finalização de compra. Um número inteiro.

Cotações em tempo real da Coordinadora

As cotações em tempo real são solicitadas para destinos na Colômbia. Deixe a chave vazia para usar somente preços fixos.

API key: sua chave de API WooCommerce da Coordinadora. Depois de salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-la. A chave nunca é gravada no log.

Remove the saved API key: aparece somente quando há uma chave salva. Ative-o e clique em Save para excluir a chave; o método passa a usar somente preços fixos.

Origin city (DANE code): o código DANE de 8 dígitos da cidade 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 e completado para 8 dígitos.

COP per 1 unit of store currency: a Coordinadora cota em pesos colombianos. Se a moeda padrão da sua loja não for COP, informe quantos COP equivalem a 1 unidade da sua moeda, por exemplo 4300. A taxa também é usada para enviar o valor declarado em COP. Se deixada vazia, as cotações em tempo real não são usadas. A taxa deve ser maior que 0. Se a moeda padrão for COP, deixe vazio.

Preços fixos (usados quando não há chave de API, para destinos fora da Colômbia e como alternativa quando uma cotação em tempo real não está disponível)

Prices by country: uma lista de países com uma coluna Price e preços opcionais por tamanho do pacote, na moeda padrão da sua loja, sem impostos. O tamanho vem do peso do carrinho: XS até 1 kg, S de 1 a 2 kg, M de 2 a 3 kg, L de 3 a 5 kg, XL acima de 5 kg. Price é usado quando a coluna de tamanho é 0 ou está vazia. Clique em Add country para adicionar uma linha; uma linha nova começa com a Colômbia. O país * All other countries se aplica a países sem linha própria. Um país sem linha (e sem *) não recebe preço fixo. Uma linha com Price 0 e sem preço por tamanho oferece frete grátis.

Fixed price per: Order (padrão) cobra o preço uma vez. Item (price × quantity) o multiplica pelo número de itens no carrinho. Isso vale somente para preços fixos; uma cotação em tempo real da Coordinadora sempre cobre o pedido inteiro.

Condições

Min weight (kg): oculta o método abaixo deste peso do carrinho. 0 significa sem limite (padrão).

Max weight (kg): oculta o método acima deste peso do carrinho. Padrão: 25 (também usado quando o campo está vazio). 0 significa sem limite.

Minimum order subtotal: mostra o método somente se o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) for pelo menos este valor. Deixe vazio para mostrá-lo sempre.

Free shipping: ativa o frete grátis a partir do subtotal abaixo.

Free shipping from: o subtotal (após o cupom, antes dos impostos) a partir do qual o frete é gratuito. Usado somente quando Free shipping está ativado. Nesse caso, nenhuma requisição é feita à API.

Tax class: a classe de imposto do custo de envio, ou No tax (padrão). Com uma classe de imposto, o OpenCart adiciona o imposto do envio sobre a tarifa. Escolha No tax se seus preços ou a cotação da Coordinadora já incluírem impostos.

Geo zone: ofereça a Coordinadora somente para endereços desta zona geográfica. All zones (padrão) significa sem limite. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.

Countries: ofereça a Coordinadora somente para estes países de destino. Deixe vazio para permitir todos os países. Este limite se aplica junto com Geo zone.

Avançado

Debug log: grava os cálculos de tarifas em storage/logs/vfd_crd_debug.log.php (no OpenCart 4, system/storage/logs/vfd_crd_debug.log.php). O arquivo não pode ser lido pela web. Erros da API e configurações incompletas são sempre registrados, mesmo com esta opção desativada. A chave de API e os endereços dos clientes nunca são registrados. Quando o arquivo chega a 5 MB, ele é movido para vfd_crd_debug.old.log.php e um novo registro é iniciado.

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

Remove data on uninstall: quando ativado, desinstalar a extensão exclui as configurações da Coordinadora, as cotações em cache e os registros. Quando desativado (padrão), tudo é mantido para uma reinstalação.

Importação / Exportação

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A chave de API 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 são verificados como em um salvamento normal. A chave de API salva é mantida.

Como funciona na finalização de compra

Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço da Coordinadora. Se houver uma Geo zone definida e o endereço estiver fora dela, a Coordinadora não é oferecida. Somente produtos com Requires Shipping definido como Yes contam: os demais não adicionam peso e não entram na cotação. O subtotal é o preço dos produtos que precisam de envio, após o desconto do cupom e antes dos impostos. Vales-presente, pontos de fidelidade e crédito da loja não são considerados. A extensão verifica primeiro as condições: países permitidos, peso do carrinho e subtotal mínimo do pedido. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada à Coordinadora.

Para um endereço na Colômbia com chave de API, a extensão procura o código DANE da cidade de destino nesta ordem: um código DANE no campo de cidade (os módulos de finalização de compra colombianos para departamentos e cidades o gravam, por exemplo MEDELLIN (ANT) (05001000)), um CEP de 8 dígitos ou a lista integrada de capitais de departamento e de cerca de 40 das maiores cidades. Se o endereço tiver uma região (departamento), uma cidade da lista é conferida contra ela. Acentos e maiúsculas são ignorados.

Em seguida, a extensão envia à Coordinadora o código DANE de destino e cada produto com a cidade de origem, seu peso (kg), suas dimensões (cm), sua quantidade e seu valor declarado (COP). O valor declarado é o total da linha do produto antes dos impostos, após o desconto do cupom. As classes de peso e de comprimento dos produtos são convertidas automaticamente. A Coordinadora retorna o preço em COP; a extensão o converte para a moeda padrão da loja, arredonda para as casas decimais dessa moeda e o exibe na moeda do cliente com o imposto da Tax class selecionada. Cada cotação fica em cache por 1 hora. Uma requisição com falha é lembrada por 10 minutos, para que uma queda da Coordinadora nunca atrase cada atualização da finalização de compra. O tempo limite da API é de 10 segundos.

Quando uma cotação em tempo real não está disponível (erro da API, cidade desconhecida, produto sem peso ou dimensões, configurações incompletas), o preço fixo é usado. Se não houver um, o método fica oculto para aquele carrinho. Os detalhes dos erros vão para o registro de depuração, nunca para o cliente.

A extensão calcula somente tarifas. Ela não cria envios nem guías, não imprime etiquetas, não agenda coletas (recogidas), não rastreia pacotes, não faz cobrança na entrega (recaudo) e não oferece pontos de retirada Droop; use o portal da Coordinadora para isso. Ela não adiciona nada aos pedidos: o pedido mostra o nome do método e o custo de envio como qualquer outro método de envio do OpenCart. Destinos internacionais usam os preços fixos.

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 Coordinadora na janela Shipping method options. 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 Coordinadora é o primeiro bloco em Extensions > Extensions > Shipping > VibeFox Coordinadora > Edit, 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles aparecem a linha Product: opencart-shipping-coordinadora e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão de modificação para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do administrativo (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 com 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, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o endereço da loja definido na configuração do OpenCart. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, a Coordinadora não é mostrada aos clientes na finalização de compra e nenhuma tarifa é 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; por isso, sem uma chave ativa, o método fica oculto para todos. Depois de abrir a página Edit uma vez, aparece um lembrete 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 quando você abre o Dashboard do admin ou a página Edit: 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 Coordinadora não aparece na finalização de compra: verifique se a licença está ativa e se Enable Coordinadora está ativado. Confira os avisos no topo da página da extensão, Geo zone, Countries, os limites de peso e Minimum order subtotal. Sem cotação em tempo real, deve existir um preço fixo para o país ou para *. Verifique se os produtos têm Requires Shipping definido como Yes.

A tarifa em tempo real não aparece, somente o preço fixo: ative Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão. Motivos comuns: a cidade de destino não é reconhecida, um produto não tem peso ou dimensões, falta o código DANE de origem ou a taxa de câmbio para COP, ou a Coordinadora retornou um erro.

A cidade de destino não é reconhecida: instale um módulo de finalização de compra colombiano para departamentos e cidades que grave o código DANE no campo de cidade. Desenvolvedores podem mapear mais cidades ou alterar o endereço da API com os eventos do OpenCart vfd_coordinadora/dane_cities, vfd_coordinadora/destination_dane e vfd_coordinadora/api_url; o endereço da API também pode ser substituído pela configuração vfd_crd_api_url (para testes), que não tem campo na página de configurações.

A tarifa inclui imposto? A tarifa é a que a Coordinadora cota. Com uma Tax class, o OpenCart adiciona o imposto do envio sobre a tarifa; escolha No tax se a cotação já o incluir.

As tarifas parecem desatualizadas após uma mudança: clique em Save na página da extensão. Isso limpa as cotações em cache.

A página diz "Warning: You do not have permission to modify VibeFox Coordinadora!": o seu grupo de usuários administradores pode ter apenas permissão para visualizar as configurações. Dê ao grupo a permissão de modificação para extension/shipping/vfd_coordinadora (OpenCart 3) ou extension/vfd_coordinadora/shipping/vfd_coordinadora (OpenCart 4) em System > Users > User Groups.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Coordinadora. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable Coordinadora, Sort order, Tax class e Geo zone. As cotações em cache são sempre removidas. Se Remove data on uninstall estiver ativado, as configurações da Coordinadora e os registros também são excluídos. Se estiver desativado, as demais configurações são mantidas e usadas novamente quando você reinstalar a extensão. Os pedidos existentes mantêm seu método e custo de envio.

No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer após a desinstalação, clique em Uninstall (o botão laranja −) ao lado de VibeFox Coordinadora na lista de extensões instaladas e depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

A Coordinadora é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pela Coordinadora.