VibeFox CTT for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a instalar em versões anteriores do PHP.
Conta de e-commerce da CTT (somente 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 à CTT uma proposta). 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 no endereço, 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 back office, vá em Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.
2. Quando o upload terminar, clique em Configure, ou encontre VibeFox CTT depois na lista de módulos e clique em Configure.
3. Informe sua chave de licença VibeFox em License key no bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Preencha a tabela de preços (pelo menos uma linha Portugal ou * Default) e clique em Save. Opcionalmente, preencha as chaves de API da CTT e o Carrier ID, e ative Live rates e Enable CTT point carrier (veja Configuração).
Na instalação, o módulo cria duas transportadoras. CTT (entrega no endereço do cliente, texto de prazo de entrega CTT delivery to your address) fica ativada. CTT point / parcel locker (texto de prazo de entrega Pickup at a CTT point or parcel locker) fica desativada até você ativá-la. Ambas estão vinculadas à zona de Portugal e a todos os grupos de clientes. Você pode alterar zonas, grupos de clientes, prazo de entrega, logotipo e limites de tamanho em Shipping > Carriers. Não defina preços ali: o preço sempre vem do módulo.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox CTT > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Os preços e as condições valem para as duas transportadoras da CTT. Cada salvamento limpa as respostas da CTT em cache, incluindo o token de API e as listas de pontos CTT.
Avisos acima das configurações informam sobre uma tabela de preços vazia, um preço ausente para Portugal, chaves de API incompletas, um Carrier ID ausente, uma moeda da loja diferente de EUR sem taxa de câmbio, uma falha de conexão com a API da CTT e uma transportadora da CTT excluída. Valores inválidos são informados ao salvar: um número inválido não é salvo, e um destino desconhecido ou uma linha duplicada na tabela de preços é removido. Se a unidade de peso ou de dimensão da sua loja não for reconhecida pelo módulo, um aviso pede que você defina as unidades em International > Localization (Local units).
Geral
Enable/Disable: ativa ou desativa a entrega da CTT no endereço do cliente. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Name: o nome da transportadora mostrado ao cliente na finalização de compra, por exemplo "CTT Expresso". Padrão: CTT. Obrigatório, até 64 caracteres.
Tax status: None significa que os preços são finais. Taxable com uma regra de imposto significa que a PrestaShop acrescenta esse imposto de entrega (por exemplo, IVA) sobre os preços. A escolha é salva para as duas transportadoras da CTT.
Entrega em ponto CTT ou armário automático
A segunda transportadora da CTT. O cliente pesquisa pontos CTT por código postal ou cidade e precisa escolher um antes de continuar. Ela precisa das chaves de API da CTT e do Carrier ID. Sem eles, é uma transportadora sem seleção de ponto.
Enable CTT point carrier: ativa ou desativa a transportadora de pontos CTT. É o mesmo interruptor do status dela em Shipping > Carriers. Padrão: desativada.
CTT point carrier name: o nome desta opção na finalização de compra. Padrão: CTT point / parcel locker. Obrigatório, até 64 caracteres.
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.
As duas chaves nunca são exibidas novamente após o salvamento. A descrição do campo então mostra Saved - leave empty to keep it. Digite um novo valor apenas para alterá-las. Marque Remove the saved public and private key e salve para excluir as duas.
App ID (X-APPID): a chave de aplicativo emitida pela CTT, enviada no cabeçalho X-APPID.
Carrier ID: o ID da transportadora da CTT na sua conta, usado para as taxas em tempo real e para a pesquisa de pontos CTT. Depois que as chaves e o App ID são salvos, as transportadoras da sua conta são listadas abaixo do campo, com as que oferecem suporte a pontos CTT marcadas com (CTT points). Somente números.
Live rates: o módulo 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, é usado aquele com este ServiceId. Deixe vazio para usar o mais barato.
Exchange rate: os preços da CTT são em euros. Se a moeda padrão 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 a tabela de preços se aplica.
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 suas. 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 padrão da sua loja)
Informe os preços do seu contrato com a CTT ou da tabela pública da CTT em ctt.pt, na moeda padrão da loja, sem impostos. 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 Price base 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 os dois campos estão vazios oculta a transportadora. A linha Azores é usada para os códigos postais portugueses 9500-9999, e a linha Madeira (incluindo Porto Santo) para 9000-9499. Sem elas, vale a linha Portugal. Clique em Add destination para adicionar uma linha e no ícone de lixeira para removê-la. Os preços aceitam ponto ou vírgula decimal. A tabela fica vazia após a instalação.
Calculation: como o preço da tabela é encontrado.
Uma taxa em tempo real da CTT é sempre para o envio inteiro.
Condições
Min weight (kg): o peso mínimo do carrinho para que as transportadoras apareçam. 0 significa sem limite.
Max weight (kg): as transportadoras ficam ocultas acima deste peso do carrinho. Padrão: 30 (os pacotes da CTT vão até 30 kg). 0 significa sem limite. Min weight (kg) não pode ser maior que Max weight (kg): as configurações não são salvas.
Minimum order amount: mostra as transportadoras somente quando o subtotal do carrinho (produtos que precisam de entrega, após descontos, antes do imposto) atinge este valor. Deixe vazio para exibi-las sempre.
Entrega grátis
Free shipping: ativa a entrega grátis da CTT a partir do valor abaixo.
Free shipping from: o subtotal do carrinho (após descontos, antes do imposto) a partir do qual as transportadoras custam 0. Aplica-se somente a destinos que têm preço. Usado apenas quando Free shipping está ativado.
Disponibilidade sem zonas de entrega
Normalmente, as transportadoras são oferecidas nas zonas de entrega às quais estão vinculadas em Shipping > Carriers.
Ignore shipping zones: oferece as transportadoras nos países abaixo sem vinculá-las à zona delas. Ao ativar, as duas transportadoras são vinculadas a todas as zonas ativas (também às zonas que você criar depois). Ao desativar, elas voltam às zonas que tinham antes.
Countries: os países de destino para esse modo. Padrão: Portugal. Deixe vazio para permitir todos os países. Usado apenas quando Ignore shipping zones está ativado. Os clientes nas zonas que as transportadoras tinham antes são sempre atendidos.
Avançado
Debug log: registra o cálculo de preços e as chamadas à API da CTT em logs/vfd_ctt_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros da API da CTT são sempre registrados, mesmo com esta opção desativada. Chaves, tokens e endereços de clientes nunca são registrados.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para limpá-lo.
Remove data on uninstall: quando ativado, desinstalar o módulo exclui as suas configurações e as suas transportadoras. Quando desativado, desinstalar apenas desativa as transportadoras. Pedidos, incluindo o ponto CTT escolhido, nunca são alterados.
Como funciona na finalização de compra
Na etapa de entrega, a PrestaShop pede ao módulo o preço de cada transportadora da CTT. Só produtos físicos contam: produtos virtuais não somam peso e não entram no valor do pedido. O módulo verifica primeiro Ignore shipping zones e os seus países, o peso do carrinho e o valor mínimo do pedido. 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 usa o preço retornado. Caso contrário, ou quando a CTT não retorna um preço (erro de API, tempo esgotado, sem cobertura, função não habilitada para o seu App ID), o preço vem da tabela. Se a entrega grátis se aplicar, o preço é 0. O preço é calculado na moeda padrão da loja e depois exibido na moeda do carrinho do cliente.
Um preço da CTT fica em cache por 1 hora, então o mesmo carrinho não gera uma nova requisição. Uma requisição com falha é lembrada por 5 minutos, para que a finalização de compra não espere pela CTT a cada atualização. O tempo limite da API é de 12 segundos. Erros da API nunca chegam ao cliente: usa-se o preço da tabela, ou a transportadora é ocultada se o destino não tiver preço.
Se você editar uma transportadora em Shipping > Carriers depois que ela tiver pedidos, a PrestaShop a salva como uma nova versão da transportadora. O módulo acompanha a nova versão automaticamente.
Com as chaves de API preenchidas, o módulo envia à CTT o endereço de entrega, os pesos e as dimensões dos produtos e a URL da sua loja para obter um preço ou os pontos CTT mais próximos.
O módulo 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. Há uma só tabela de preços e um só conjunto de configurações de API para as duas transportadoras.
Pontos de retirada
Quando o cliente seleciona a transportadora de pontos CTT, aparecem abaixo um campo de pesquisa e uma lista. O código postal do endereço de entrega é preenchido e pesquisado automaticamente. O cliente pode pesquisar outros pontos CTT por código postal ou cidade (botão Search ou Enter) e escolher um da lista. A escolha é salva no carrinho imediatamente. Só é aceito um ponto da lista da CTT para essa pesquisa.
Um ponto precisa ser escolhido antes que o cliente possa continuar. Quando o cliente clica em Continue na etapa de entrega, o módulo verifica o ponto novamente no servidor. Sem ponto, o cliente vê Please select a CTT point.; com um ponto que não está na lista da CTT, vê The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. As listas de pontos CTT ficam em cache por 6 horas. Se a CTT não puder ser acessada, o cliente vê CTT points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.
A seleção de ponto funciona com os temas Classic e Hummingbird. Ela só fica ativa quando a chave pública, a chave privada, o App ID e o Carrier ID estão preenchidos.
O ponto escolhido é salvo no pedido. Ele aparece na página do pedido na administração, no bloco CTT point (nome e ID), na página de confirmação do pedido, nos detalhes do pedido na conta do cliente e no e-mail de confirmação do pedido como CTT point: ao lado do nome da transportadora. O novo e-mail de pedido do módulo Mail alerts também mostra o ID do ponto.
Na página do pedido na administração, informe um código postal ou uma cidade em Change CTT point, clique em Search, escolha um ponto e clique em Save. A página mostra CTT point updated. e é adicionada uma mensagem privada do pedido CTT point changed to: com o novo ponto. Alterar o ponto exige permissão para editar pedidos.
Chave de licença
O módulo funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox CTT é o primeiro bloco da página Modules > Module Manager > VibeFox CTT > Configure, acima das configurações. Informe a chave em License key e clique em Activate. Depois disso, o bloco mostra a chave mascarada, o status (por exemplo, a data até a qual a licença está ativa e o seu domínio) e os botões Check now para verificar o status novamente, Change key para informar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-shipping-ctt e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente funcionários com a permissão Configure do módulo podem alterar a chave. Os textos do bloco seguem o idioma do back office (inglês e russo estão incluídos).
Se a chave não for aceita, o bloco informa o motivo, por exemplo Key not found, This key belongs to another product, Domain limit reached ou License expired on com uma data. Depois que o endereço da loja mudar, ou depois que você liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, o módulo continua funcionando com o último status conhecido.
Uma chave funciona em um domínio: o domínio da loja principal, também em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio dela. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, nenhuma das duas transportadoras da CTT (entrega no endereço ou em ponto CTT) é exibida aos clientes na finalização de compra, e nenhuma taxa é calculada. A loja PrestaShop não sabe que você está conectado ao back office, então as transportadoras também ficam ocultas para você: é possível configurar o módulo antes de comprar uma chave, mas não testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Pedidos existentes não são afetados.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A CTT não aparece na finalização de compra: verifique se a licença está ativa e se Enable/Disable (ou Enable CTT point carrier) está ativado. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo 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á dentro de Min weight e Max weight e se o Minimum order amount foi atingido. Produtos também podem ser limitados a determinadas transportadoras na página do produto.
O cliente não consegue escolher um ponto CTT: o seletor aparece somente abaixo da transportadora de pontos CTT, e somente quando a chave pública, a chave privada, o App ID e o Carrier ID estão preenchidos. Verifique os avisos acima das configurações, ative o Debug log e veja o campo Log na página do módulo.
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á habilitada 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 módulo tenta novamente automaticamente após alguns minutos.
Preços com ou sem IVA: com Tax status em uma regra Taxable, a PrestaShop acrescenta o imposto de entrega ao preço. Com None, o preço é final.
Os preços parecem desatualizados após uma alteração: clique em Save na página do módulo. Isso limpa as respostas da CTT em cache.
A página diz que uma transportadora da CTT não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente. A redefinição mantém as configurações e o status ativado/desativado das duas transportadoras.
Para desenvolvedores: o endereço da API da CTT pode ser alterado com a chave de configuração vfd_ctt_API_URL.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox CTT e escolha Uninstall. A chave de licença, o status da licença, as respostas da CTT em cache e o token de API são sempre removidos. Se Remove data on uninstall estiver ativado, as duas transportadoras são excluídas (os pedidos mantêm o histórico), e as configurações, o log e os pontos CTT de carrinhos que nunca se tornaram pedidos são removidos. Se estiver desativado, as transportadoras são apenas desativadas e todas as configurações são mantidas. Instalar o módulo novamente devolve a cada transportadora o status ativado/desativado que ela tinha. Pontos CTT salvos em pedidos são sempre mantidos.
CTT é uma marca comercial do respectivo proprietário. Este módulo não é afiliado à CTT nem endossado por ela.