VibeFox CTT for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e posteriores (testado na 4.1.0.3).

PHP: 8.0 ou superior.

Conta de e-commerce da CTT (somente para tarifas em tempo real e pontos CTT): as tarifas em tempo real e a entrega em um 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 gestão 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 assim que as chaves forem salvas. Se você usar 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

O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3 vfd_ctt-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_ctt.ocmod.zip. Instale apenas o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_ctt-oc3-(version).ocmod.zip. A extensão não adiciona modificações OCMOD, então você não precisa atualizar Extensions > Modifications. Em vez do Installer, você pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox CTT e clique em Install (o botão verde +).

3. Clique em Edit (o botão com lápis) para abrir a página de configurações.

4. Informe sua chave de licença VibeFox em License key, no bloco de licença no topo da página Edit, e clique em Activate (veja Chave de licença).

5. Preencha a tabela de preços (pelo menos uma linha Portugal ou * Default), ative Enable/Disable e/ou Enable CTT point option e clique em Save. Opcionalmente, preencha as chaves de API da CTT, o App ID e o Carrier ID e ative Live rates (veja Configuração).

OpenCart 4

1. No administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_ctt.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão pelo nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas, na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox CTT, clique em Install (o botão verde +) e depois em Edit (o botão com lápis).

4. Informe a chave de licença e as configurações como nos passos 4 e 5 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões.

Após a primeira instalação, as duas opções de envio ficam desativadas até que você ative uma e salve. Se você instalar a extensão novamente após uma desinstalação sem remover os dados, as configurações mantidas são usadas novamente e a extensão é reativada se uma das opções estava ativa.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Shipping > VibeFox CTT > Edit. As seções são listadas à esquerda. Um botão Save no final salva a página inteira sem recarregá-la. Os preços e as condições se aplicam às duas opções da CTT. Cada salvamento limpa as respostas da CTT em cache: o token da API, as transportadoras, os preços e as listas de pontos da CTT. Somente usuários administradores com a permissão de modificação para esta extensão podem salvar as configurações.

Avisos no topo da página informam sobre uma tabela de preços vazia, um preço ausente para Portugal, chaves de API incompletas enquanto as tarifas em tempo real ou a opção de ponto CTT estiverem ativas, 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 loja sem uma classe de peso com a unidade kg ou uma classe de comprimento com a unidade cm (as unidades dos produtos são então convertidas pelo nome da unidade; verifique System > Localisation > Weight Classes e Length Classes). Se um nome estiver vazio, for inválido ou tiver mais de 64 caracteres, se Min weight (kg) for maior que Max weight (kg), ou se Sort Order, a classe de imposto ou a zona geográfica forem inválidos, a página mostra um erro e nada é salvo. Outros valores inválidos são informados como avisos e o restante é salvo: um número inválido não é salvo, uma taxa de câmbio igual ou menor que 0 é limpa, um tamanho de produto inválido volta ao padrão, um destino desconhecido ou uma linha duplicada na tabela de preços é removido, um preço inválido da tabela fica vazio.

Geral

A extensão oferece até duas opções na finalização de compra: entrega pela CTT no endereço do cliente e entrega em um ponto CTT ou armário automático. Os preços e as condições se aplicam às duas.

Enable/Disable: ativa ou desativa a entrega pela CTT no endereço do cliente.

Name: o nome do método de envio exibido ao cliente na finalização de compra, por exemplo "CTT Expresso". Padrão: CTT. Até 64 caracteres.

Tax class: a classe de imposto do custo de envio. O OpenCart adiciona esse imposto (por exemplo, IVA) sobre os preços. --- None --- significa que os preços são finais. Usado pelas duas opções.

Sort Order: a posição da CTT entre os métodos de envio na finalização de compra. Um número inteiro.

Entrega em um ponto CTT ou armário automático

A segunda opção da CTT. O cliente pesquisa pontos da CTT por código postal ou cidade (o endereço de entrega é pesquisado automaticamente) e precisa escolher um antes de continuar. Ela exige as chaves de API da CTT e o Carrier ID. Sem eles, é uma opção sem seleção de ponto.

Enable CTT point option: oferece a entrega em um ponto CTT ou armário automático. Padrão: desativado.

CTT point option name: o nome desta opção na finalização de compra. Padrão: CTT point / parcel locker. Até 64 caracteres.

API de e-commerce da CTT (tarifas em tempo real, pontos CTT) (opcional; sem as chaves, a tabela de preços é usada)

Public key: a chave pública da página de gestão 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.

Ambas as chaves nunca são exibidas novamente após o salvamento. A descrição do campo então diz Saved - leave empty to keep it. Digite um novo valor apenas para alterá-lo. Marque Remove the saved public and private key e salve para excluir as duas. Quando nada está salvo, a seção mostra No keys saved.

App ID (X-APPID): a chave do aplicativo emitida pela CTT, enviada no cabeçalho X-APPID.

Carrier ID: o ID da transportadora CTT na sua conta, usado para as tarifas em tempo real e a pesquisa de pontos CTT. Depois que as chaves e o App ID forem salvos, as transportadoras da sua conta são listadas abaixo do campo (Carriers of your CTT account:), com as que aceitam pontos CTT marcadas como CTT points. Somente números.

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, é usado aquele com este ServiceId. Deixe vazio para usar o mais barato.

Exchange rate: os preços da CTT estão em euros. Se a moeda padrão da sua loja for diferente, informe quantas unidades da moeda da loja equivalem a 1 unidade da moeda da CTT. Sem esse valor, as tarifas em tempo real em outra moeda não são usadas e a tabela de preços é aplicada.

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 classes de comprimento e peso dos produtos.

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 lista pública de preços da CTT em ctt.pt, na moeda padrão da loja, sem impostos. Com as tarifas em tempo real desativadas, esta tabela define o preço. Com elas ativadas, ela é o valor de reserva.

Price table: uma linha por destino. Escolha um país, Portugal - Azores, Portugal - Madeira 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 ambos estão vazios oculta o método. A linha Azores é usada para os códigos postais portugueses 9500-9999, a linha Madeira para 9000-9499. Sem elas, vale a linha Portugal. Clique em Add destination para adicionar uma linha e no botão × para removê-la. Os preços aceitam ponto ou vírgula como separador decimal. A tabela fica vazia após a instalação.

Calculation: como o preço da tabela é determinado.

Um preço em tempo real da CTT é sempre para o envio inteiro.

Condições

Min weight (kg): o peso mínimo do carrinho para que as opções da CTT apareçam. 0 significa sem limite.

Max weight (kg): as opções da CTT 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).

Minimum order amount: exibe as opções da CTT somente quando o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) atingir este valor. Deixe vazio para exibi-las sempre.

Frete grátis

Free shipping: ativa a entrega grátis pela CTT a partir do valor indicado abaixo.

Free shipping from: o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) a partir do qual as opções da CTT custam 0. Aplica-se somente aos destinos que têm preço. Usado apenas quando Free shipping está ativado.

Disponibilidade

Normalmente as opções da CTT são oferecidas na zona geográfica selecionada abaixo. All Zones significa em todos os lugares. Com Ignore shipping zones, a zona geográfica não é verificada e quem decide é Countries.

Geo Zone: a zona geográfica do endereço de envio. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.

Ignore shipping zones: não verificar a zona geográfica; oferecer a CTT nos países abaixo.

Countries: os países de destino para esse modo. Padrão: Portugal. Deixe vazio para permitir todos os países. Usado somente com Ignore shipping zones.

Avançado

Debug log: registra o cálculo dos preços e as chamadas à API da CTT em storage/logs/vfd_ctt_debug.log.php (no OpenCart 4, system/storage/logs/vfd_ctt_debug.log.php). O arquivo não pode ser lido pela web. Erros da API da CTT são sempre registrados, mesmo quando esta opção está desativada. Chaves, tokens e endereços de clientes nunca são registrados. Quando o arquivo chega a 5 MB, ele é movido para vfd_ctt_debug.old.log.php e um novo log é iniciado.

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 a extensão exclui as configurações, o log e os pontos CTT das finalizações de compra não concluídas. Quando desativado (padrão), as configurações são mantidas para uma nova instalação. Pedidos, incluindo o ponto CTT escolhido, nunca são alterados.

Importar / Exportar

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. As chaves pública e privada não são exportadas.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações, por exemplo em outra loja. Os valores são verificados como em um salvamento normal. As chaves salvas são mantidas.

Como funciona na finalização de compra

Quando o OpenCart exibe os métodos de envio, ele pede à extensão o preço da CTT. Com Ignore shipping zones, a CTT é oferecida somente para um país de Countries (vazio = todos os países); caso contrário, se uma Geo Zone estiver definida, somente para endereços dentro dela. Somente produtos com Requires Shipping definido como Yes contam: os demais não somam peso e não entram no valor do pedido. A extensão verifica o peso do carrinho e o valor mínimo do pedido. Com Live rates ativado e um endereço completo, ela envia à CTT o endereço de entrega e, para cada item 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 fornece um preço (erro de API, tempo esgotado, sem cobertura, uma função não habilitada para o seu App ID), o preço vem da tabela. Se o frete grátis se aplicar, o preço é 0. As duas opções recebem o mesmo preço. O preço é calculado na moeda padrão da loja, arredondado conforme as casas decimais dela e exibido ao cliente na moeda dele com o imposto da Tax class selecionada.

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 é lembrada por 5 minutos, para que a finalização de compra não espere pela CTT a cada atualização. O token da API, a lista de transportadoras e as listas de pontos da CTT também ficam em cache, no máximo pelo tempo de vida do cache do OpenCart (1 hora por padrão). Erros da API nunca chegam ao cliente: usa-se o preço da tabela, ou o método é ocultado se o destino não tiver preço.

Com as chaves de API preenchidas, a extensão 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 da CTT mais próximos.

A extensão não cria envios, não imprime etiquetas, não solicita coletas, não fornece números de rastreio nem mostra um mapa dos pontos CTT. Há uma só tabela de preços e um só conjunto de configurações de API para as duas opções.

No OpenCart 4, o cliente clica em Choose no bloco do método de envio na página de finalização de compra e escolhe uma opção da CTT na janela Shipping method options. Os preços são os mesmos do OpenCart 3.

Pontos de retirada

Quando o cliente seleciona a opção de ponto CTT na etapa do método de entrega, um campo de pesquisa e uma lista aparecem logo abaixo. O código postal do endereço de entrega é preenchido e pesquisado automaticamente. O cliente pode pesquisar outros pontos da CTT por código postal ou cidade (botão Search) e escolher um na lista. A escolha é salva imediatamente. Somente um ponto da lista da CTT para aquela pesquisa é aceito.

Um ponto precisa ser escolhido antes que o cliente possa continuar. Quando o cliente clica em Continue, a extensão verifica o ponto no servidor. Sem um ponto, o cliente vê Please select a CTT point.; com um ponto que não está na lista da CTT, The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. 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 fica ativa somente quando a chave pública, a chave privada, o App ID e o Carrier ID estão preenchidos. Ela foi feita para o tema padrão do OpenCart e a sua finalização de compra; outros temas podem precisar de ajustes.

No OpenCart 4, o campo de pesquisa e a lista aparecem na janela Shipping method options, abaixo da opção de ponto CTT. O botão Continue da janela não avança sem um ponto válido, com as mesmas mensagens. O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza sempre que o cliente confirma de novo, e o ponto CTT do pedido é atualizado junto.

O ponto escolhido é adicionado ao método de envio do pedido, por exemplo CTT point / parcel locker: .... Assim, o cliente o vê no histórico de pedidos da conta dele e nos e-mails do pedido, ele é impresso na fatura e aparece em Sales > Orders. A página de sucesso do pedido do OpenCart não mostra o método de envio.

Na página do pedido no administrativo, o painel CTT point acima do histórico mostra o nome e o ID do ponto. Para alterá-lo, digite 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., o texto do método de envio do pedido é atualizado e uma entrada CTT point changed to: ... é adicionada ao histórico sem notificar o cliente. Alterar o ponto exige a permissão de modificação de pedidos (sale/order) e as configurações de API. O painel também aparece para pedidos da CTT enquanto a extensão estiver desativada.

Chave de licença

A extensão funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox CTT é o primeiro bloco na página Extensions > Extensions > Shipping > VibeFox CTT > Edit, 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: opencart-shipping-ctt e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente usuários administradores com a permissão de modificação para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do administrativo (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 seguido de uma data. Depois que o endereço da loja mudar ou que você liberar um slot de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o endereço da loja nas configurações do OpenCart. Remover a chave da loja não libera o slot do domínio. Libere o slot na sua conta vibefox.net.

Sem uma chave ativa, a CTT não é exibida aos clientes na finalização de compra e nenhuma tarifa é calculada. Um usuário administrador conectado ao administrativo no mesmo navegador ainda vê o método na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 essa visualização não está disponível: a loja não enxerga o login do administrativo, então sem uma chave ativa o método fica oculto para todos. Depois que você abrir a página Edit uma vez, um lembrete aparece no Dashboard do administrativo. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem a renovação. O status é verificado de novo automaticamente quando você abre o Dashboard ou a página Edit do administrativo: 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 a extensão 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 option) está ativado. Verifique Geo Zone, ou Ignore shipping zones e Countries. Confira 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 os produtos têm Requires Shipping definido como Yes.

O cliente não consegue escolher um ponto da CTT: o seletor aparece somente abaixo da opção de ponto CTT, e somente quando a chave pública, a chave privada, o App ID e o Carrier ID estão preenchidos. Verifique os avisos no topo da página de configurações, ative o Debug log e veja o campo Log na página da extensão.

As tarifas 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 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 no topo da página de configurações mostra o erro. Verifique as chaves e o App ID. A extensão tenta novamente automaticamente após alguns minutos.

Preços com ou sem IVA: com uma Tax class selecionada, o OpenCart adiciona esse imposto sobre o preço. Com --- None ---, o preço é final.

Os preços parecem desatualizados após uma alteração: clique em Save na página da extensão. Isso limpa as respostas da CTT em cache.

A página diz "Warning: You do not have permission to modify VibeFox CTT!": o seu grupo de usuários administradores pode apenas visualizar as configurações. Conceda ao grupo a permissão de modificação para extension/shipping/vfd_ctt (OpenCart 3) ou extension/vfd_ctt/shipping/vfd_ctt (OpenCart 4) em System > Users > User Groups.

Para desenvolvedores: o endereço da API da CTT pode ser substituído pela configuração vfd_ctt_api_url (para testes); ela não tem campo na página de configurações.

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox CTT. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine o status da extensão, Sort Order, Tax class e Geo Zone. As respostas da CTT em cache e o token da API são sempre removidos. Se Remove data on uninstall estiver ativado, as configurações, o log e os pontos CTT das finalizações de compra que nunca viraram pedidos também são removidos. Se estiver desativado, as demais configurações são mantidas e usadas novamente quando a extensão for reinstalada. Os pontos CTT salvos nos pedidos são sempre mantidos, e os pedidos existentes conservam o método e o custo de envio.

No OpenCart 4, para remover também os arquivos da extensão, vá em Extensions > Installer depois da desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox CTT na lista de extensões instaladas, depois em Delete (o botão vermelho com lixeira) para remover o pacote enviado.

A CTT é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada à CTT nem endossada por ela.