VibeFox Cargoson 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 Cargoson (somente para preços em tempo real): os preços em tempo real usam a API de preços de frete da Cargoson. As consultas de preço de frete exigem uma assinatura Cargoson com acesso à API (plano Advanced ou superior no momento da redação). A chave de API é emitida na sua conta Cargoson; se o seu plano não mostrar as configurações de API, peça ajuda ao suporte da Cargoson. Os preços vêm das transportadoras e das tabelas conectadas a essa conta. Se você usar apenas preços fixos, não precisa de uma conta Cargoson.
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_cargoson para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Cargoson, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Escolha como o custo de entrega será calculado e preencha as seções correspondentes: os preços fixos e, para os preços em tempo real, a chave de API e o CEP de coleta (veja Configuração).
6. Adicione VibeFox Cargoson 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 estão em uma única página: WooCommerce > Settings > Shipping > VibeFox Cargoson. Elas valem para todas as zonas de entrega. Quando você adiciona o método a uma zona, a janela da zona tem apenas um campo:
Title (zone): o nome exibido ao cliente nesta zona. Deixe vazio para usar o Method title global.
Sempre que você salvar as configurações, os preços da Cargoson em cache são apagados. Números decimais podem ser digitados com ponto ou vírgula.
General
Enable/Disable: ativa ou desativa o método em todas as zonas de uma só vez.
Method title: o nome do método de entrega exibido no carrinho e na finalização de compra. Padrão: Cargoson. Uma zona pode substituí-lo.
Shipping cost: como o preço é calculado.
O motivo de um preço em tempo real ausente é registrado no log do WooCommerce. Ele nunca é exibido ao cliente.
Cargoson API (obrigatória somente para preços em tempo real)
API key: a chave de API da sua conta Cargoson. Ela é enviada somente para cargoson.com e nunca é exibida aos clientes nem gravada no log.
Carrier: quais preços são usados. O cliente vê uma única tarifa.
Package type code: o tipo de pacote da Cargoson enviado com a consulta de preço. Padrão: CLL. Os exemplos da API da Cargoson usam EUR (palete EUR) e FIN (palete FIN). Para encomendas, use o código de pacote da sua conta Cargoson. O pedido é enviado como um único pacote com o peso total do carrinho.
Price currency: a moeda dos preços na sua conta Cargoson, como código de 3 letras. Padrão: EUR. A API retorna valores sem código de moeda.
Currency conversion rate: necessária apenas se a moeda dos preços for diferente da moeda da loja: 1 unidade da moeda da Cargoson = X unidades da moeda da loja. Deixe vazio para rejeitar esses preços, assim o cliente nunca paga na moeda errada.
Ship from (collection address) (usado para preços em tempo real)
Collection country: o país de onde você envia. Por padrão, é o país da sua loja.
Collection postcode: o CEP de onde você envia. A Cargoson exige. Se estiver vazio e o país de coleta for o da sua loja, é usado o CEP da loja em WooCommerce > Settings > General.
A data de coleta enviada à Cargoson é hoje ou, em fins de semana, a próxima segunda-feira.
Fixed prices (usados quando Shipping cost é Fixed prices, e como alternativa para os preços em tempo real)
Price per country and size: uma tabela de países com uma coluna Price e preços por peso do carrinho na moeda da loja: XS até 1 kg, S até 2 kg, M até 3 kg, L até 5 kg, XL acima de 5 kg. Um preço de tamanho vazio ou 0 usa a coluna Price; uma coluna Price vazia significa que não há preço fixo para aquele tamanho. Clique em Add country para adicionar uma linha e no X para remover uma. A linha * Default vale para todos os países que não tenham linha própria. Países sem linha (quando não há linha *) não recebem preço fixo, por isso o método fica oculto para eles.
Fixed price applies: Per order cobra o preço uma única vez. Per item (price × quantity) multiplica o preço pela quantidade de itens no carrinho. Os preços em tempo real da Cargoson são sempre por envio.
Conditions
Minimum weight (kg): oculta o método abaixo deste peso de carrinho. 0 significa sem limite.
Maximum weight (kg): oculta o método acima deste peso de carrinho. Padrão: 25. 0 significa sem limite.
Minimum order amount: exibe o método somente quando o subtotal do carrinho (após descontos, antes dos impostos) for pelo menos este valor. Deixe vazio para exibi-lo sempre.
Excluded shipping classes: oculta o método se o carrinho tiver um produto de qualquer uma destas classes de entrega do WooCommerce.
Free shipping: ativa a entrega grátis quando o valor do pedido abaixo for atingido.
Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual a entrega é grátis. Usado somente quando Free shipping está ativado.
Tax status: Taxable adiciona imposto sobre a entrega de acordo com as suas configurações de impostos do WooCommerce; None não adiciona. As tarifas das transportadoras na Cargoson costumam ser líquidas (sem IVA). Escolha None se os seus preços já incluírem impostos.
Availability without shipping zones
Ignore shipping zones: oferece a Cargoson para os países abaixo, mesmo que ela não esteja adicionada 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 você entrega. Este campo é usado somente quando Ignore shipping zones está ativado.
Advanced
Debug log: registra cada cálculo de tarifa em WooCommerce > Status > Logs, origem vfd_cargoson. Erros da API são sempre registrados, mesmo com esta opção desativada. A chave de API e o CEP do cliente nunca são registrados.
Remove data on uninstall: quando ativado, excluir o plugin remove todas as configurações da Cargoson, os métodos das zonas e os preços 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. Se a entrega grátis se aplicar, o cliente recebe uma tarifa grátis e nenhuma solicitação é enviada à Cargoson.
No modo de preços fixos, o preço é obtido da tabela. Nos modos em tempo real, o plugin envia à Cargoson a data de coleta, o país e o CEP de coleta, o país e o CEP de entrega, e um pacote com o código do tipo de pacote e o peso total do carrinho (no mínimo 0,1 kg). Os pesos dos produtos são convertidos da unidade da sua loja para quilogramas. Um preço em tempo real só é solicitado depois que o cliente informa um CEP. A Cargoson retorna os preços das suas transportadoras; o plugin escolhe o mais barato (da transportadora selecionada, se houver) e o converte para a moeda da loja, se necessário.
Cada resposta fica em cache por 1 hora, para que o mesmo carrinho não gere uma nova solicitação. Uma solicitação com falha fica em cache por 10 minutos, para que a finalização de compra não espere pela Cargoson a cada atualização. O tempo limite da API é de 10 segundos. Se a Cargoson retornar um erro, nenhum preço para a rota ou um preço em outra moeda sem taxa de conversão, o cliente não vê nenhum erro. O método fica oculto ou, no modo de contingência, é usado o preço fixo.
O método funciona na finalização de compra clássica e nos blocos de Carrinho e Finalização de compra. Ele é compatível com o WooCommerce High-Performance Order Storage (HPOS).
O plugin calcula somente tarifas. Ele não cria envios nem reservas na Cargoson, não imprime etiquetas nem rastreia encomendas, e os clientes não podem escolher um armário automático de encomendas nem um ponto de retirada. O carrinho é cotado como um único pacote com o peso total; as dimensões do pacote não são enviadas. Apenas o preço mais baixo é exibido, não uma lista de transportadoras.
Pedidos
Quando um preço em tempo real é usado, a linha de entrega do pedido salva a Carrier, o Service e o Cargoson service ID cotados. Eles aparecem na tela de edição do pedido, para que você saiba o que reservar na Cargoson. Reserve o envio na Cargoson ou com as integrações dela.
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 Cargoson. 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 único 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 Cargoson 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 Cargoson 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 amount e Excluded shipping classes. No modo de preços fixos, confirme que o país ou o * Default tem preço para o tamanho do carrinho.
Os preços em tempo real não aparecem: abra WooCommerce > Status > Logs, origem vfd_cargoson. Erros da API são sempre registrados; ative o Debug log para ver cada cálculo. Motivos comuns: nenhum CEP de entrega informado ainda, nenhum CEP de coleta, chave de API rejeitada (chave errada ou expirada, ou sem acesso à API no seu plano Cargoson), nenhuma transportadora para a rota ou o peso, ou um preço em outra moeda. Com Cargoson live prices, fixed prices if the API fails, os clientes continuam recebendo o preço fixo enquanto você resolve o problema.
A Cargoson rejeita o tipo de pacote: use o código de pacote que a sua conta Cargoson utiliza em Package type code. O motivo aparece no log.
Um preço em outra moeda é rejeitado: defina Price currency como a moeda dos seus preços da Cargoson e informe a Currency conversion rate.
As tarifas parecem desatualizadas após uma mudança: salve a página de configurações. Isso limpa os preços da Cargoson 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 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 todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin são sempre removidos. As configurações, os métodos das zonas e os preços em cache 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 entrega.
A Cargoson é uma marca registrada de seu respectivo titular. Este plugin não é afiliado à Cargoson nem endossado por ela.