VibeFox Chilexpress for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não ativa sem ele.

PHP: 8.0 ou superior.

Chaves de API da Chilexpress (somente para tarifas em tempo real): crie uma conta no portal de desenvolvedores da Chilexpress (developers.wschilexpress.com) e assine dois produtos: Rating (Cotizador) e Coverage (Coberturas / Georreferencia). Cada produto tem sua própria chave de assinatura. Chaves de teste funcionam somente com o ambiente de teste; chaves de produção são emitidas para clientes corporativos da Chilexpress com contrato de cliente. Você também precisa do código county da Chilexpress da comuna de onde envia, por exemplo STGO. Se usar somente preços fixos, você não precisa de chaves de API.

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_chilexpress para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Chilexpress, 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. Preencha a tabela de preços. Para tarifas em tempo real, informe as duas chaves de assinatura, o código county de origem e, se a moeda da loja não for CLP, a taxa de câmbio para CLP; depois escolha a fonte das tarifas (veja Configuração).

6. Adicione VibeFox Chilexpress a uma zona de entrega para o Chile 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 Chilexpress. 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 desta opção de entrega na finalização de compra para esta zona. Deixe em branco para usar o Name global.

A página de configurações mostra os problemas no topo: há tarifas de API selecionadas, mas falta uma chave, o código county de origem ou a taxa de câmbio para CLP, ou a tabela de preços não tem linha para o Chile nem para * Default. Sempre que você salva as configurações, as tarifas e as listas de comunas em cache são apagadas. Os números podem ser digitados com ponto ou vírgula; um número inválido não é salvo e um erro é exibido.

Geral

Enable/Disable: liga ou desliga a entrega pela Chilexpress em todas as zonas de uma vez.

Name: o nome do método de entrega exibido ao cliente na finalização de compra. Default: Chilexpress.

Tax status: Taxable adiciona o imposto do WooCommerce ao custo de entrega (se os impostos estiverem ativados), None não adiciona. As tarifas da API da Chilexpress são usadas exatamente como cotadas. Escolha None se a cotação já incluir IVA e sua loja acrescentaria imposto por cima.

Tarifas

Rate source: de onde vem o preço.

As tarifas em tempo real estão disponíveis somente para destinos no Chile. Os demais países sempre usam os preços fixos.

Country prices: uma tabela de países de destino 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 até 2 kg, M até 3 kg, L até 5 kg, XL acima de 5 kg. Um tamanho deixado em 0 usa Price. Clique em + Add country para adicionar uma linha e no X para removê-la. A linha * Default vale para países sem linha própria. Um país sem linha (e sem *) não tem preço fixo. Uma linha cujo preço e preço por tamanho são ambos 0 oferece frete grátis.

Calculation type: Per order cobra o preço fixo uma vez. Per item (fixed price x number of items) multiplica pelo número de itens no carrinho. Uma tarifa da API da Chilexpress é sempre cotada para o pacote inteiro.

API da Chilexpress (tarifas em tempo real)

Test environment: usa o ambiente de teste da Chilexpress (qaservices.wschilexpress.com). Use com chaves de teste e desative em uma loja em produção.

Rating API key: a chave de assinatura do produto Rating (Cotizador).

Coverage API key: a chave de assinatura do produto Coverage (Coberturas / Georreferencia). Ela é usada para encontrar o código county da Chilexpress da comuna do cliente (o campo Cidade na finalização de compra).

Origin county code: o código county da Chilexpress (comuna) de onde você envia, de 2 a 5 letras, por exemplo STGO (Santiago Centro), PROV (Providencia), LCON (Las Condes), VALP (Valparaíso) ou CONC (Concepción). Um valor que não é um código county é rejeitado com erro.

Service: o serviço da Chilexpress usado para a tarifa. Se ele não for oferecido para o destino, é usado o serviço mais barato disponível.

CLP exchange rate: a Chilexpress cota em pesos chilenos. Necessário somente se a moeda da sua loja não for CLP: o preço de 1 CLP na moeda da loja, por exemplo 0.001. Sem ele as tarifas da API não são usadas.

Disponibilidade

Min weight (kg): o peso mínimo do carrinho para o método aparecer. 0 significa sem limite.

Max weight (kg): o método fica oculto acima deste peso do carrinho. Default: 25. 0 significa sem limite.

Minimum subtotal: mostra o método somente quando o subtotal do carrinho (após descontos, sem impostos) é pelo menos este valor. Deixe em branco para sempre mostrar.

Excluded shipping classes: oculta o método quando algum item do carrinho pertence a uma destas classes de entrega do WooCommerce.

Ignore shipping zones: oferece o método para os países abaixo mesmo sem adicioná-lo a uma zona de entrega.

Countries: os países de destino para esse modo. Deixe em branco para usar todos os países de entrega da loja. Este campo só é usado quando Ignore shipping zones está ativado.

Frete grátis

Free shipping: ativa o limite de frete grátis.

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

Avançado

Debug log: registra as requisições à API e os cálculos de tarifas em WooCommerce > Status > Logs, origem vfd-chilexpress. Erros da API são sempre registrados, mesmo com esta opção desativada. Chaves de API nunca são registradas.

Remove data on uninstall: quando ativado, excluir o plugin remove suas configurações e os métodos das zonas. Desativar nunca apaga as configurações. As linhas de entrega de pedidos existentes são sempre mantidas.

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 e classes de entrega excluídas. Se o frete grátis se aplicar, o cliente recebe uma tarifa gratuita e nenhuma requisição é enviada à Chilexpress.

Para um endereço no Chile e uma fonte de tarifas de API, o plugin pega a região e a comuna do campo Cidade e procura o código county da Chilexpress na lista de comunas dessa região (API Coverage). Acentos, espaços e variações de grafia são ignorados, então Ñuñoa e Nunoa coincidem, e Santiago coincide com Santiago Centro. Um código county digitado no campo Cidade também é aceito. Em seguida, o plugin envia à API Rating os códigos county de origem e destino, o peso do carrinho (no mínimo 0,1 kg), as dimensões do pacote (comprimento e largura do maior produto, alturas somadas) e o subtotal do carrinho em CLP como valor declarado. A Chilexpress retorna seus serviços; o plugin usa o serviço escolhido ou o mais barato e converte o valor em pesos para a moeda da sua loja. O nome do serviço é salvo na linha de entrega do pedido como Chilexpress service.

As tarifas ficam em cache por 1 hora e as listas de comunas por 7 dias. Uma requisição que falhou é lembrada por 5 minutos, para que uma API lenta ou indisponível não atrase cada atualização da finalização de compra. O timeout da API é de 10 segundos. Se a Chilexpress retornar erro, nenhum serviço com preço ou uma comuna desconhecida, o cliente não vê erro algum. O método fica oculto no modo somente API, ou o preço fixo é usado. O motivo é gravado no log do WooCommerce.

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 High-Performance Order Storage (HPOS) do WooCommerce.

O plugin calcula somente tarifas. Ele não cria envios nem ordens de transporte (OT), não imprime etiquetas, não agenda coletas e não rastreia pacotes; faça a reserva do envio na sua conta da Chilexpress. Os clientes não podem escolher uma agência da Chilexpress, e não há seletor de comuna: o cliente digita a comuna no campo Cidade padrão. 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 Chilexpress. 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 em 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 em vibefox.net.

Sem uma chave ativa, a Chilexpress não é exibida aos clientes na finalização de compra. Gerentes da loja 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 aviso 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 exigem renovação. O status é verificado novamente de forma automática em segundo plano.

Solução de problemas

A Chilexpress não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado 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). Verifique os limites de peso, Minimum subtotal e Excluded shipping classes. Com preços fixos, confira se o país ou * Default tem uma linha.

A tarifa em tempo real não aparece e o preço fixo é usado no lugar: primeiro veja os avisos no topo da página de configurações. Caso contrário, ative Debug log, recarregue a finalização de compra e abra WooCommerce > Status > Logs, origem vfd-chilexpress. Causas comuns: uma comuna que a Chilexpress não reconhece (verifique o campo Cidade e a região), uma chave de outro produto ou ambiente, ou um destino sem cobertura da Chilexpress.

HTTP 401 ou 403 no log: a chave de assinatura está errada, inativa ou é de outro produto ou ambiente. Chaves de teste funcionam somente com Test environment ativado.

As tarifas da API não são usadas em uma loja com outra moeda: informe o CLP exchange rate.

As tarifas da API incluem IVA ou não? Elas são usadas exatamente como a Chilexpress as cota. Se a sua loja acrescenta imposto ao frete e a cotação já inclui IVA, defina Tax status como None.

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

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 em 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 estiver inacessível, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todas as configurações; ele só limpa as tarifas e as listas de comunas em cache. Para removê-lo, desative e exclua na página Plugins. A chave de licença e o status de licença deste plugin, assim como os caches, são sempre removidos. Configurações e métodos de zona só são removidos se Remove data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. As linhas de entrega de pedidos existentes são sempre mantidas.

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