VibeFox Coordinadora 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.

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 WooCommerce da Coordinadora, o mesmo que o plugin oficial da Coordinadora usa. A Coordinadora emite a chave de API para clientes com acordo comercial ativo. Pergunte ao seu gerente de conta na Coordinadora ou veja wc.coordinadora.com. Você também precisa do código DANE de 8 dígitos da cidade de onde envia. Sem chave, o método funciona apenas com preços fixos.

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

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.

Instalação

1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta vfd_coordinadora para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Coordinadora, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Digite a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

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

6. Adicione VibeFox Coordinadora a uma zona de entrega que cubra a Colômbia em WooCommerce > Settings > Shipping > Shipping zones, ou ative Ignore shipping zones e escolha os países.

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

Configuração

Todas as configurações estão em uma única página: WooCommerce > Settings > Shipping > VibeFox Coordinadora. 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 do método de entrega exibido ao cliente nesta zona. Deixe vazio para usar o Name global.

A página de configurações mostra avisos no topo quando as cotações em tempo real não podem funcionar ou o método ficaria oculto: o código DANE de origem está ausente ou é inválido, a taxa de câmbio em COP está ausente ou não há preço fixo para a Colômbia. Sempre que você salva as configurações, as cotações em cache são apagadas. Os números podem ser digitados com ponto ou vírgula (9,99 = 9.99).

Geral

Enable/Disable: ativa ou desativa a Coordinadora em todas as zonas de uma só vez.

Name: o nome do método de entrega exibido ao cliente na finalização de compra. Padrão: Coordinadora. O Title de uma zona o substitui.

Tax status: Taxable adiciona o imposto de frete do WooCommerce sobre a tarifa, None não adiciona. Escolha None se os seus preços ou a cotação da Coordinadora já incluírem impostos.

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 apenas preços fixos.

API key: a sua chave de API do WooCommerce da Coordinadora. Ela nunca é gravada no log.

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 da sua loja não for 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. Se a moeda da loja 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 tabela de países com uma coluna Price e preços opcionais por tamanho de pacote na moeda da sua loja. 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 é 0 ou está vazia. Clique em + Add country para adicionar uma linha e no X para remover uma. O país * All other countries se aplica aos 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 dá frete grátis.

Fixed price per: Order cobra o preço uma vez. Item (price × quantity) o multiplica pelo número de itens no carrinho. Isso vale apenas 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.

Max weight (kg): oculta o método acima deste peso do carrinho. Padrão: 25. 0 significa sem limite.

Minimum order subtotal: mostra o método somente se o subtotal do carrinho for pelo menos este valor. Deixe vazio para mostrar sempre.

Excluded shipping classes: oculta o método se um item do carrinho pertencer a uma destas classes de entrega do WooCommerce.

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

Free shipping from: o subtotal do carrinho a partir do qual o frete é grátis. Usado somente quando Free shipping está ativado. Nesse caso, nenhuma requisição à API é feita.

Disponibilidade sem zonas de entrega

Ignore shipping zones: oferece o método para os países abaixo, mesmo que ele não esteja adicionado a uma zona de entrega.

Countries: os países de destino para esse modo. Deixe vazio para usar todos os países para os quais a loja envia. Este campo só é usado quando Ignore shipping zones está ativado.

Avançado

Debug log: registra os cálculos de tarifas em WooCommerce > Status > Logs, origem vfd-coordinadora. Erros da API são sempre registrados, mesmo com esta opção desativada. A chave de API e os endereços dos clientes nunca são registrados.

Remove data on uninstall: quando ativado, excluir o plugin remove as suas configurações, os métodos de zona e as cotações em cache. Desativar o plugin nunca apaga dados.

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: peso do carrinho, subtotal mínimo do pedido e classes de entrega excluídas. Se o frete grátis se aplicar, o cliente recebe uma tarifa grátis e nenhuma requisição é enviada à Coordinadora.

Para um endereço na Colômbia com chave de API, o plugin encontra o código DANE da cidade de destino nesta ordem: um código DANE no campo de cidade (os plugins de departamentos e cidades colombianos para finalização de compra 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. Uma cidade da lista é conferida com o departamento selecionado. Acentos e maiúsculas/minúsculas são ignorados.

Em seguida, o plugin 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). As unidades da loja são convertidas automaticamente. A Coordinadora devolve o preço em COP, e o plugin o converte para a moeda da sua loja. Cada cotação fica em cache por 1 hora. Uma requisição com falha fica registrada por 10 minutos, para que uma queda 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), usa-se o preço fixo. Se não houver nenhum, o método fica oculto. Os detalhes dos erros vão para o log do WooCommerce, nunca para o cliente.

O método funciona na finalização de compra clássica e nos blocos de Carrinho e Finalização de compra. É compatível com o HPOS (High-Performance Order Storage) do WooCommerce.

O plugin calcula apenas tarifas. Ele não cria envios nem 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. Não há cotação de entrega no mesmo dia, e destinos internacionais usam os preços fixos.

Chave de licença

O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Shipping > VibeFox Coordinadora. 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 na vibefox.net.

Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga de domínio. Libere a vaga na sua conta da vibefox.net.

Sem uma chave ativa, a Coordinadora não é mostrada aos clientes na finalização de compra. Os gerentes da loja que estiverem logados 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. Pedidos existentes não são afetados.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática em segundo plano.

Solução de problemas

A Coordinadora 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 é permitido). Confira os limites de peso, Minimum order subtotal e Excluded shipping classes. Sem cotação em tempo real, deve existir um preço fixo para o país ou para *.

A cotação em tempo real não aparece, só o preço fixo: ative o Debug log, recarregue a finalização de compra e abra WooCommerce > Status > Logs, origem vfd-coordinadora. Motivos comuns: a cidade de destino não foi reconhecida, um produto não tem peso ou dimensões, falta o código DANE de origem ou a taxa de câmbio em COP, ou a Coordinadora retornou um erro.

A cidade de destino não é reconhecida: instale um plugin 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 filtros vfd_crd_dane_cities e vfd_crd_destination_dane.

A tarifa inclui impostos? A tarifa é a que a Coordinadora cota. Com Tax status em Taxable, o WooCommerce adiciona o imposto de frete por cima; escolha None se a cotação já o incluir.

As tarifas parecem desatualizadas após uma mudança: salve a página de configurações. Isso limpa as cotações em cache.

O bloco de licença mostra um erro: siga a mensagem do bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta da vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no 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 todas as configurações; ele apenas limpa as cotações em cache. Para remover, desative e exclua o plugin na página Plugins. A chave de licença e o status de licença deste plugin, assim como as cotações em cache, são sempre removidos. Configurações e métodos de zona são removidos somente se Remove data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Pedidos existentes mantêm suas linhas de frete.

A Coordinadora é marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Coordinadora.