VibeFox Correios for WooCommerce — Ajuda
Requisitos
WordPress: 5.8 ou superior.
WooCommerce: 5.0 ou superior, instalado e ativo. O plugin não ativa sem ele.
PHP: 8.0 ou superior.
Contrato dos Correios (apenas para preços em tempo real): os preços em tempo real usam a API de preços dos Correios Web Services (CWS) e precisam das credenciais de um contrato dos Correios com cartão de postagem. Você precisa de três dados: o seu usuário do Meu Correios (geralmente o CNPJ ou CPF do contrato), o código de acesso à API e o número do cartão de postagem. Gere o código de acesso no portal dos Correios Web Services (cws.correios.com.br; para homologação, cwshom.correios.com.br). Você também precisa do CEP de onde envia. Sem credenciais, o plugin funciona apenas com preços fixos.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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_correios para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Correios, 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. Informe o usuário da API dos Correios, o código de acesso, o número do cartão de postagem, o CEP de origem e o serviço. Se a moeda da sua loja não for BRL, informe a cotação em BRL. Preencha os preços fixos para outros países e como alternativa (veja Configuração).
6. Adicione VibeFox Correios a uma zona de envio 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 Correios. Elas valem para todas as zonas de envio. Ao adicionar o método a uma zona, a janela da zona tem apenas um campo:
Title (zone): o nome mostrado ao cliente nesta zona. Deixe vazio para usar o Method title geral.
A página de configurações mostra avisos quando os preços em tempo real ou o método não podem funcionar: só parte das três credenciais está preenchida, falta o CEP de origem, falta a cotação em BRL para uma loja em outra moeda, ou não há nem credenciais nem preços fixos. Sempre que você salva as configurações, os preços em cache e o token da API são limpos. Os números podem ser digitados com ponto ou vírgula.
Geral
Enable/Disable: ativa ou desativa o método em todas as zonas de uma vez.
Method title: o nome do método de envio mostrado no carrinho e na finalização da compra. Padrão: Correios. Uma zona pode substituí-lo por um título próprio.
Tax status: Taxable adiciona o imposto do WooCommerce sobre o valor do frete; None não adiciona.
API dos Correios (preços em tempo real no Brasil)
Para endereços no Brasil, o preço vem da API de preços dos Correios. Se a API não retornar preço (API fora do ar, CEP não atendido, pacote grande demais), é usado o preço fixo de Country prices, ou o método fica oculto se não houver um.
API user: o seu login no portal Meu Correios, geralmente o CNPJ ou CPF do contrato.
Access code: o código de acesso à API gerado no portal dos Correios Web Services. Não é a senha do portal.
Posting card: o número do cartão de postagem do seu contrato: 10 dígitos, geralmente começando com dois zeros, por exemplo 0012345678. Números menores são completados com zeros à esquerda. Você pode conferir o número na página Correios Fácil do site dos Correios.
Homologation: usa o ambiente de homologação (teste) dos Correios com um código de acesso de homologação. Desative em uma loja em produção.
Origin CEP: o CEP (8 dígitos) de onde os pacotes são enviados, por exemplo 01001-000.
Service: o serviço dos Correios cobrado na finalização da compra. Códigos de varejo: PAC (04510, padrão), SEDEX (04014), SEDEX 12 (04782), SEDEX 10 (04790), SEDEX Hoje (04804). Códigos de contrato: PAC (03298), SEDEX (03220), SEDEX 12 (03140), SEDEX 10 (03158), SEDEX Hoje (03204), Correios Mini Envios (04227). Códigos de contrato exigem um cartão de postagem de um contrato que inclua o serviço.
Other service code: opcional, um código de serviço de 5 dígitos do seu contrato que não está na lista, por exemplo 03085. Quando preenchido, é usado no lugar de Service.
Package format: o tipo de objeto enviado aos Correios.
Default product weight (kg): enviado aos Correios para cada produto sem peso. Default: 0.3. Pesos e dimensões dos produtos são convertidos a partir das unidades da sua loja, e o carrinho é cobrado como um único pacote.
BRL → store currency rate: o nome do campo mostra a moeda da sua loja. Os preços dos Correios estão em BRL. Se a moeda da sua loja não for BRL, informe quantas unidades da sua moeda valem 1 BRL, por exemplo 0.17. Sem isso, os preços em tempo real não são usados. Se a moeda da sua loja for BRL, deixe vazio.
Preços fixos (para países fora do Brasil, sem credenciais de API e como alternativa quando a API não retorna preço)
Country prices: uma tabela de países com um preço Base e preços por peso do carrinho na moeda da sua loja: XS até 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL acima de 5 kg. Um preço de tamanho vazio ou zero usa o preço Base. Clique em Add country para adicionar uma linha e no X para remover uma. A linha * Default (all other countries) define os preços de todos os países sem linha própria. Um país sem linha (e sem *) não recebe preço fixo. Um preço base de 0 significa frete grátis para esse país.
Fixed price per: Order cobra o preço uma única vez. Item (price × quantity) multiplica pelo número de itens no carrinho. Isso se aplica apenas aos preços fixos. Os preços em tempo real são sempre calculados para o pacote inteiro.
Condições
Min cart weight (kg): oculta o método abaixo deste peso de carrinho. 0 significa sem limite.
Max cart weight (kg): oculta o método acima deste peso de carrinho. Padrão: 30. 0 significa sem limite. Pacotes PAC e SEDEX dos Correios podem pesar até 30 kg.
Minimum order amount: mostra o método somente quando o subtotal do carrinho atinge este valor. Deixe vazio para sempre mostrar.
Excluded shipping classes: oculta o método se algum item do carrinho tiver uma destas classes de envio do WooCommerce.
Free shipping: ativa o frete grátis a partir do valor abaixo.
Free shipping from: o subtotal do carrinho a partir do qual o frete é grátis. Nesse caso, nenhuma requisição é feita à API.
Disponibilidade sem zonas de envio
Ignore shipping zones: oferece o método para os países abaixo, qualquer que seja a zona correspondente.
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á ativo.
Avançado
Debug log: registra os cálculos de preço em WooCommerce > Status > Logs, origem vfd-correios. Erros da API são sempre registrados, mesmo com esta opção desativada. O usuário da API, o código de acesso, o cartão de postagem, o token e os CEPs dos clientes não são registrados.
Remove data on uninstall: quando ativo, excluir o plugin remove suas configurações, métodos das zonas e preços em cache. Desativar o plugin nunca apaga nada.
Como funciona na finalização da compra
Quando o cliente informa um endereço de entrega, o WooCommerce pede ao plugin um valor de frete. O plugin verifica primeiro as condições: peso do carrinho, valor mínimo do pedido e classes de envio excluídas. Se o frete grátis se aplicar, o cliente recebe um valor grátis e nenhuma requisição é enviada aos Correios.
Para um endereço no Brasil com credenciais configuradas, o plugin primeiro obtém um token da API para o seu cartão de postagem. O token também fornece os números do contrato e da agência regional, então o preço é o preço do seu contrato. Em seguida, solicita o preço do serviço escolhido pelo CEP de origem e de destino, o peso do pacote em gramas e o tamanho do pacote em cm. O preço só é solicitado quando o CEP de destino tem 8 dígitos. Quando todos os produtos têm dimensões, o tamanho do pacote é estimado a partir delas; caso contrário, é enviado o tamanho mínimo dos Correios. Pacotes acima de 30 kg não são enviados à API. O preço em BRL é convertido com a sua cotação. O serviço é salvo na linha de envio do pedido como Correios service e fica visível na administração do pedido.
Cada preço fica em cache por 1 hora por pacote. Uma requisição com falha fica em cache por 10 minutos, para que uma queda da API não deixe lenta cada atualização da finalização da compra. O token fica em cache até pouco antes de expirar e é renovado automaticamente; se os Correios o recusarem, um novo token é solicitado e a requisição de preço é repetida uma vez. O tempo limite da API é de 12 segundos.
Se a API não retornar preço, usa-se o preço fixo, ou o método fica oculto quando não há preço fixo. O cliente nunca vê os detalhes dos erros da API; eles vão para o log do WooCommerce.
O método funciona na finalização clássica e nos blocos de Carrinho e de Finalização de compra. É compatível com o WooCommerce High-Performance Order Storage (HPOS).
O plugin calcula apenas os valores de frete. Ele não obtém os preços internacionais dos Correios (Exporta Fácil, Packet), estimativas de prazo de entrega, etiquetas, pré-postagens, declarações ou rastreamento. Os clientes não podem escolher uma agência ou um escaninho dos Correios. Serviços adicionais (valor declarado, mão própria, aviso de recebimento) não são incluídos. Ele mostra um único serviço dos Correios por loja, e as cotações de moeda não são atualizadas automaticamente.
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 Correios. 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 informar 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 do domínio. Libere a vaga na sua conta da vibefox.net.
Sem uma chave ativa, os Correios não são exibidos para os clientes na finalização da compra. Administradores da loja conectados ainda os veem, marcados 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 exigem renovação. O status é verificado novamente, automaticamente, em segundo plano.
Solução de problemas
Os Correios não aparecem na finalização da 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á ativo e o país é permitido). Confira os limites de peso, Minimum order amount e Excluded shipping classes. Sem preço em tempo real, precisa existir um preço fixo para o país ou para *.
O método mostra um preço fixo em vez do preço dos Correios: abra WooCommerce > Status > Logs, origem vfd-correios. O erro dos Correios é registrado ali: código de acesso errado, serviço que não está no seu contrato, CEP não atendido, pacote acima de 30 kg ou acima dos limites de tamanho. Verifique também se o CEP de origem está preenchido e, se a moeda da loja não for BRL, a cotação em BRL. Ative o Debug log para ver cada cálculo.
A requisição do token falha: confira o usuário da API, o código de acesso, o cartão de postagem e o ambiente. Um código de acesso de homologação só funciona com Homologation ativado, e um código de produção só com essa opção desativada.
Os preços parecem desatualizados após uma mudança: salve a página de configurações. Isso limpa os preços em cache e o token da API.
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 para o 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 todos os dados. Para removê-lo, desative e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin são sempre removidos. Configurações, métodos das zonas e preços em cache são removidos somente se Remove data on uninstall estava ativo. Caso contrário, eles permanecem para uma reinstalação futura. Os pedidos nunca são alterados.
Correios é uma marca de seu respectivo titular. Este plugin não é afiliado nem endossado pelos Correios.