VibeFox Blue Express 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.
Conta Blue Express (somente para tarifas em tempo real): as tarifas em tempo real exigem uma conta de e-commerce da Blue Express e a sua chave de API (x-api-key). Solicite-a à Blue Express: developers.bluex.cl ou gpo.integraciones@bx.cl. O serviço que você usa (EX, PY ou MD) deve estar habilitado no seu contrato com a Blue Express. Se você usar apenas preços fixos, não precisa de chave de API.
Regiões chilenas: para uma tarifa em tempo real, o endereço de entrega deve ter uma região chilena. Se a sua loja não tiver as regiões chilenas, a extensão pode adicioná-las para você (veja Configuração).
Pontos de retirada: o mapa da Blue Express é carregado a partir de widget-pudo.blue.cl no navegador do cliente.
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_blue_express-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_blue_express.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 painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_blue_express-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 Blue Express e clique em Install (o botão verde +).
3. Clique em Edit (o botão do lápis) para abrir a página de configurações.
4. Digite 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. Informe a chave da API, o serviço, o código do distrito de origem (por exemplo SCL), a taxa de câmbio para CLP se a moeda da sua loja não for CLP, e os preços fixos (por exemplo CL=4500). Ative Enable/Disable para a entrega em domicílio e Pickup point option se quiser oferecer retirada nos pontos da Blue Express. Clique em Save. Veja Configuração.
OpenCart 4
1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_blue_express.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 Blue Express, clique em Install (o botão verde +) e depois em Edit (o botão do lápis).
4. Digite 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 campos são os mesmos nas duas versões.
Ao instalar, a extensão cria uma tabela para os pontos de retirada dos pedidos. O método fica desativado até que você ative a entrega em domicílio ou a opção de ponto de retirada e salve. Se você instalar a extensão novamente após uma desinstalação, as configurações da Blue Express que você manteve voltam a ser usadas.
Configuração
Todas as configurações estão na página da extensão: Extensions > Extensions > Shipping > VibeFox Blue Express > Edit. As seções ficam listadas à esquerda. Um único botão Save salva a página inteira sem recarregá-la. Cada salvamento também limpa o cache de tarifas da Blue Express e de dados de comunas. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações. As condições, os preços e a classe de imposto abaixo se aplicam às duas opções.
Valores inválidos são recusados com um erro e nada é salvo: um nome vazio ou com os caracteres < > ; = # { }, um nome com mais de 64 caracteres, um número negativo ou inválido, um Min weight (kg) maior que Max weight (kg), um Sort order que não é um número inteiro, ou uma classe de imposto ou zona geográfica desconhecida.
Avisos sobre configurações que ocultariam as opções ou a tarifa em tempo real aparecem no topo da página: falta a chave de API, uma moeda da loja diferente de CLP sem taxa de câmbio, uma tabela de preços fixos vazia, nenhuma zona para o Chile, e uma loja sem classe de peso em quilogramas nem classe de comprimento em centímetros cuja unidade padrão a extensão não reconhece (os pesos são então lidos como kg e as dimensões como cm).
Geral
Enable/Disable: ativa ou desativa a entrega em domicílio da Blue Express.
Name: o nome do método de entrega exibido no checkout para a entrega em domicílio. Padrão: Blue Express. Obrigatório, no máximo 64 caracteres.
Tax class: a classe de imposto do custo de entrega, ou None (no tax on shipping) (padrão). Os preços da Blue Express incluem IVA. Escolha None se o OpenCart não deve adicionar imposto por cima. Vale para as duas opções.
Sort order: a posição da Blue Express entre os métodos de entrega no checkout. Um número inteiro.
Retirada em pontos da Blue Express (PUDO)
Pickup point option: oferece a entrega em um ponto da Blue Express escolhido pelo cliente, como segunda opção ao lado da entrega em domicílio. Desativada por padrão.
Pickup point name: o nome do método de entrega exibido no checkout para a retirada em um ponto da Blue Express. Padrão: Blue Express pickup point. Obrigatório, no máximo 64 caracteres.
API da Blue Express (necessária para tarifas em tempo real)
API key: a sua chave de API da Blue Express (cabeçalho x-api-key). Sem ela, só os preços fixos são usados. Depois de salvar, o campo fica vazio e mostra A key is saved - leave empty to keep it. Digite um valor novo somente se quiser alterá-la.
Remove the saved API key: ative e salve para excluir a chave salva.
Service: o serviço da Blue Express usado para a tarifa: Express (EX) (padrão), Prioritario (PY) ou SameDay (MD). Ele deve estar habilitado no seu contrato com a Blue Express.
Origin district code: o código de distrito da Blue Express do local de onde você envia, por exemplo SCL para Santiago (padrão). Pergunte à Blue Express se tiver dúvidas.
CLP per 1 (your currency): o rótulo mostra a moeda padrão da sua loja, por exemplo CLP per 1 EUR. Os preços da Blue Express estão em pesos chilenos (CLP). Informe quantos CLP vale uma unidade da moeda padrão da sua loja, por exemplo 1050. Sem isso, as tarifas em tempo real não são usadas. É ignorado quando a moeda da loja é CLP.
Preço
Rate source: como o preço é calculado. A tarifa em tempo real exige um endereço chileno com região e comuna (cidade). Os erros são gravados no log e nunca mostrados ao cliente.
Fixed prices: uma linha por país no formato CÓDIGO_DO_PAÍS=PREÇO, na moeda padrão da loja, sem impostos, por exemplo CL=4500 em uma loja em CLP ou CL=4.50 em uma loja em EUR. Vírgula ou ponto são aceitos como separador decimal. Linhas inválidas são ignoradas e listadas em um aviso ao salvar. Um país sem linha não tem preço fixo, por isso as opções ficam ocultas para ele quando o preço fixo é necessário. Os preços fixos podem ser usados para qualquer país.
Fixed price per: Order (padrão) cobra o preço uma vez. Item (price x quantity) o multiplica pelo número de itens no carrinho. Isso vale somente para o preço fixo. A tarifa da API é sempre para o envio inteiro.
Condições
Min weight (kg): oculta o método quando o carrinho pesa menos. 0 significa sem limite (padrão).
Max weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 100. 0 significa sem limite; um campo vazio significa 100 kg.
Minimum order subtotal: mostra o método somente a partir deste subtotal do carrinho (moeda da loja, produtos que precisam de entrega, após o cupom, sem impostos). Deixe vazio para mostrá-lo sempre.
Frete grátis
Free shipping: ativa o frete grátis a partir de um subtotal do carrinho.
Free from subtotal: o subtotal do carrinho (moeda da loja, produtos que precisam de entrega, após o cupom, sem impostos) a partir do qual o frete é grátis. Nesse caso nenhuma solicitação é enviada à Blue Express. Usado somente quando Free shipping está ativado.
Disponibilidade
Geo zone: oferece a Blue Express somente para endereços desta zona geográfica. All zones (padrão) significa sem limite. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones. Não é verificado com Ignore shipping zones.
Ignore shipping zones: oferece as duas opções em todas as zonas geográficas. Os países são então limitados pela lista abaixo.
Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países. Usado somente com Ignore shipping zones.
Regiões chilenas (exibido somente quando faltam regiões chilenas na sua loja)
A Blue Express precisa da região de um endereço chileno (RM, VS etc.) para a tarifa em tempo real. A região é obtida da zona do endereço, pelo seu código ou pelo seu nome. A seção mostra quantas zonas o Chile tem na sua loja e quais regiões faltam (uma loja OpenCart 3.0.5 padrão tem 15 de 16, sem Ñuble). Clique em Add Chilean regions para adicionar as regiões que faltam como zonas do Chile, com os códigos que a Blue Express usa. Regiões que você já tem, por código ou por nome, não são adicionadas duas vezes. Nada é alterado até você clicar no botão. Você também pode adicioná-las em System > Localisation > Zones.
Avançado
Debug log: registra solicitações e decisões em storage/logs/vfd_blex_debug.log.php. O arquivo não pode ser lido pela web. Erros da API são sempre registrados. A chave de API e os endereços dos clientes nunca são registrados. Desative o log quando terminar. O log é rotacionado ao atingir 5 MB.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativado, ao desinstalar a extensão são excluídos as configurações, as tarifas em cache e o log. Quando desativado (padrão), são mantidos para uma reinstalação. Os pontos de retirada 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 ativada. Se houver uma Geo zone definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, a Blue Express não é oferecida. Com Ignore shipping zones, a lista Countries decide. Somente produtos com Requires Shipping definido como Yes contam: os demais não adicionam peso e não entram no subtotal. A extensão verifica o peso do carrinho e o Minimum order subtotal. O subtotal é o preço dos produtos que precisam de entrega, após o desconto do cupom e antes dos impostos. Vale-presentes, pontos de fidelidade 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 à Blue Express.
Para uma tarifa em tempo real, o endereço deve estar no Chile, com região e cidade (comuna). A extensão primeiro pede à Blue Express que reconheça a comuna e depois solicita o preço do serviço, do distrito de origem, do destino e dos pacotes. Cada produto é enviado com peso e dimensões convertidos para kg e cm a partir de suas classes de peso e comprimento. Produtos sem peso ou tamanho são enviados como 0,01 kg, 10 x 10 x 10 cm. O valor declarado é enviado em CLP. O preço em CLP é convertido para a moeda padrão da loja, arredondado para as suas casas decimais e exibido ao cliente na moeda dele, com o imposto da Tax class selecionada.
As tarifas ficam em cache por 1 hora e os dados de comunas por até 12 horas, mas nunca além do tempo de cache do OpenCart (1 hora por padrão). Uma chamada à API com falha é lembrada por 5 minutos, e o tempo limite é de 10 segundos, para que uma API lenta ou indisponível não atrase cada atualização da finalização de compra. Erros da API nunca são mostrados ao cliente: a opção fica oculta, ou o preço fixo é usado no modo de contingência. O motivo é gravado no log.
A extensão não cria envios nem etiquetas na Blue Express, não atribui números de rastreamento e não mostra atualizações de rastreamento. Crie o envio na sua conta da Blue Express. Não há tabelas de tarifas regionais por comuna: use a tarifa da API da Blue Express ou um preço fixo por país. As tarifas em tempo real funcionam somente para o Chile.
No OpenCart 4, o cliente clica em Choose no bloco de métodos de entrega da página de finalização de compra e escolhe Blue Express ou Blue Express pickup point na janela Shipping method options. As opções funcionam da mesma forma que no OpenCart 3; a caixa do ponto de retirada é descrita em Pontos de retirada.
Pontos de retirada
Quando a opção de ponto de retirada está ativada, aparece uma caixa com o botão Choose pickup point abaixo de Blue Express pickup point na etapa Delivery Method da finalização de compra do OpenCart. O botão abre o mapa oficial da Blue Express, onde o cliente escolhe um ponto. O ponto escolhido é exibido com nome e endereço, e o botão muda para Change pickup point. O ponto é salvo para a sessão de compra, e a tarifa é recalculada com o preço de retirada (PUDO) da Blue Express. Se o preço mudar, a opção mostra o novo preço. Se a opção não for mais oferecida para aquele ponto, a etapa de entrega é recarregada. Enquanto nenhum ponto for escolhido, a opção mostra o preço da entrega em domicílio.
O cliente não pode continuar sem um ponto: Continue na etapa de entrega é recusado com Please choose a Blue Express pickup point. Isso é verificado no navegador e novamente pela loja. Um código de ponto malformado é recusado com The selected Blue Express pickup point is not valid. Please choose it again on the map., e a escolha anterior é mantida. Se o salvamento falhar, o cliente vê The pickup point could not be saved. Please try again.
No OpenCart 4, o cliente clica em Choose no bloco de métodos de entrega da finalização de compra. A janela Shipping method options mostra a mesma caixa com Choose pickup point abaixo de Blue Express pickup point enquanto essa opção estiver selecionada. Quando o preço muda com o ponto escolhido, a opção na janela mostra o novo preço, e se a opção de retirada já estiver salva para a finalização de compra, o campo do método de entrega e o bloco de confirmação do pedido também são atualizados. Se a opção não for mais oferecida para esse ponto, a janela é fechada e a lista de métodos de entrega é carregada novamente. Continue na janela sem ponto é bloqueado com Please choose a Blue Express pickup point. na caixa, e a loja verifica novamente. O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza a cada confirmação; o ponto de retirada do pedido é atualizado junto, e é removido quando o pedido é alterado para outro método de entrega.
Quando o pedido é feito, o ponto é salvo no pedido com seu código de agência da Blue Express, nome, endereço e região. Ele também é adicionado ao método de entrega do pedido após o nome da opção de retirada, por exemplo Blue Express pickup point: Blue Point Providencia, Av. Providencia 1234, para que o cliente o veja nos e-mails de pedido e nas páginas de pedidos da sua conta.
Na página de pedido do administrador (Sales > Orders, View), o ponto aparece no painel Blue Express pickup point com seu código e região. Se o pedido não tiver ponto, o painel mostra Not chosen. Clique em Edit para escolher outro ponto com Choose on the Blue Express map ou para digitar manualmente o Agency code, o Name e o Address, depois clique em Save pickup point. O texto do método de entrega do pedido também é atualizado, e a alteração é adicionada ao histórico do pedido sem notificar o cliente (Blue Express pickup point changed: código antigo -> código novo). Alterar o ponto exige apenas a permissão de modificação de pedidos, não o acesso às configurações da extensão. Os pedidos existentes mantêm os dados do ponto de retirada.
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 Blue Express é o primeiro bloco em Extensions > Extensions > Shipping > VibeFox Blue Express > 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 novamente, Change key para inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: opencart-shipping-blue-express 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 da 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 seguido de 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, 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 Blue Express não é exibida aos clientes na finalização de compra e nenhuma tarifa é calculada. Um administrador conectado ao painel no mesmo navegador ainda vê o método na loja, marcado como (unlicensed — visible to admins only), então você pode configurar e testar a extensão antes de comprar uma chave. Depois que você abrir a página Edit uma vez, um lembrete aparece no Dashboard do administrador. 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 precisam de renovação. O status é verificado novamente automaticamente 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 cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.
Solução de problemas
A Blue Express não aparece na finalização de compra: verifique se a licença está ativa e se Enable/Disable (ou Pickup point option) está ativado. Leia os avisos no topo da página da extensão. Confira Geo zone (ou Ignore shipping zones e Countries), os limites de peso, o Minimum order subtotal, e se Fixed prices tem uma linha para o país caso use preços fixos ou a contingência. Confira se os produtos têm Requires Shipping definido como Yes.
As tarifas em tempo real não aparecem: com Blue Express API only, as opções ficam ocultas quando não há tarifa. Ative Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão. Motivos comuns: sem chave de API, moeda da loja diferente de CLP sem taxa de câmbio, região ou comuna ausente no endereço, comuna não reconhecida pela Blue Express, ou um erro da API (por exemplo HTTP 401 ou 403 quando a chave de API é recusada). Com Blue Express API, fixed price if the API gives no rate, os clientes continuam recebendo o preço fixo enquanto você resolve o problema.
Endereços chilenos não têm região: a página mostra um aviso sobre regiões ausentes. Clique em Add Chilean regions na página da extensão. Os clientes cujos endereços foram salvos sem região precisam editar o endereço e escolher a região.
O imposto é somado ao preço da Blue Express: os preços da Blue Express incluem IVA. Defina Tax class como None (no tax on shipping).
O mapa não abre: o mapa é carregado a partir de widget-pudo.blue.cl no navegador do cliente, então esse endereço precisa estar acessível e não bloqueado no seu site.
As tarifas parecem desatualizadas após uma alteração: clique em Save na página da extensão. Isso limpa as tarifas e os dados de comunas em cache.
A página diz "Warning: You do not have permission to modify VibeFox Blue Express!": 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_blue_express (OpenCart 3) ou extension/vfd_blue_express/shipping/vfd_blue_express (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: os endereços da API e do mapa da Blue Express podem ser substituídos pelas configurações vfd_blex_api_url e vfd_blex_widget_url (para testes); eles não têm campos 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 Blue Express. A chave de licença e o status de licença desta extensão são sempre removidos. O OpenCart sempre redefine o status do método, Sort order, Tax class e Geo zone. As tarifas em cache são sempre removidas. Se Remove data on uninstall estiver ativado, as configurações da Blue Express e o log também são excluídos. Se estiver desativado, as demais configurações são mantidas e voltam a ser usadas quando você instalar a extensão novamente. Os pontos de retirada salvos nos pedidos nunca são removidos, e o texto do método de entrega dos pedidos existentes mantém o ponto de retirada.
No OpenCart 4, para remover também os arquivos da extensão, vá em Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Blue Express na lista de extensões instaladas, depois em Delete (o botão vermelho da lixeira) para remover o pacote enviado.
A Blue Express é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pela Blue Express.