VibeFox Chilexpress for OpenCart — Ajuda

Requisitos

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

PHP: 8.0 ou superior.

Chaves de API da Chilexpress (somente para tarifas em tempo real): crie uma conta no portal de desenvolvedores da Chilexpress (developers.wschilexpress.com) e assine dois produtos: Rating (Cotizador) e Coverage (Coberturas / Georreferencia). Cada produto tem sua própria chave de assinatura. As chaves de teste funcionam somente com o ambiente de teste; as chaves de produção são emitidas para clientes empresariais da Chilexpress com contrato. Você também precisa do código de county da Chilexpress da comuna de onde envia, por exemplo STGO. Se usar apenas preços fixos, não precisa de chaves de API.

Regiões do Chile (somente para tarifas em tempo real): as tarifas em tempo real precisam da região (zona) do endereço de entrega. O OpenCart 3.0.5.0 tem 15 das 16 regiões do Chile; a extensão pode adicionar as que faltam (veja Chilean regions abaixo). O país Chile precisa existir na loja.

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_chilexpress-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_chilexpress.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, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_chilexpress-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. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox Chilexpress 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. Digite 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 Country prices. Para tarifas em tempo real, informe as duas chaves de assinatura, o código de county de origem e, se a moeda da loja não for CLP, a taxa de câmbio para CLP. Clique em Add Chilean regions se a página mostrar regiões faltantes e, depois, escolha a fonte das tarifas (veja Configuração). Ative Enable/Disable e clique em Save.

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_chilexpress.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir 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 Chilexpress, clique em Install (o botão verde +) e depois em Edit (o botão de 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 seus campos são iguais nas duas versões.

Após a instalação, o método fica desativado até que você ative Enable/Disable e salve. Se você instalar a extensão novamente depois de desinstalá-la, as configurações da Chilexpress que você manteve serão usadas de novo.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Shipping > VibeFox Chilexpress > 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 Chilexpress rates and comuna lists were cleared. Somente usuários administradores com permissão de modificação para esta extensão podem salvar as configurações, limpar o log ou adicionar regiões.

A página mostra os problemas no topo: tarifas da API selecionadas, mas a chave Rating API está vazia; a chave Coverage API está vazia; o código de county de origem está vazio ou é inválido; a moeda da loja não é CLP e não há taxa de câmbio para CLP definida; Country prices não tem linha para o Chile nem para o padrão; o Chile não tem zonas na loja; a unidade de peso ou de comprimento da loja não é conhecida pela extensão (os pesos são lidos como kg e as dimensões como cm; use kg, g, lb ou oz e cm, mm, m ou in em System > Localisation). Os números podem ser digitados com ponto ou vírgula. Nada é salvo e a página lista os erros se Name estiver vazio, contiver algum dos caracteres < > ; = # { } ou tiver mais de 64 caracteres, se um número for inválido ou negativo, se CLP exchange rate for 0, se Min weight (kg) for maior que Max weight (kg), se Origin county code não for um código de county ou se Sort order não for um número inteiro.

Geral

Um único método de envio "Chilexpress" para cada zona geográfica, ou para a zona geográfica selecionada em Disponibilidade.

Enable/Disable: mostra ou oculta a Chilexpress na finalização de compra. Padrão: desativado.

Name: o nome do método de envio exibido ao cliente na finalização de compra. Padrão: Chilexpress. Obrigatório, até 64 caracteres.

Tax class: a classe de imposto do custo de envio, ou No tax (padrão). As tarifas da API da Chilexpress são usadas exatamente como cotadas. Escolha No tax se a cotação já incluir o IVA e a loja aplicaria imposto por cima.

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

Tarifas

Rate source: de onde vem o preço.

As tarifas em tempo real estão disponíveis somente para destinos no Chile. Os demais países sempre usam os preços fixos.

Country prices: uma lista de países de destino com uma coluna Price e preços opcionais por tamanho do pacote, na moeda padrão da sua loja, sem impostos. O tamanho vem do peso do carrinho: XS até 1 kg, S até 2 kg, M até 3 kg, L até 5 kg, XL acima de 5 kg. Um tamanho deixado em 0 usa Price. Clique em Add country para adicionar uma linha. A linha * Default (other countries) se aplica a países sem linha própria. Um país sem linha (e sem a linha padrão) não recebe preço fixo, então o método fica oculto ali. Uma linha salva cujo preço e preços por tamanho são todos 0 oferece frete grátis. Uma tabela vazia mostra uma linha para o Chile com 0, então informe preços reais antes de salvar a página. Um país repetido ou um preço inválido é corrigido (a duplicata é ignorada e o preço vai para 0), e um aviso lista as correções.

Calculation type: Per order (padrão) cobra o preço fixo uma vez. Per item (fixed price x number of items) o multiplica pelo número de itens do carrinho. Uma tarifa da API da Chilexpress é sempre cotada para o pacote inteiro.

API da Chilexpress (tarifas em tempo real)

A seção começa com links para o portal de desenvolvedores e para as páginas de assinatura de Rating e Coverage.

Test environment: usa o ambiente de teste da Chilexpress (qaservices.wschilexpress.com). Use-o com chaves de teste e desative-o em uma loja em produção. Padrão: desativado.

Rating API key: a chave de assinatura do produto Rating (Cotizador).

Coverage API key: a chave de assinatura do produto Coverage (Coberturas / Georreferencia). Ela serve para encontrar o código de county da Chilexpress da comuna do cliente (o campo City do endereço, junto com a região).

Depois de salvar, o campo da chave fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-la. A chave é salva como digitada; apenas os espaços em volta são removidos.

Remove the saved Rating API key e Remove the saved Coverage API key: ative uma delas e clique em Save para excluir essa chave.

Origin county code: o código de county da Chilexpress da comuna de onde você envia, de 2 a 5 letras, por exemplo STGO (Santiago Centro), PROV (Providencia) ou VALP (Valparaíso). Fica vazio após a instalação. Um valor que não seja um código de county é recusado com um erro.

Service: o serviço da Chilexpress usado para a tarifa. Se ele não for oferecido para o destino, é usado o serviço mais barato disponível.

CLP exchange rate: a Chilexpress cota em pesos chilenos. Só é necessária se a moeda padrão da sua loja não for CLP: o preço de 1 CLP nessa moeda, por exemplo 0.001. Sem ela, as tarifas da API não são usadas. Se a moeda da loja for CLP, deixe vazio. O valor deve ser maior que 0.

Chilean regions: as comunas do Chile são consultadas por região, por isso as tarifas em tempo real precisam da região (zona) do endereço. O campo mostra quantas zonas o Chile tem e quais regiões faltam, com o botão Add Chilean regions. Ele adiciona somente as regiões faltantes como zonas do Chile; zonas existentes não são alteradas e uma região não é adicionada duas vezes. Quando as 16 regiões estiverem presentes, o campo mostra All 16 Chilean regions are zones of Chile. Se o Chile não for um país da loja, o campo informa isso: adicione-o em System > Localisation > Countries.

Disponibilidade

Min weight (kg): o peso mínimo do carrinho para o método aparecer. 0 significa sem limite (padrão).

Max weight (kg): o método fica oculto acima deste peso do carrinho. Padrão: 25. 0 significa sem limite; um campo vazio significa 25 kg.

Minimum subtotal: mostra o método somente quando o subtotal do carrinho (produtos que precisam de envio, após cupons, sem impostos) for pelo menos este valor. Deixe vazio para mostrá-lo sempre.

Geo zone: oferece o método 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 é usado enquanto Ignore shipping zones estiver ativado.

Ignore shipping zones: oferece o método para os países abaixo sem verificar a zona geográfica.

Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países. Este campo só é usado quando Ignore shipping zones está ativado.

Frete grátis

Free shipping: ativa o limite de frete grátis.

Free shipping from: o subtotal do carrinho (produtos que precisam de envio, após cupons, sem impostos) a partir do qual o envio é gratuito. Usado somente quando Free shipping está ativado. Nesse caso, nenhuma requisição é feita à API.

Avançado

Debug log: grava as requisições à API e os cálculos de tarifas em storage/logs/vfd_chx_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. Chaves de API e endereços de clientes nunca são registrados. Quando o arquivo chega a 5 MB, ele é movido para vfd_chx_debug.old.log.php e um novo registro é iniciado.

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

Remove data on uninstall: quando ativado, desinstalar a extensão exclui todas as suas configurações, tarifas em cache e o registro. Quando desativado (padrão), tudo é mantido para uma reinstalação. Pedidos e os serviços da Chilexpress salvos com eles são sempre mantidos.

Importação / Exportação

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. Chaves de API 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. Chaves de API salvas são mantidas.

Como funciona na finalização de compra

Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço da Chilexpress. Se houver uma Geo zone definida, Ignore shipping zones estiver desativado e o endereço estiver fora da zona, a Chilexpress não é oferecida. Somente produtos com Requires Shipping definido como Yes contam: os demais não adicionam peso e não entram no subtotal. Os pesos são convertidos em quilogramas e as dimensões em centímetros, a partir das classes de peso e de comprimento dos produtos. O subtotal é o preço dos produtos que precisam de envio, após o desconto do cupom, sem impostos, na moeda padrão da loja. Vales-presente, pontos de fidelidade e crédito da loja não são considerados. A extensão verifica primeiro as condições: países permitidos (com Ignore shipping zones), peso do carrinho e subtotal mínimo. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada à Chilexpress.

Para um endereço no Chile com fonte de tarifas da API, a extensão obtém a região (zona) do endereço e a comuna do campo City e procura o código de county da Chilexpress na lista de comunas dessa região (API Coverage). Acentos, espaços e variações de grafia são ignorados, então Ñuñoa e Nunoa coincidem, e Santiago coincide com Santiago Centro. Um código de county digitado no campo City também é aceito. Em seguida, a extensão envia à API Rating os códigos de county de origem e de destino, o peso do carrinho (pelo menos 0,1 kg), as dimensões do pacote (comprimento e largura do maior produto, alturas somadas) e o subtotal do carrinho em CLP como valor declarado. A Chilexpress retorna seus serviços; a extensão usa o escolhido ou o mais barato e converte o valor em pesos para a moeda padrão da loja. O preço é arredondado para as casas decimais dessa moeda e então exibido na moeda do cliente com o imposto da Tax class selecionada.

As tarifas ficam em cache por 1 hora. As listas de comunas ficam em cache por até 7 dias, mas não mais do que o cache do OpenCart mantém suas entradas (1 hora por padrão). Uma requisição que falhou é lembrada por 5 minutos, para que uma API lenta ou indisponível não atrase cada atualização da finalização de compra. O tempo limite da API é de 10 segundos. Se a Chilexpress retornar erro, nenhum serviço com preço, ou se a comuna ou a região forem desconhecidas, o cliente não vê nenhum erro. O método fica oculto no modo somente API, ou o preço fixo é usado. O motivo é gravado no registro de depuração.

A extensão calcula somente tarifas. Ela não cria envios nem ordens de transporte (OT), não imprime etiquetas, não agenda coletas e não rastreia pacotes; faça a reserva do envio na sua conta da Chilexpress. Os clientes não podem escolher uma agência da Chilexpress, e não há seletor de comuna: o cliente digita a comuna no campo City padrão. Envios internacionais usam os preços fixos.

No OpenCart 4, o cliente clica em Choose no bloco de método de envio da página de finalização de compra e escolhe a Chilexpress na janela Shipping method options, por exemplo Chilexpress - $5.49. O método funciona da mesma forma que no OpenCart 3.

Pedidos

Quando um pedido é feito com a Chilexpress, a extensão salva como o preço foi calculado. Em Sales > Orders, a página do pedido mostra um painel Chilexpress com Chilexpress service (para uma tarifa em tempo real, o serviço cotado pela Chilexpress, por exemplo Express; caso contrário, um traço) e Price: Live rate (Chilexpress Rating API), Fixed price ou Free shipping. O painel também é exibido enquanto o método estiver desativado. No OpenCart 4 o painel Chilexpress é exibido acima de History, e quando um pedido é confirmado novamente na finalização de compra ou muda para outro método de envio, o painel acompanha a mudança.

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 Chilexpress é o primeiro bloco em Extensions > Extensions > Shipping > VibeFox Chilexpress > 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-chilexpress 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 painel 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 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 de domínio. Libere a vaga na sua conta vibefox.net.

Sem uma chave ativa, a Chilexpress não é exibida aos clientes na finalização de compra e nenhuma tarifa é calculada. Um usuário administrador conectado ao admin 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 admin, então sem uma chave ativa o método fica oculto para todos. Depois que você abre a página Edit uma vez, aparece um lembrete no Dashboard do admin. 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 precisam de renovação. O status é verificado de novo automaticamente quando você abre o Dashboard ou a página Edit do admin: uma vez por dia nos primeiros 14 dias após a chave ser inserida 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

A Chilexpress não aparece na finalização de compra: verifique se a licença está ativa e se Enable/Disable está ativado. Confira Geo zone (ou Ignore shipping zones e Countries), os limites de peso e Minimum subtotal. Com preços fixos, verifique se o país ou * Default (other countries) tem uma linha. Verifique se os produtos têm Requires Shipping definido como Yes.

O envio no Chile é grátis quando não deveria ser: a linha de Country prices para o Chile (ou a linha padrão) tem 0 em Price e nas colunas de tamanho. Informe os preços e clique em Save.

A tarifa em tempo real não aparece, o preço fixo é usado: primeiro verifique os avisos no topo da página da extensão. Caso contrário, ative Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão. Causas comuns: o endereço não tem região ou o Chile tem regiões faltando (use Add Chilean regions), uma comuna que a Chilexpress não reconhece (verifique o campo City e a região), uma chave de outro produto ou ambiente, ou um destino sem cobertura da Chilexpress.

HTTP 401 ou 403 no log: a chave de assinatura está errada, inativa ou é de outro produto ou ambiente. Chaves de teste funcionam somente com Test environment ativado.

As tarifas da API não são usadas em uma loja com outra moeda: informe o CLP exchange rate.

As tarifas da API incluem IVA ou não? Elas são usadas exatamente como a Chilexpress as cota. Se a sua loja adicionar imposto ao envio e a cotação já incluir o IVA, defina Tax class como No tax.

As tarifas parecem desatualizadas após uma mudança: clique em Save na página da extensão. Isso limpa as tarifas e listas de comunas em cache.

A página diz "Warning: You do not have permission to modify VibeFox Chilexpress!": 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_chilexpress (OpenCart 3) ou extension/vfd_chilexpress/shipping/vfd_chilexpress (OpenCart 4) em System > Users > User Groups.

Para desenvolvedores: o endereço base da API da Chilexpress pode ser substituído pela configuração vfd_chx_api_base_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 Chilexpress. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable/Disable, Sort order, Tax class e Geo zone. As tarifas e listas de comunas em cache são sempre removidas. Se Remove data on uninstall estiver ativado, as demais configurações e o registro de depuração também são excluídos. Se estiver desativado, são mantidos e usados novamente quando você reinstalar a extensão. Os serviços da Chilexpress salvos com os pedidos nunca são excluídos, e os pedidos existentes mantêm seu método e custo de envio. As regiões do Chile adicionadas com Add Chilean regions permanecem na loja.

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

A Chilexpress é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pela Chilexpress.