VibeFox The Courier Guy for OpenCart — Ajuda

Requisitos

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

PHP: 8.0 ou superior.

Chave de API do ShipLogic (para tarifas em tempo real e lockers): a The Courier Guy opera na plataforma ShipLogic. Crie uma chave de API no seu portal de courier da The Courier Guy em Settings > API Keys (conta empresarial). Sem a chave, apenas a tabela de preços é usada e a opção de locker não é oferecida.

Envio para a África do Sul: as tarifas em tempo real e os lockers são apenas para endereços sul-africanos. A África do Sul precisa ser um país habilitado na loja (System > Localisation > Countries), e a tarifa de courier em tempo real precisa das províncias sul-africanas (zonas), que o OpenCart 3 já possui.

Chave de licença VibeFox: adquirida em vibefox.net. Uma chave funciona em um único 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 README.txt, o pacote do OpenCart 3 vfd_the_courier_guy-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_the_courier_guy.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, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_the_courier_guy-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 do pacote para a pasta raiz da sua loja.

2. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox The Courier Guy e clique em Install (o botão verde +).

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

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

5. Ative Courier to the door e/ou TCG locker e informe a API key do ShipLogic. Para tarifas em tempo real, preencha o endereço do remetente (rua, cidade, província, CEP) e, se a moeda da sua loja não for o ZAR, a ZAR conversion rate.

6. Preencha a tabela de preços e/ou um custo de contingência e clique em Save.

OpenCart 4

1. No administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_the_courier_guy.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão do 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. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox The Courier Guy, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).

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

Após a instalação, as duas opções ficam desativadas até que você ative uma delas e salve. A extensão fica ativa enquanto pelo menos uma das duas opções estiver ligada. Se você reinstalar a extensão depois de uma desinstalação, as configurações mantidas voltam a ser usadas.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Shipping > VibeFox The Courier Guy > Edit. As seções ficam listadas à esquerda. Um botão Save no final salva a página inteira sem recarregá-la. Cada salvamento limpa as tarifas e os lockers em cache e o último erro do ShipLogic. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações.

Se um nome de opção, a classe de imposto, a ordem de exibição ou a zona geográfica não forem válidos, nada é salvo e a página mostra o motivo, por exemplo Enter a valid option name (1-64 characters, without < > ; = # { }). Um número inválido (por exemplo, negativo) não é salvo: a página indica o campo e mantém o valor anterior, e o restante é salvo. Enquanto pelo menos uma opção estiver ativa, os avisos no topo da página informam quando a África do Sul não é um país habilitado, quando a chave de API está ausente, quando faltam a taxa de conversão para ZAR ou o endereço do remetente, quando não há tabela de preços nem custo de contingência, quando a África do Sul não tem zonas (províncias) ou quando a última requisição ao ShipLogic falhou (com data e erro). Um aviso também aparece quando a loja não tem uma classe de peso com a unidade kg nem uma classe de comprimento com a unidade cm.

Geral

Cada tipo de entrega é uma opção própria na finalização de compra.

Courier to the door: oferece entrega por courier da The Courier Guy até o endereço do cliente. Padrão: desativado.

Courier option name: o nome da opção de courier na finalização de compra. Padrão: The Courier Guy. Obrigatório, no máximo 64 caracteres, sem < > ; = # { }.

TCG locker: o cliente escolhe um locker na finalização de compra. É oferecido somente para endereços sul-africanos e somente com a chave de API do ShipLogic. Padrão: desativado.

Locker option name: o nome da opção de locker na finalização de compra. Padrão: The Courier Guy locker. Mesmas regras do nome do courier.

Tax status: a classe de imposto das duas opções. Com uma classe de imposto, as tarifas em tempo real são usadas sem IVA e o OpenCart soma o imposto da classe. None (live rates including VAT) (padrão): as tarifas em tempo real são usadas com IVA incluído.

Sort order: a posição entre os métodos de entrega na finalização de compra. Um número inteiro.

API do ShipLogic

API key: a sua chave de API do ShipLogic no portal da The Courier Guy. Ela nunca é mostrada aos clientes nem gravada no log. Depois de salvar, o campo fica vazio e mostra Saved - leave empty to keep it. Digite um valor novo somente se quiser alterá-la. Marque Remove the saved API key e salve para removê-la.

Account ID: opcional. O ID numérico da conta no ShipLogic, somente se a sua chave tiver acesso a várias contas. Um valor que não seja numérico não é salvo.

Tarifas em tempo real (para endereços sul-africanos; se nenhuma tarifa em tempo real estiver disponível, a tabela de preços é usada)

A tarifa em tempo real é o serviço mais barato do ShipLogic do endereço do remetente até o endereço do cliente (courier) ou até o locker mais próximo da cidade do cliente (locker). Ela exige a chave de API, o endereço do remetente e, para lojas que não operam em rands, uma taxa de conversão.

Price source: de onde vem o preço.

ZAR conversion rate: o ShipLogic cota em rands sul-africanos (ZAR). Se a moeda padrão da sua loja não for o ZAR, informe quanto vale 1 ZAR na sua moeda, por exemplo 0.05. Deve ser maior que 0. Sem ela, as tarifas em tempo real não são usadas e a tabela de preços é aplicada. Se a moeda da sua loja for o ZAR, deixe o campo vazio. A taxa não é atualizada automaticamente.

Endereço do remetente (de onde a The Courier Guy coleta os pacotes, na África do Sul)

O endereço da loja no OpenCart é um texto livre, por isso o endereço do remetente é informado aqui. Rua, cidade, província e CEP são necessários para as tarifas em tempo real.

Sender company: o nome da sua empresa.

Sender street address: por exemplo 12 My Road.

Sender suburb: o bairro do endereço do remetente.

Sender city: a cidade do endereço do remetente.

Sender province: escolha uma das 9 províncias sul-africanas na lista.

Sender postal code: o CEP do endereço do remetente.

Tabela de preços (seus próprios preços na moeda padrão da loja, sem impostos: usada com Price table only, fora da África do Sul e sempre que não houver tarifa em tempo real; aceita vírgula ou ponto decimal)

Calculation type: aplica-se somente à tabela de preços. Uma tarifa em tempo real é sempre para o pedido inteiro.

Prices by weight: uma tabela de países com uma coluna Price e as faixas de peso XS (até 1 kg), S (até 2 kg), M (até 3 kg), L (até 5 kg) e XL (acima de 5 kg). Clique em Add row para adicionar uma linha (uma nova linha começa com a África do Sul) e no botão de remover para excluir uma. Uma faixa vazia ou igual a 0 usa a coluna Price. Um preço de 0 significa frete grátis. A linha * Any country se aplica a países sem linha própria e a uma linha de país sem nenhum preço. Um preço que não seja numérico é apagado, e a página o informa.

Fallback cost: usado quando não há tarifa em tempo real nem preço na tabela. Deixe o campo vazio para ocultar as opções nesse caso.

Condições (ambas as opções)

Min weight (kg): oculta as opções abaixo deste peso do carrinho. 0 significa sem limite (padrão).

Max weight (kg): oculta as opções acima deste peso do carrinho. Padrão: 30. 0 significa sem limite, vazio significa 30 kg. Se Min weight (kg) for maior que Max weight (kg), a página mostra um aviso e os dois limites mantêm os valores anteriores.

Minimum order amount: mostra as opções somente a partir deste subtotal do carrinho (produtos que precisam de entrega, sem impostos, após descontos). Deixe vazio para sempre mostrá-las.

Free shipping from: o subtotal do carrinho a partir do qual a entrega é gratuita. Deixe vazio para nunca oferecer frete grátis. Quando o subtotal chega a esse valor, as opções aparecem com preço 0 e nenhuma requisição é enviada ao ShipLogic para a tarifa.

Disponibilidade

Geo zone: oferece as opções somente para endereços desta zona geográfica. All zones (padrão) significa qualquer endereço. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.

Ignore shipping zones: para o tipo de entrega abaixo, a zona geográfica não é verificada. Em vez disso, a opção é oferecida nos países listados abaixo.

Delivery type without zones: Courier to the door (padrão) ou TCG locker (customer chooses a locker). Usado somente com Ignore shipping zones. O outro tipo continua seguindo a Geo zone.

Countries: os países de destino para esse modo. Usado somente com Ignore shipping zones. Deixe vazio para permitir todos os países. Os lockers são oferecidos somente na África do Sul.

Avançado

Debug log: grava mensagens de depuração em storage/logs/vfd_tcgr_debug.log.php. O arquivo não pode ser lido pela web. Erros da API são sempre registrados, mesmo com esta opção desativada. A chave de API e os dados dos clientes nunca são registrados. Quando o arquivo chega a 5 MB, um novo log é iniciado.

Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.

Remove data on uninstall: quando ativada, desinstalar a extensão apaga as configurações, o log e as escolhas de locker das finalizações de compra sem pedido. Tarifas e lockers em cache são sempre removidos. Lockers e referências de rastreamento salvos nos pedidos são sempre mantidos.

Importar / Exportar

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A chave de API não é exportada.

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. A chave de API salva é mantida.

Como funciona na finalização de compra

Quando o OpenCart mostra os métodos de entrega, ele pede à extensão o preço de cada opção. A opção precisa atender à Geo zone (ou, com Ignore shipping zones, à lista de países). Somente produtos com Requires Shipping definido como Yes são considerados: os demais não adicionam peso e não entram no valor do pedido. Em seguida, a extensão verifica as condições: peso do carrinho e valor mínimo do pedido. O valor do pedido é o preço dos produtos que precisam de entrega, antes dos impostos e depois do desconto do cupom. Se o frete grátis se aplicar, o preço é 0.

Courier to the door: a extensão pede ao ShipLogic o serviço mais barato do endereço do remetente até o endereço do cliente. O endereço precisa ter rua, cidade, província e CEP. Até lá, a tabela de preços é usada.

TCG locker: a tarifa em tempo real é o serviço porta a locker mais barato até o locker mais próximo da cidade do cliente. Ela não é recalculada para o locker escolhido pelo cliente. A opção de locker aparece somente para endereços sul-africanos e somente com a chave de API.

O pedido inteiro é cotado como um único pacote: o peso total, o maior comprimento e a maior largura, e as alturas empilhadas. Produtos sem dimensões contam como cubos de 10 cm. Pesos e dimensões são convertidos a partir das classes de peso e de comprimento dos produtos. O valor em rands é convertido para a moeda padrão da loja, arredondado conforme as casas decimais dela e mostrado ao cliente em sua moeda, com o imposto da classe de imposto selecionada.

As requisições ao ShipLogic expiram após 12 segundos. As tarifas ficam em cache por 1 hora, os lockers por 6 horas e as falhas por 10 minutos, para que uma API lenta não atrase cada atualização da finalização de compra. Se não houver tarifa em tempo real, o preço vem da tabela e, depois, de Fallback cost. Se nenhum dos dois se aplicar, a opção fica oculta. Erros da API nunca são mostrados ao cliente.

A extensão não agenda envios, não gera conhecimentos de transporte ou etiquetas e não atualiza o rastreamento automaticamente. Não há mapa de lockers: eles são escolhidos em uma lista. As tarifas em tempo real e os lockers são somente para a África do Sul. Outros países usam a tabela de preços. Apenas uma tarifa por opção (o nível de serviço mais barato) é mostrada, sem escolha de níveis de serviço, seguro ou extras na finalização de compra.

No OpenCart 4, o cliente clica em Choose no bloco do método de entrega da finalização de compra e escolhe a opção de courier ou de locker na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.

Pontos de retirada

Quando o cliente escolhe a opção de locker na etapa do método de entrega, aparece abaixo um seletor de lockers: um campo de busca (por padrão, a cidade do endereço de entrega) e uma lista de lockers com nome, endereço e horário de funcionamento. O cliente pode digitar outra cidade, bairro ou CEP e clicar em Search. Um locker precisa ser escolhido antes de o cliente continuar; caso contrário, a etapa mostra Please choose a The Courier Guy locker.

O locker é verificado no servidor com a lista do ShipLogic quando o cliente continua e novamente quando o pedido é feito. Nome e fornecedor vêm do ShipLogic, nunca do navegador. A escolha pertence ao país e à cidade ou CEP do endereço: se o endereço de entrega mudar, o cliente escolhe novamente.

Se o ShipLogic não puder ser acessado, o seletor mostra Lockers cannot be loaded right now. You can place the order without choosing one - the store will contact you about the locker. O pedido pode então ser feito sem locker. Ele fica sinalizado na página do pedido no administrativo: Not chosen - ShipLogic was unavailable at checkout. Agree the locker with the customer.

No OpenCart 4, o seletor de lockers aparece na janela Shipping method options, abaixo da opção de locker, e é carregado de novo sempre que a janela é aberta, porque o endereço pode mudar na finalização de compra em uma única página. O botão Continue da janela não avança sem um locker da lista, com a mesma mensagem, e um ShipLogic indisponível também não bloqueia o pedido. O OpenCart 4 mantém um pedido para a finalização de compra e o atualiza cada vez que o cliente confirma de novo, e o locker do pedido é atualizado junto.

Pedidos

O locker escolhido é adicionado ao método de entrega do pedido, por exemplo "The Courier Guy locker: nome — endereço". Esse texto aparece em Sales > Orders, na página do pedido do cliente, na nota fiscal e nos e-mails de pedido.

A página do pedido em Sales > Orders tem um painel The Courier Guy acima do histórico para cada pedido enviado com a The Courier Guy. Para um pedido com locker, ele mostra o nome, o ID e o fornecedor do locker, com not verified (ShipLogic was unavailable at checkout) quando o locker não pôde ser verificado, ou a mensagem Not chosen quando o ShipLogic estava indisponível. O painel aparece mesmo com a extensão desativada.

The Courier Guy tracking reference: registre o pacote no seu portal da The Courier Guy, informe a referência neste campo do painel e clique em Save. Esvazie o campo e salve para removê-la. Usuários administradores sem permissão para modificar pedidos veem a referência somente para leitura. O cliente vê a referência na página do pedido da conta dele (clientes cadastrados) e nos e-mails de status do pedido quando você notifica o cliente. O e-mail de novo pedido não tem a referência, porque ela é informada depois.

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 The Courier Guy é o primeiro bloco de Extensions > Extensions > Shipping > VibeFox The Courier Guy > Edit, acima das configurações. Cole 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 de novo, Change key para informar outra chave e Remove key para remover a chave desta loja. Abaixo ficam a linha Product: opencart-shipping-the-courier-guy 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 Modify 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 com uma data. Depois de alterar o endereço da loja, ou depois de liberar um espaço 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 único domínio: o endereço da loja na configuração do OpenCart. Remover a chave da loja não libera o seu espaço de domínio. Libere-o na sua conta vibefox.net.

Sem uma chave ativa, nenhuma das duas opções da The Courier Guy (entrega por courier até a porta ou TCG locker) é mostrada aos clientes na finalização de compra, e nenhuma tarifa é calculada. Um usuário administrador conectado ao administrativo no mesmo navegador continua vendo as opções na loja, marcadas com (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 essa prévia não está disponível: a loja não vê o login do administrativo, então sem uma chave ativa as opções ficam ocultas para todos. Depois de 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 renovação. O status é verificado de novo automaticamente ao abrir o Dashboard do administrativo ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser informada e, depois, uma vez por semana. Não é necessário nenhum cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

The Courier Guy does not appear at checkout: verifique se a licença está ativa e se a opção está ligada (Courier to the door ou TCG locker). Confira Geo zone (ou Ignore shipping zones e Countries), os limites de peso e Minimum order amount. Verifique se a tabela ou Fallback cost tem um preço. Verifique se os produtos têm Requires Shipping definido como Yes. A opção de locker aparece somente para endereços sul-africanos e com a chave de API.

Customers see no locker list: os lockers precisam da chave de API, de TCG locker ligado e de um endereço de entrega na África do Sul. A página de configurações mostra o último erro do ShipLogic, se houver, por exemplo uma chave recusada.

The price is always the table price: confira os avisos na página de configurações. Uma tarifa em tempo real exige a chave de API, o endereço completo do remetente e, para lojas que não usam rands, a taxa de conversão para ZAR. Para entrega por courier, o endereço do cliente precisa de rua, cidade, província (zona) e CEP. Para os lockers, o ShipLogic precisa encontrar um locker perto da cidade do cliente. Ative o Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão.

ShipLogic is down: é mostrado o preço da tabela ou o preço de contingência. Pedidos com locker podem ser feitos sem locker e ficam sinalizados no pedido.

Rates look outdated after a change: clique em Save na página da extensão. Isso limpa as tarifas e os lockers em cache.

The page says "Warning: You do not have permission to modify VibeFox The Courier Guy!": o seu grupo de usuários administradores pode apenas visualizar as configurações. Dê ao grupo a permissão de modificação para extension/shipping/vfd_the_courier_guy (OpenCart 3) ou extension/vfd_the_courier_guy/shipping/vfd_the_courier_guy (OpenCart 4) em System > Users > User Groups.

For developers: o endereço da API do ShipLogic pode ser substituído pela configuração vfd_tcgr_api_url (para testes); ela não tem campo na página de configurações.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox The Courier Guy. 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 status e Geo zone. As tarifas e os lockers em cache e o último erro do ShipLogic são sempre removidos. Se Remove data on uninstall estiver ativada, as configurações, o log e as escolhas de locker das finalizações de compra sem pedido também são apagados. Se estiver desativada, as demais configurações são mantidas e voltam a ser usadas ao reinstalar a extensão. Lockers e referências de rastreamento salvos nos pedidos nunca são removidos, e os pedidos existentes mantêm o método de entrega e o custo.

Para remover também os arquivos da extensão no OpenCart 4, acesse Extensions > Installer após a desinstalação, clique em Uninstall (o botão laranja −) ao lado de VibeFox The Courier Guy na lista de extensões instaladas e, depois, em Delete (o botão vermelho da lixeira) para excluir o pacote enviado.

A The Courier Guy e o ShipLogic são marcas registradas de seus respectivos proprietários. Esta extensão não é afiliada nem endossada pela The Courier Guy ou pelo ShipLogic.