VibeFox CTT for WooCommerce — Ajuda
Requisitos
WordPress: 5.8 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.
PHP: 8.0 ou superior.
Conta de e-commerce da CTT (apenas para taxas em tempo real e pontos CTT): as taxas em tempo real e a entrega em ponto CTT usam a API de e-commerce da CTT. Você precisa de uma conta de e-commerce da CTT em enviosecommerce.ctt.pt (para clientes com contrato CTT Expresso, ou peça uma proposta à CTT). Na página de gerenciamento de chaves dessa conta, crie um par de chaves pública e privada. O App ID (X-APPID) é emitido pela CTT para a sua integração: peça ao seu contato de e-commerce da CTT. A CTT também decide quais funções da API (estimativa de custo, pontos CTT) o seu App ID pode usar. Por fim, você precisa do Carrier ID da CTT na sua conta. A página de configurações lista as transportadoras da sua conta depois que as chaves são salvas. Se você usa apenas a tabela de preços e a entrega em domicílio, não precisa de chaves de API.
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_ctt para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox CTT, 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 (pelo menos uma linha Portugal ou * Default). Opcionalmente, preencha as chaves de API da CTT e o Carrier ID e ative Live rates (veja Configuração).
6. Em WooCommerce > Settings > Shipping > Shipping zones, abra ou crie uma zona para Portugal e adicione VibeFox CTT. Nas configurações do método, escolha o título e o tipo de entrega. Ou ative Ignore shipping zones e escolha os países.
Configuração
Preços, chaves de API e condições ficam em uma única página: WooCommerce > Settings > Shipping > VibeFox CTT. Eles se aplicam a todas as zonas de entrega. Ao adicionar o método a uma zona, a janela da zona tem dois campos:
Title (zone): o nome desta opção na finalização de compra nesta zona. Deixe vazio para usar o Name global.
Delivery: To the customer's address (padrão) ou To a CTT point or parcel locker chosen at checkout. Um ponto CTT exige as chaves de API da CTT e o Carrier ID nas configurações globais. Adicione o método duas vezes a uma zona para oferecer, lado a lado, a entrega em domicílio e a entrega em ponto CTT.
Os avisos acima das configurações informam sobre um preço ausente para Portugal, chaves de API incompletas, um Carrier ID ausente, uma moeda da loja sem taxa de câmbio e uma falha de conexão com a API da CTT. Sempre que você salva as configurações, as respostas da CTT em cache são limpas.
Geral
Enable/Disable: ativa ou desativa o método em todas as zonas de uma vez.
Name: o nome do método de entrega exibido na finalização de compra, por exemplo "CTT Expresso". Padrão: CTT. Um Title de zona substitui esse nome.
Tax status: Taxable adiciona o imposto de entrega do WooCommerce (por exemplo, IVA) sobre o preço; None significa que o preço é final.
API de e-commerce da CTT (taxas em tempo real, pontos CTT) (opcional; sem chaves, a tabela de preços é usada)
Public key: a chave pública da página de gerenciamento de chaves da sua conta de e-commerce da CTT.
Private key: a chave secreta usada para assinar cada requisição (HMAC-SHA256). Ela nunca é enviada à CTT nem gravada no log.
App ID (X-APPID): a chave de aplicação emitida pela CTT para a sua integração.
Carrier ID: o ID da transportadora CTT na sua conta, usado para as taxas em tempo real e para a busca de pontos CTT. Depois que as chaves são salvas, as transportadoras da sua conta aparecem abaixo do campo, com as que oferecem suporte a pontos CTT marcadas.
Live rates: pede à CTT o preço (estimativa de custo) assim que o cliente informa a rua, o código postal e a cidade. A tabela de preços é usada enquanto o endereço estiver incompleto e sempre que a CTT não fornecer um preço. A CTT chama esse preço de estimativa. Padrão: desativado.
Service ID: opcional. Quando a CTT retorna vários serviços, usa-se o que tiver este ServiceId. Deixe vazio para usar o mais barato.
Exchange rate: os preços da CTT estão em euros. Se a moeda da sua loja for outra, informe quantas unidades da moeda da loja equivalem a 1 unidade da moeda da CTT. Sem isso, as taxas em tempo real em outra moeda não são usadas e vale a tabela de preços.
Default product size (cm): comprimento x largura x altura enviados à CTT para produtos sem dimensões. Padrão: 30x20x15. Produtos com dimensões usam as próprias. As dimensões são convertidas para cm e os pesos para gramas a partir das unidades da sua loja.
Preços (o título da seção mostra a moeda da sua loja)
Informe os preços do seu contrato com a CTT ou da tabela pública de preços da CTT, na moeda da loja. Com as taxas em tempo real desativadas, esta tabela define o preço. Com as taxas em tempo real ativadas, ela é a alternativa.
Price table: uma linha por destino. Escolha um país, Portugal - Azores (PT-AC), Portugal - Madeira (PT-MA) ou * Default (other destinations). Cada linha tem um preço base (Price) e preços opcionais para os tamanhos XS (até 1 kg), S (até 2 kg), M (até 3 kg), L (até 5 kg) e XL (acima de 5 kg). Um preço de tamanho vazio (ou 0) usa o preço base. Uma linha em que ambos estão vazios oculta o método. A linha dos Açores é usada para os códigos postais portugueses 9500-9999; a linha da Madeira (incluindo Porto Santo), para 9000-9499. Sem elas, vale a linha Portugal. Clique em + Add destination para adicionar uma linha e no X para remover uma. Os preços aceitam ponto ou vírgula decimal. Linhas inválidas são informadas ao salvar.
Calculation: como o preço da tabela é determinado.
Uma taxa em tempo real da CTT sempre vale para o envio inteiro.
Condições
Min weight (kg): o peso mínimo do carrinho para que o método apareça. 0 significa sem limite.
Max weight (kg): o método fica oculto acima deste peso do carrinho. Padrão: 30 (os pacotes da CTT vão até 30 kg). 0 significa sem limite.
Minimum order amount: exibe o método apenas quando o subtotal do carrinho (após descontos, antes dos impostos) atinge este valor. Deixe vazio para exibi-lo sempre.
Excluded shipping classes: oculta o método quando algum item do carrinho pertence a uma destas classes de entrega do WooCommerce.
Entrega grátis
Free shipping: ativa a entrega grátis pela CTT a partir do valor abaixo.
Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual este método custa 0. Aplica-se apenas onde o método tem preço. Usado somente quando Free shipping está ativo.
Disponibilidade sem zonas de entrega
Ignore shipping zones: oferece o método nos países abaixo quando a zona do cliente não o contém.
Countries: os países de destino para esse modo. Padrão: Portugal. Deixe vazio para usar todos os países para os quais você envia. Este campo só é usado quando Ignore shipping zones está ativo.
Avançado
Debug log: registra o cálculo dos preços e as chamadas à API da CTT em WooCommerce > Status > Logs, origem vfd-ctt. Erros da API da CTT são sempre registrados, mesmo quando esta opção está desativada. Chaves, tokens e endereços dos clientes nunca são registrados.
Remove data on uninstall: quando ativo, excluir o plugin remove as suas configurações e os métodos das zonas. Desativar o plugin nunca apaga dados. Os pedidos nunca são alterados.
Como funciona na finalização de compra
Quando o cliente informa um endereço de entrega, o WooCommerce pede um preço ao plugin. O plugin verifica primeiro o peso do carrinho, o valor mínimo do pedido e as classes de entrega excluídas. Com Live rates ativado e um endereço completo, ele envia à CTT o endereço de entrega e, para cada linha do carrinho, a quantidade, o peso em gramas e as dimensões em cm, e exibe o preço retornado. Caso contrário, ou quando a CTT não fornece um preço (erro da API, timeout, sem cobertura, função não ativada para o seu App ID), o preço vem da tabela. Se a entrega grátis se aplicar, o preço é 0.
Um preço da CTT fica em cache por 1 hora, para que o mesmo carrinho não gere uma nova requisição. Uma requisição com falha fica registrada por 5 minutos, para que a finalização de compra não espere pela CTT a cada atualização. O timeout da API é de 12 segundos.
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.
Com as chaves de API preenchidas, o plugin envia à CTT o endereço de entrega, os pesos e dimensões dos produtos e a URL da sua loja para obter um preço ou os pontos CTT mais próximos.
O plugin não cria envios, não imprime etiquetas, não solicita coletas, não fornece números de rastreamento nem exibe um mapa dos pontos CTT. Existem uma tabela de preços e um conjunto de configurações de API para a loja inteira. As zonas diferem pelo título e pelo tipo de entrega.
Pontos de coleta
Para um método de zona com Delivery definido como ponto CTT, aparecem na finalização de compra, abaixo do método, um campo de busca e uma lista. O endereço de entrega é pesquisado automaticamente. O cliente pode buscar outros pontos CTT por código postal ou cidade e precisa escolher um antes de fazer o pedido. Isso também é verificado no servidor. As listas de pontos CTT ficam em cache por 6 horas. Se a CTT não puder ser acessada, o cliente vê uma mensagem e pode tentar novamente mais tarde ou escolher outro método de entrega.
O ponto escolhido é salvo no pedido. Ele aparece na administração do pedido abaixo do endereço de entrega, na página de pedido recebido, em My account > Orders e nos e-mails de pedido (HTML e texto simples) como CTT point.
Na administração do pedido, clique em Change ao lado do ponto CTT, pesquise por código postal ou cidade e escolha outro ponto. A alteração é salva imediatamente e adiciona uma nota ao pedido.
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 CTT. 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 do domínio. Libere a vaga na sua conta da vibefox.net.
Sem uma chave ativa, a CTT não é exibida aos clientes na finalização de compra. Os 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 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 de forma automática em segundo plano.
Solução de problemas
A CTT 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). Verifique se o destino tem uma linha na tabela de preços (ou uma linha * Default), se o peso do carrinho está entre Min weight e Max weight, se o Minimum order amount foi atingido e se nenhum produto pertence a uma classe de entrega excluída.
O cliente não consegue escolher um ponto CTT: o seletor aparece apenas para um método de zona com Delivery definido como ponto CTT, e somente quando a chave pública, a chave privada, o App ID e o Carrier ID estão preenchidos. Ative o Debug log e verifique WooCommerce > Status > Logs.
As taxas em tempo real não aparecem: a tabela de preços é usada até que o cliente informe a rua, o código postal e a cidade. Verifique os avisos acima das configurações e o log. A resposta "405" significa que a função não está ativada para o seu App ID: peça à CTT. Em uma loja que não usa euro, preencha o Exchange rate.
A conexão com a API da CTT falhou: o aviso acima das configurações mostra o erro. Verifique as chaves e o App ID. O plugin tenta novamente automaticamente após alguns minutos.
Preços com ou sem IVA: com Tax status em Taxable, o WooCommerce adiciona o imposto de entrega sobre o preço. Com None, o preço é final.
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 e exclua-o na página Plugins. A chave de licença e o status da licença deste plugin são sempre removidos, assim como as respostas da CTT em cache e o token da API. As configurações e os métodos de zona só são removidos se Remove data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos, incluindo o ponto CTT escolhido, nunca são alterados, e os pedidos existentes mantêm suas linhas de entrega.
CTT é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela CTT.