VibeFox Cargoson for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado com a 3.0.5.0) ou 4.0.2 e posteriores (testado com a 4.1.0.3).
PHP: 8.0 ou superior.
Conta Cargoson (somente para preços em tempo real): os preços em tempo real usam a API de preços de frete da Cargoson. As consultas de preço de frete exigem uma assinatura Cargoson com acesso à API (plano Advanced ou superior, no momento em que este texto foi escrito). A chave de API é emitida na sua conta Cargoson; peça ajuda ao suporte da Cargoson se o seu plano não mostrar as configurações de API. Os preços vêm das transportadoras e tabelas de preço conectadas a essa conta. Se você usa somente preços fixos, não precisa de conta Cargoson.
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 README.txt, o pacote do OpenCart 3 vfd_cargoson-oc3-(versão).ocmod.zip e o pacote do OpenCart 4 vfd_cargoson.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.
OpenCart 3
1. No administrador, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_cargoson-oc3-(versão).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 Cargoson e clique em Install (o botão verde +).
3. Clique em Edit (o botão de lápis) para abrir a página de configurações.
4. Insira a 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. Escolha como o custo do frete é calculado e preencha as seções correspondentes: os preços fixos e, para os preços em tempo real, a chave de API e o código postal de coleta (veja Configuração). Ative Enable Cargoson e clique em Save.
OpenCart 4
1. No administrador, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_cargoson.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. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox Cargoson, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).
4. Insira 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 seus campos são iguais nas duas versões.
Após a instalação, o método fica desativado até que você ative Enable Cargoson e salve. Se você reinstalar a extensão depois de desinstalá-la, as configurações da Cargoson que você manteve serão usadas novamente.
Configuração
Todas as configurações ficam na página da extensão: Extensions > Extensions > Shipping > VibeFox Cargoson > Edit. As seções aparecem à esquerda. Um único botão Save no final salva a página inteira sem recarregá-la. Depois de salvar, você verá Settings saved. Cached Cargoson prices were cleared. Números decimais podem ser digitados com ponto ou vírgula. Nada é salvo e a página lista os erros se Method title estiver vazio ou com mais de 64 caracteres, se um campo numérico contiver texto ou um número negativo, se Currency conversion rate for 0, se Minimum weight (kg) for maior que Maximum weight (kg), se Price currency não for um código de 3 letras, se uma linha da tabela de preços tiver um país ou um preço inválidos, ou se Sort order não for um número inteiro. Se a unidade de peso da loja não for conhecida pela extensão, um aviso após salvar informa que os pesos dos produtos são tratados em quilogramas; adicione uma classe de peso com a unidade kg em System > Localisation > Weight Classes. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações.
Geral
O cliente vê uma única tarifa da Cargoson. Você pode limitar o método a uma zona geográfica ou a países em Availability.
Enable Cargoson: mostra ou oculta a Cargoson na finalização de compra. Padrão: desativado.
Method title: o nome do método de envio mostrado ao cliente no carrinho e na finalização de compra, com no máximo 64 caracteres. Padrão: Cargoson. Obrigatório.
Shipping cost: como o preço é calculado.
O motivo de um preço em tempo real ausente é registrado no log de depuração. Ele nunca é mostrado ao cliente.
Sort order: a posição da Cargoson entre os métodos de envio na finalização de compra. Um número inteiro.
API da Cargoson (obrigatória somente para preços em tempo real)
API key: a chave de API da sua conta Cargoson. Ela é enviada somente à Cargoson e nunca é mostrada aos clientes nem gravada no log. Após salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo somente para alterá-la.
Remove the saved API key: ative e salve para apagar a chave salva.
Carrier: quais preços são usados. O cliente vê uma única tarifa.
Package type code: o tipo de pacote da Cargoson enviado com a consulta de preço. Padrão: CLL. Os exemplos da API da Cargoson usam EUR (palete EUR) e FIN (palete FIN). Para pacotes, use o código de pacote da sua conta Cargoson. O pedido é enviado como um único pacote com o peso total do carrinho.
Price currency: a moeda dos preços na sua conta Cargoson, como código de 3 letras. Padrão: EUR. A API retorna valores sem código de moeda.
Currency conversion rate: necessária somente se a moeda dos preços for diferente da moeda padrão da loja: 1 unidade da moeda da Cargoson = X unidades da moeda padrão. Deixe vazio para rejeitar esses preços, de modo que o cliente nunca seja cobrado em moeda errada.
Envio a partir de (endereço de coleta) (para preços em tempo real)
Collection country: o país de onde você envia. A primeira opção, Store country, usa o país da sua loja.
Collection postcode: o código postal de onde você envia. A Cargoson exige para preços em tempo real. O endereço da loja no OpenCart é texto livre, então o código postal nunca é tirado dele: informe-o aqui.
A data de coleta enviada à Cargoson é hoje no fuso horário da loja, ou a próxima segunda-feira nos fins de semana.
Preços fixos (usados quando Shipping cost é Fixed prices, e como alternativa para os preços em tempo real)
Price per country and size: uma lista de linhas com um Country, um Price e preços conforme o peso do carrinho, na moeda padrão da loja e sem impostos: XS até 1 kg, S até 2 kg, M até 3 kg, L até 5 kg, XL acima de 5 kg. Um preço de tamanho vazio ou igual a 0 usa a coluna Price; um Price vazio significa que não há tarifa fixa para aquele tamanho. Clique em Add country para adicionar uma linha. Escolha * All other countries para os preços usados em todos os países sem linha própria. Países sem linha (quando não há linha *) não têm tarifa fixa, então o método fica oculto para eles. Os preços devem ser números maiores ou iguais a 0. Uma linha vazia é ignorada.
Fixed price applies: Per order (padrão) cobra o preço uma vez. Per item (price × quantity) o multiplica pelo número de itens no carrinho. Os preços em tempo real da Cargoson são sempre por envio.
Condições
Minimum weight (kg): oculta o método abaixo deste peso do carrinho. 0 significa sem limite (padrão).
Maximum weight (kg): oculta o método acima deste peso do carrinho. Padrão: 25. 0 significa sem limite.
Minimum order amount: mostra o método somente quando o subtotal dos produtos que precisam de envio (após o cupom, sem impostos) atinge este valor. Deixe vazio para mostrar sempre.
Free shipping: ative o frete grátis da Cargoson a partir do valor abaixo.
Free shipping from: o subtotal dos produtos que precisam de envio (após o cupom, sem impostos) a partir do qual o frete é grátis. Usado somente quando Free shipping está ativo.
Tax class: a classe de imposto do custo do frete, ou No tax (padrão). Os preços das transportadoras na Cargoson costumam ser líquidos (sem IVA). Escolha No tax se seus preços já incluem impostos.
Disponibilidade
Geo zone: oferece a Cargoson somente para endereços nesta zona geográfica. All zones (padrão) significa sem limite. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.
Ignore shipping zones: não verifica a zona geográfica; a lista de países abaixo decide.
Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países. Este campo é usado somente quando Ignore shipping zones está ativo.
Avançado
Debug log: registra cada cálculo de tarifa em storage/logs/vfd_cgs_debug.log.php. O arquivo não pode ser lido pela web. Erros da API e preços rejeitados são sempre registrados, mesmo com esta opção desativada. A chave de API e o código postal do cliente nunca são registrados. Quando o arquivo chega a 5 MB, ele é movido para vfd_cgs_debug.old.log.php e um novo log é iniciado.
Log: mostra o tamanho e as últimas entradas do log de depuração. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativo, desinstalar a extensão apaga as configurações da Cargoson, os preços em cache e o log. Quando desativado (padrão), eles são mantidos para uma nova instalação. As cotações da Cargoson de pedidos realizados são sempre mantidas.
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 envio, ele pede à extensão o preço da Cargoson. Se uma Geo zone estiver definida, Ignore shipping zones estiver desativado e o endereço estiver fora dela, a Cargoson não é oferecida. Só contam produtos com Requires Shipping definido como Yes: os demais não somam peso e não entram no valor do pedido. Os pesos dos produtos são convertidos da classe de peso para quilogramas. Depois a extensão verifica as condições: países permitidos, peso do carrinho e valor mínimo do pedido. O valor do pedido é o preço dos produtos que precisam de envio, após o desconto do cupom e antes dos impostos. Vales-presente, pontos de recompensa e crédito da loja não são considerados. Se o frete grátis se aplicar, o preço é 0 e nenhuma solicitação é enviada à Cargoson.
No modo fixo, o preço é tirado da tabela. Nos modos em tempo real, a extensão envia à Cargoson a data de coleta, o país e o código postal de coleta, o país e o código postal de entrega, e um pacote com o código do tipo de pacote e o peso total do carrinho (no mínimo 0,1 kg). Um preço em tempo real só é solicitado quando o endereço de entrega tem código postal. A Cargoson retorna os preços das suas transportadoras; a extensão escolhe o mais barato (da transportadora selecionada, se houver) e o converte para a moeda padrão, se necessário. O preço é calculado na moeda padrão, arredondado conforme as casas decimais dela, e mostrado ao cliente na moeda dele com o imposto da Tax class selecionada.
Cada resposta fica em cache por 1 hora, para que o mesmo carrinho não dispare uma nova solicitação. Uma solicitação com falha fica em cache por 10 minutos, para que a finalização de compra não espere pela Cargoson a cada atualização. O tempo limite da API é de 10 segundos. Se a Cargoson retornar um erro, nenhum preço para a rota ou um preço em outra moeda sem taxa de conversão, o cliente não vê nenhum erro: o método fica oculto, ou no modo de reserva usa-se o preço fixo.
A extensão apenas calcula tarifas. Ela não cria envios ou reservas na Cargoson, não imprime etiquetas, não rastreia pacotes, e os clientes não podem escolher um armário automático nem um ponto de retirada. O carrinho é cotado como um único pacote com o peso total; as dimensões do pacote não são enviadas. Só o preço mais baixo é mostrado, não uma lista de transportadoras.
No OpenCart 4, o cliente clica em Choose no bloco de métodos de envio da página de finalização de compra e escolhe a Cargoson na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.
Pedidos
Quando um cliente faz um pedido com a Cargoson, a tarifa calculada na finalização de compra é salva com o pedido. Em Sales > Orders, a página do pedido mostra um painel Cargoson shipping:
Carrier, Service e Cargoson service ID: a transportadora e o serviço da Cargoson cotados, mostrados quando um preço em tempo real foi usado.
Price source: Cargoson live price, Fixed price ou Free shipping threshold.
Calculated price (excl. tax): o preço na moeda padrão da sua loja.
O painel também aparece com o método desativado. No OpenCart 4, o pedido é criado uma vez na etapa de confirmação e atualizado sempre que o cliente volta a ela, então a cotação salva é a última calculada na finalização de compra; se o cliente mudar para outro método de envio, a cotação da Cargoson do pedido é removida. Alterar o pedido no administrador não muda a cotação, e ela também não muda depois. Reserve o envio na Cargoson ou com as integrações próprias dela.
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 Cargoson é o primeiro bloco em Extensions > Extensions > Shipping > VibeFox Cargoson > Edit, acima das configurações. Insira 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: opencart-shipping-cargoson 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 administrador (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 de liberar uma vaga 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 na configuração do OpenCart. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a Cargoson não é mostrada aos clientes na finalização de compra e nenhuma tarifa é calculada. Um usuário administrador que esteja logado no administrador 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 prévia não está disponível: a loja não enxerga o login do administrador, então sem uma chave ativa o método fica oculto para todos. Depois de abrir a página Edit uma vez, um lembrete aparece no Dashboard do administrador. Feche-o com × para ocultá-lo por 7 dias. 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 novamente de forma automática quando você abre o Dashboard do administrador ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser inserida, 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
A Cargoson não aparece na finalização de compra: verifique se a licença está ativa e se Enable Cargoson está ativado. Verifique a Geo zone (ou Ignore shipping zones e Countries), os limites de peso e o Minimum order amount. No modo fixo, confira se o país ou * All other countries tem preço para o tamanho do carrinho. Confira se os produtos têm Requires Shipping definido como Yes.
Os preços em tempo real não aparecem: veja o campo Log na página da extensão. Erros da API são sempre registrados; ative o Debug log para ver cada cálculo. Motivos comuns: ainda não foi informado o código postal de entrega, falta o Collection postcode, a chave de API foi rejeitada (chave errada ou expirada, ou o plano da Cargoson não tem acesso à API), não há transportadora para a rota ou o peso, ou há um preço em outra moeda. Com Cargoson live prices, fixed prices if the API fails, os clientes continuam recebendo o preço fixo enquanto você corrige o problema.
A Cargoson rejeita o tipo de pacote: use o código de pacote que a sua conta Cargoson usa em Package type code. O motivo aparece no log.
Um preço em outra moeda é rejeitado: defina Price currency como a moeda dos seus preços da Cargoson e informe a Currency conversion rate.
O imposto é cobrado duas vezes no frete: seus preços da Cargoson já incluem IVA. Defina Tax class como No tax.
As tarifas parecem desatualizadas após uma alteração: clique em Save na página da extensão. Isso limpa os preços da Cargoson em cache.
A página diz "Warning: You do not have permission to modify VibeFox Cargoson!": o seu grupo de usuários administradores pode ter apenas permissão de visualização das configurações. Dê ao grupo a permissão de modificação para extension/shipping/vfd_cargoson (OpenCart 3) ou extension/vfd_cargoson/shipping/vfd_cargoson (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: o endereço da API da Cargoson pode ser substituído pela configuração vfd_cgs_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 Cargoson. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable Cargoson, Sort order, Tax class e Geo zone. Os preços em cache são sempre removidos. Se Remove data on uninstall estiver ativo, as configurações da Cargoson e o log de depuração também são apagados. Se estiver desativado, as demais configurações são mantidas e usadas novamente ao reinstalar a extensão. As cotações da Cargoson de pedidos realizados nunca são apagadas, e os pedidos existentes mantêm o método de envio e o custo.
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 Cargoson na lista de extensões instaladas, depois em Delete (o botão vermelho de lixeira) para remover o pacote enviado.
Cargoson é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela Cargoson.