VibeFox Coordinadora for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo não é instalado em versões mais antigas do PHP.

Chave de API da Coordinadora (somente para cotações em tempo real): as cotações em tempo real vêm do Cotizador da Coordinadora por meio do serviço Coordinadora WooCommerce, o mesmo usado pelo plugin oficial da Coordinadora. A Coordinadora emite a chave de API para clientes com acordo comercial ativo. Fale com o 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 chave, a transportadora funciona apenas com preços fixos.

Produtos: para uma cotação em tempo real, cada produto do carrinho precisa de peso e dimensões (largura, altura, profundidade).

Chave de licença 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 Coordinadora 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. Informe a chave de API, o código DANE da cidade de origem e, se a sua moeda padrão não for o COP, a taxa de câmbio para COP. Adicione pelo menos um preço fixo para a Colômbia como alternativa (veja Configuração). Clique em Save.

5. Verifique se a Colômbia está ativa na sua loja e se os seus produtos têm peso e dimensões.

Ao instalar, o módulo cria a transportadora Coordinadora com o texto de prazo de entrega Courier delivery in Colombia. 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 Coordinadora > Configure. Elas se aplicam a todas as zonas da transportadora. Cada seção tem o seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa as cotações da Coordinadora em cache. Os números podem ser digitados com ponto ou vírgula (9,99 = 9.99).

A página não salva e mostra um erro quando um número ou um preço da tabela é inválido ou negativo, quando COP per 1 unit of store currency é 0, quando Min weight é maior que Max weight ou quando Name tem mais de 64 caracteres. Nada é salvo até que você corrija.

A página mostra avisos no topo quando as cotações em tempo real não podem funcionar ou a transportadora ficaria oculta: Origin city (DANE code) está vazio ou inválido, COP per 1 unit of store currency está ausente enquanto a sua moeda padrão não é o COP, ou não há preço fixo para a Colômbia (ou *). Sem chave de API e sem esse preço fixo, a transportadora nunca é exibida para endereços colombianos. Um aviso também aparece quando a unidade de peso ou de dimensão da loja em International > Localization (Local units) não é conhecida pelo módulo; nesse caso, os pesos dos produtos são lidos como kg e as dimensões como cm.

Geral

Enable Coordinadora: liga ou desliga a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.

Name: o nome da transportadora exibido ao cliente na finalização de compra. Padrão: Coordinadora. Obrigatório.

Tax: a regra de imposto da transportadora, ou No tax. Com uma regra, o PrestaShop adiciona o imposto do frete sobre a tarifa. Escolha No tax se os seus preços ou a cotação da Coordinadora já incluírem imposto.

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: a sua chave de API do Coordinadora WooCommerce, fornecida pela Coordinadora. Depois de salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente para alterá-la. A chave nunca é gravada no log.

Remove the saved API key: aparece somente quando uma chave está salva. Ative e clique em Save para apagar a chave; a transportadora 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 sua moeda padrão não for o COP, informe quantos COP valem 1 unidade da sua moeda, por exemplo 4300. A taxa também é usada para enviar o valor declarado em COP. Se deixar vazio, as cotações em tempo real não são usadas. A taxa deve ser maior que 0. Se a sua moeda padrão for o 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 tabela de países com uma coluna Price e preços opcionais por tamanho de pacote, na sua moeda padrão, sem impostos. O tamanho vem do peso do carrinho: XS até 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL acima de 5 kg. Price é usado quando a coluna de tamanho está em 0 ou vazia. Clique em Add country para adicionar uma linha e no X para remover uma. 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 cobra o preço uma vez. Item (price × quantity) multiplica pelo número de itens do carrinho. Isso se aplica somente aos preços fixos; uma cotação em tempo real da Coordinadora sempre cobre o pedido inteiro.

Condições

Min weight: oculta a transportadora abaixo deste peso do carrinho, em kg. 0 significa sem limite.

Max weight: oculta a transportadora acima deste peso do carrinho, em kg. Padrão: 25 (também usado quando o campo está vazio). 0 significa sem limite. Não pode ser menor que Min weight.

Minimum order subtotal: mostra a transportadora somente se o subtotal do carrinho (após descontos, antes de impostos) for pelo menos este valor. Deixe vazio para mostrá-la sempre.

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

Free shipping from: o subtotal do carrinho (após descontos, antes de impostos) a partir do qual o frete é grátis. Usado somente quando Free shipping está ativo. Nesse caso, nenhuma requisição à API é feita.

Countries: oferece a Coordinadora somente para estes países de destino. Só países ativos são listados. Deixe vazio para permitir todos os países das zonas da transportadora.

Avançado

Debug log: grava os cálculos de tarifas em logs/vfd_crd_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros da API e configurações incompletas são sempre registrados, mesmo com esta opção desligada. A chave de API e os endereços dos clientes nunca são registrados.

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 ativo, desinstalar o módulo apaga as configurações da Coordinadora, a transportadora, as cotações em cache e os logs. Quando desligado, tudo é mantido para uma reinstalação.

Como funciona na finalização de compra

Na etapa de frete, o PrestaShop pede ao módulo o preço da Coordinadora. Só produtos físicos contam: produtos virtuais não somam peso e não entram na cotação. O módulo 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, o módulo encontra o código DANE da cidade de destino nesta ordem: um código DANE no campo de cidade (os módulos de departamentos e cidades colombianos o gravam, por exemplo MEDELLIN (ANT) (05001000)), um CEP de 8 dígitos ou a lista integrada das capitais de departamento e de cerca de 40 das maiores cidades. Se o endereço tiver departamento (estado), uma cidade da lista é verificada contra ele. Acentos e maiúsculas/minúsculas são ignorados.

Em seguida, o módulo envia à Coordinadora o código DANE de destino e cada produto com a cidade de origem, seu peso (kg), dimensões (cm), quantidade e valor declarado (COP). O valor declarado é o total da linha do produto antes dos impostos e antes dos descontos do carrinho. As unidades da loja são convertidas automaticamente. A Coordinadora devolve o preço em COP, e o módulo o converte para a sua moeda padrão e depois para a moeda do carrinho do cliente. Cada cotação fica em cache por 1 hora. Uma requisição com falha fica registrada por 10 minutos, para que uma indisponibilidade da Coordinadora nunca deixe lenta 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 ausentes), o preço fixo é usado. Se não houver um, a transportadora fica oculta para aquele carrinho. Os detalhes de erro vão para o log de depuração, nunca para o cliente.

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 segue a nova versão automaticamente.

O módulo calcula apenas as cotações. Ele não cria envios ou guias (guías), não imprime etiquetas, não agenda coletas (recogidas), não rastreia encomendas, não faz cobrança na entrega (recaudo) nem oferece pontos de coleta Droop; use o portal da Coordinadora para isso. Destinos internacionais 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 Coordinadora é o primeiro bloco da página Modules > Module Manager > VibeFox Coordinadora > Configure, acima das configurações. Digite 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 ficam a linha Product: presta-shipping-coordinadora e o link Manage licenses and domains in your account, que abre a sua conta em 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, inclusive em uma configuração multiloja. 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 transportadora Coordinadora não é exibida aos clientes na finalização de compra, e nenhuma cotação é calculada. A vitrine do PrestaShop não sabe que você está logado no 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 exigem a 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. 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 Coordinadora não aparece na finalização de compra: verifique se a licença está ativa e se Enable Coordinadora está ligado. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente. Confira 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 *. Os produtos também podem ser limitados a determinadas transportadoras na página do produto.

A cotação em tempo real não aparece, só o preço fixo: ative Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo. Motivos comuns: a cidade de destino não é reconhecida, um produto não tem peso ou dimensões, o código DANE de origem ou a taxa de COP está ausente, ou a Coordinadora retornou um erro.

A cidade de destino não é reconhecida: instale um módulo de departamentos e cidades colombianos para finalização de compra que grave o código DANE no campo de cidade. Desenvolvedores podem mapear mais cidades com os hooks do módulo actionVfdCrdDaneCities e actionVfdCrdDestinationDane, ou alterar o endereço da API com actionVfdCrdApiUrl.

A cotação inclui imposto? A cotação é o que a Coordinadora informa. Com uma regra de Tax, o PrestaShop adiciona o imposto do frete por cima; escolha No tax se a cotação já o incluir.

As cotações parecem desatualizadas após uma alteração: clique em Save na página do módulo. Isso limpa as cotações em cache.

A página diz que a transportadora Coordinadora não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Coordinadora e escolha Uninstall. A chave de licença, o status da licença e as cotações em cache são sempre removidas. Se Remove data on uninstall estiver ativo, a transportadora é excluída (os pedidos mantêm o histórico) e as configurações e o log são removidos. Se estiver desligado, a transportadora é apenas desativada e todas as configurações são mantidas. Reinstalar o módulo, ou um Reset, devolve à transportadora salva o status que ela tinha antes: uma transportadora que você desativou continua desativada.

A Coordinadora é marca registrada do respectivo titular. Este módulo não é afiliado nem endossado pela Coordinadora.