VibeFox Sameday Easybox for OpenCart — Ajuda

Requisitos

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

PHP: 8.0 ou superior.

Nome de usuário e senha da API da Sameday: o acesso à API faz parte de uma conta empresarial Sameday na Romênia, Hungria ou Bulgária. Pergunte ao seu gerente de conta Sameday ou à equipe de integração da Sameday. As credenciais costumam ser as mesmas do portal eAWB (eawb.sameday.ro, .hu ou .bg). Para a API de demonstração, a Sameday fornece credenciais de teste separadas. Sem nome de usuário e senha da API, o método não é oferecido, porque o cliente não conseguiria escolher um locker.

País e condados: o país da sua conta Sameday precisa estar ativado em System > Localisation > Countries. A estimativa da Sameday precisa do condado do endereço de entrega (o campo Region / State). O OpenCart tem os condados da Romênia e da Bulgária, mas no OpenCart 3 nenhum da Hungria (no OpenCart 4.1 eles existem). A extensão pode adicioná-los para você (veja mais abaixo, lockers easybox). Sem eles, os preços vêm da sua tabela ou do custo de contingência.

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 para OpenCart 3 vfd_sameday_easybox-oc3-(version).ocmod.zip e o pacote para OpenCart 4 vfd_sameday_easybox.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 admin, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_sameday_easybox-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ê também pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Vá em Extensions > Extensions, escolha o tipo de extensão Shipping, encontre VibeFox Sameday Easybox 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. 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. Informe o seu API username e a sua API password da Sameday, escolha o Sameday country, ative Enable/Disable e clique em Save. A página deve mostrar "Connected to Sameday ... easybox lockers". Pickup point e Easybox service são preenchidos a partir da sua conta.

6. Defina seus preços: Exchange rate of the estimate se a moeda da sua loja for diferente da moeda da Sameday, e uma linha de Country prices (por exemplo * Default) ou um Fallback cost.

7. Se a página disser que o OpenCart não tem condados para o seu país Sameday, clique em Add counties na seção easybox lockers.

OpenCart 4

1. No admin, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_sameday_easybox.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 nesta mesma página. Clique em Install (o botão verde +) ao lado dele.

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

4. Informe a chave de licença e as configurações como nas etapas 4 a 7 do OpenCart 3. A página de configurações e seus campos são iguais nas duas versões. Só a URL do cron é diferente (veja lockers easybox).

Após a instalação, o método fica desativado até você ativar Enable/Disable e salvar. Se você reinstalar a extensão depois de desinstalá-la, as configurações mantidas serão usadas novamente, mas o método começa desativado.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Shipping > VibeFox Sameday Easybox > Edit. As seções são listadas à esquerda. Um botão Save no final salva a página inteira sem recarregá-la. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações.

Acima das configurações, a página mostra o status da conexão: o host da Sameday, o número de lockers easybox e quando a lista foi atualizada, ou que a Sameday recusou o nome de usuário ou a senha. Também lista problemas de configuração, por exemplo falta de credenciais, de preço, de taxa de câmbio para a estimativa, de condados, de classe de peso em quilogramas ou países selecionados fora do seu país Sameday.

Alguns erros impedem o salvamento, e nada é salvo: Enter a valid name (1-64 characters, without < > ; = # { })., Sort order must be a whole number., uma classe de imposto ou uma zona geográfica inválida. Outros problemas mantêm apenas um valor: todos os preços e limites aceitam vírgula ou ponto como separador decimal (4,99 ou 4.99), e um número inválido ou negativo não é salvo. Um aviso indica o campo, e o valor anterior é mantido.

Geral

Enable/Disable: mostra ou oculta o método na finalização de compra. É o status da extensão em Extensions > Extensions > Shipping. Padrão: desligado.

Name: o nome do método de envio mostrado ao cliente. Padrão: Sameday easybox. Até 64 caracteres.

Tax class: --- None --- (padrão) significa que o preço é final. Com uma classe de imposto, o OpenCart adiciona o imposto dessa classe sobre o preço.

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

Conta Sameday (API)

Ao salvar, a extensão entra na Sameday e carrega seus serviços, pontos de coleta e a lista de lockers easybox. A lista é atualizada diariamente.

API username: seu nome de usuário da API da Sameday.

API password: sua senha da API da Sameday. Ela nunca é mostrada de novo: deixe o campo vazio para manter a salva. Esvaziar o nome de usuário remove a senha também. Se a Sameday a recusar, ela não é tentada novamente por 10 minutos.

Sameday country: o país da sua conta Sameday: Romania (api.sameday.ro) (padrão), Hungary (api.sameday.hu) ou Bulgaria (api.sameday.bg). Os lockers dele são oferecidos, e o método é mostrado somente para este país de destino.

Test mode: usa a API de demonstração da Sameday (sameday-api.demo.zitec.com) com credenciais de demonstração.

Preços (o título da seção mostra a moeda padrão da sua loja)

A ordem de uso é: a estimativa da Sameday (quando Pickup point e Easybox service estão definidos), depois a tabela de preços por país e, por último, o custo de contingência. Os preços da tabela são informados na moeda padrão da loja. Clientes que pagam em outra moeda veem o preço convertido.

Pickup point: seu ponto de coleta da Sameday, onde a Sameday recolhe os pacotes. Após um login bem-sucedido, é uma lista dos pontos de coleta da sua conta, e o padrão é escolhido automaticamente. Antes disso, é um campo para o ID. Necessário para a estimativa da Sameday. Escolha - not set (price table only) - para usar somente a tabela de preços.

Easybox service: o serviço da Sameday para entrega easybox, normalmente "Locker NextDay" (código LN), que é escolhido automaticamente. Necessário para a estimativa da Sameday.

Exchange rate of the estimate: a Sameday calcula estimativas na moeda do seu país Sameday: RON, HUF ou BGN (EUR para lojas búlgaras que vendem em euro). Se a sua loja vende em outra moeda, informe o valor de 1 unidade da moeda da Sameday na moeda da sua loja, por exemplo 0.20. A taxa deve ser maior que 0. Sem ela, a estimativa não é usada e vale a tabela de preços. O lev e o euro são convertidos automaticamente pela taxa fixa.

Table price: Per order cobra o preço uma vez. Per item (price x quantity) o multiplica pela quantidade de itens. Isso vale para o preço da tabela e para o custo de contingência. A estimativa da Sameday é sempre para o pacote inteiro.

Country prices: um preço por país de destino e peso do pacote. Clique em Add country para adicionar uma linha e no botão de remover para excluir uma. Cada linha tem uma coluna Price e colunas de peso: XS até 1 kg, S 1-2 kg, M 2-3 kg, L 3-5 kg e XL acima de 5 kg. Uma coluna de peso deixada em 0 ou vazia usa a coluna Price. A linha * Default vale para países sem linha própria. Uma nova linha começa como * Default com todos os preços em 0, o que significa frete grátis. Escolha o país e informe os preços antes de salvar, ou remova a linha. Se o mesmo país estiver em duas linhas, ao salvar só a primeira é mantida, e um aviso informa isso. Se uma célula não for um número igual ou maior que 0, a tabela não é salva.

Fallback cost: usado quando não há estimativa da Sameday e a tabela do país não tem linha para o destino. Deixe vazio para não oferecer o método nesse caso.

Free shipping from: o subtotal do carrinho (produtos que precisam de envio, após descontos, sem impostos) a partir do qual a entrega easybox é grátis. Quando o subtotal o atinge, o método é oferecido sem custo e nenhum preço é consultado. Deixe vazio para nunca oferecer frete grátis.

Disponibilidade

Minimum weight (kg): oculta o método quando o carrinho pesa menos. O peso é convertido a partir da classe de peso dos produtos. Vazio ou 0 significa sem limite.

Maximum weight (kg): pacotes mais pesados que isso não recebem entrega easybox. Padrão: 30. Confira o limite do seu contrato Sameday e os tamanhos das caixas easybox. Vazio ou 0 significa sem limite. Um peso mínimo acima do máximo não é salvo: um aviso informa isso e os valores anteriores são mantidos.

Minimum cart subtotal: ofereça o método somente quando o subtotal do carrinho (produtos que precisam de envio, após descontos, sem impostos) atingir este valor. Vazio significa sem mínimo.

Geo zone: ofereça o método 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. Não é verificada quando Ignore shipping zones está ativado.

Ignore shipping zones: quando ativado, a zona geográfica não é verificada e o método é oferecido para os países selecionados abaixo (o país da Sameday se a lista estiver vazia). Quando desativado, vale somente a zona geográfica acima.

Countries (ignore zones mode): os países de destino para esse modo. Países diferentes do país da Sameday são ignorados, e a página avisa sobre eles. Este campo só é usado quando Ignore shipping zones está ativado.

Lockers easybox

Locker list: mostra quantos lockers easybox em quantas cidades estão carregados e quando. Refresh the locker list now carrega de novo. A lista é atualizada ao salvar as configurações e, quando tem mais de um dia, após uma requisição da finalização de compra (no máximo uma vez por hora). Para uma atualização diária fixa, chame uma vez por dia a URL mostrada aqui por um cron do seu servidor. No OpenCart 3, a URL tem este formato: https://your-store/index.php?route=extension/shipping/vfd_sameday_easybox/cron&token=(token), no OpenCart 4, este: https://your-store/index.php?route=extension/vfd_sameday_easybox/shipping/vfd_sameday_easybox.cron&token=(token). Copie a URL exatamente como as configurações a mostram. A URL contém um token secreto. Sem o token correto, ela responde com erro e não contata a Sameday. Também não faz nada enquanto o método estiver desativado.

Counties: mostra quantos condados o OpenCart tem para o seu país Sameday. Se não tiver nenhum, clique em Add counties. A extensão adiciona os condados desse país em System > Localisation > Zones, e o campo Region / State do formulário de endereço passa a listá-los. Condados já existentes não são adicionados de novo. No OpenCart 4.1 os condados dos três países já existem, então o botão não é necessário ali.

Avançado

Debug log: grava os cálculos de tarifas, as chamadas à API e as escolhas de lockers em storage/logs/vfd_sdeb_debug.log.php, que não pode ser lido pela web. Erros da API são sempre registrados. Nenhuma senha, token ou dado pessoal do cliente é registrado. Quando o arquivo chega a 5 MB, um novo log é iniciado. Desative o log quando terminar.

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 ativado, desinstalar a extensão apaga as configurações, os dados em cache da Sameday e o log. Quando desativado (padrão), as configurações são mantidas. A lista de lockers e os caches são sempre removidos. O locker salvo nos pedidos é sempre mantido.

Importação / Exportação

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

Import: cole um JSON exportado anteriormente e clique em Import. Os valores passam pelas mesmas verificações do formulário. A senha 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 entrega easybox da Sameday. A extensão verifica a zona geográfica (ou os países de Ignore shipping zones), o país de entrega da sua conta Sameday, as credenciais da API e uma lista de lockers utilizável, o peso do carrinho e o subtotal mínimo. Somente produtos com Requires Shipping definido como Yes contam. O subtotal é o preço desses produtos sem impostos, após o desconto do cupom. Se o frete grátis se aplicar, o cliente vê o método sem custo.

Caso contrário, a extensão pede uma estimativa à Sameday, depois que o cliente informa uma cidade e um condado. Envia o seu ponto de coleta e serviço, o peso do pacote e o endereço do cliente (rua, cidade, condado e CEP). Nome, e-mail ou telefone não são enviados. Bucareste é enviada como "Sector 1", como o plugin oficial da Sameday. A estimativa é convertida para a moeda da sua loja. Se não houver estimativa (não configurada, ainda sem cidade ou condado, erro, sem taxa de câmbio), o preço vem da tabela do país e, depois, do custo de contingência. Se não houver preço, o método fica oculto. O preço é mostrado na moeda do cliente com o imposto da Tax class selecionada.

Problemas da Sameday nunca interrompem a finalização de compra. A estimativa fica em cache por 1 hora. Um erro fica em cache por 10 minutos. Após um timeout ou um erro do servidor, nenhuma estimativa é solicitada por 5 minutos. As requisições expiram em 15 segundos. Durante a finalização de compra, a lista de lockers é lida do seu servidor, não da Sameday.

A extensão não cria AWBs (remessas), não imprime etiquetas, não rastreia pacotes e não trata de pagamento na entrega. Não há entrega domiciliar por courier nem widget de mapa da Sameday. Crie o AWB no portal eAWB da Sameday ou na sua ferramenta habitual, com o ID do locker mostrado no pedido.

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

Pontos de coleta

Quando o cliente seleciona o método, aparece abaixo dele um bloco easybox locker com duas listas: - Select city - e - Select easybox locker -. A cidade do endereço de entrega vem pré-selecionada quando tem lockers. Cada locker mostra o nome e o endereço. A escolha é salva na hora para a finalização de compra, então continua lá se a etapa de entrega for aberta de novo.

O locker é obrigatório. Sem um, o cliente não consegue continuar e vê "Please choose a Sameday easybox locker.". Quando o cliente clica em Continue, o servidor verifica se o locker escolhido está na lista. Um ID de locker falsificado ou removido é recusado com "The selected easybox locker is not available any more. Please choose another easybox locker.". Se a lista não puder ser carregada, o cliente vê "The easybox lockers could not be loaded. Please try again in a moment or choose another shipping method.". O nome e o endereço salvos com o pedido vêm da lista, não do navegador.

Páginas do pedido, e-mails e nota fiscal: o locker é acrescentado ao método de envio do pedido, por exemplo "Sameday easybox: nome - endereço" (primeiro o nome do método, depois o locker). O cliente vê isso na confirmação do pedido, no histórico de pedidos e nos e-mails do pedido, e você vê na nota fiscal.

Página do pedido no admin: em Sales > Orders, a página do pedido tem um painel Sameday easybox locker com nome, endereço e o Locker ID para o AWB da Sameday. Se um pedido easybox não tiver locker, o painel diz "No easybox locker was selected for this order.". O painel também aparece enquanto o método estiver desativado.

No OpenCart 4, o bloco easybox locker aparece na janela Shipping method options, abaixo da opção Sameday easybox, e a lista de cidades é carregada de novo sempre que a janela é aberta, porque o endereço pode mudar na finalização de compra em uma página. O botão Continue da janela não avança sem um locker 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 locker do pedido é atualizado junto. O painel da página do pedido no admin é mostrado acima da seção History.

Chave de licença

A extensão funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença License — VibeFox Sameday Easybox é o primeiro bloco de Extensions > Extensions > Shipping > VibeFox Sameday Easybox > 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 de novo, Change key para informar outra chave e Remove key para remover a chave desta loja. Abaixo ficam a linha Product: opencart-shipping-sameday-easybox e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do admin (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 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 seu slot de domínio. Libere o slot na sua conta vibefox.net.

Sem uma chave ativa, o método de envio Sameday easybox não é mostrado aos clientes na finalização de compra, e nenhum preço é consultado ou calculado. Um administrador conectado ao admin no mesmo navegador ainda vê o método na loja, marcado 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 enxerga o login do admin, então, sem uma chave ativa, o método fica oculto para todos. Depois que você abrir a página Edit uma vez, aparece um lembrete no Dashboard do admin. 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 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 informada, depois uma vez por semana. Não é preciso nenhum cron. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

O Sameday easybox não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, se o nome de usuário e a senha da API estão informados e se a página de configurações diz "Connected to Sameday", e se o país de destino é o país da sua conta Sameday. Verifique se há um preço disponível (estimativa da Sameday, linha do país, linha * Default ou Fallback cost), os limites de peso e subtotal, Geo zone e os países de Ignore shipping zones. Verifique se os produtos têm Requires Shipping definido como Yes. Ative o Debug log para ver o motivo no campo Log.

A Sameday recusou o nome de usuário ou a senha da API: confira e salve de novo. As credenciais de demonstração só funcionam com Test mode ligado; as de produção, só com ele desligado. Até lá, a lista de lockers salva é oferecida, se houver, e a estimativa da Sameday não é usada.

O preço vem da minha tabela, não da Sameday: a estimativa precisa de um Pickup point, do Easybox service, de condados para o seu país Sameday e, se a moeda da loja for diferente da moeda da Sameday, do Exchange rate of the estimate. Ela só é solicitada depois que o cliente informa uma cidade e um condado. Quando a Sameday está inacessível ou devolve erro, a tabela ou o custo de contingência é usado; o motivo está no log.

A lista de lockers está antiga ou ausente: clique em Refresh the locker list now ou salve as configurações. Se uma atualização falhar, a lista anterior é usada e o status informa isso.

O frete está grátis por engano: confira Free shipping from e as linhas de Country prices com Price igual a 0, especialmente uma linha * Default adicionada com Add country e deixada sem preencher.

Os limites de peso ou as colunas de peso não batem: se a página avisar que não há classe de peso com a unidade "kg", adicione uma classe de peso em quilogramas em System > Localisation > Weight Classes.

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

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Sameday Easybox. 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. A lista de lockers salva, o resultado da verificação da conta e todos os caches são sempre removidos. Se Remove data on uninstall estiver ativado, as demais configurações, o token de cron e o log também são apagados. Se estiver desativado, são mantidos e usados de novo quando você reinstalar a extensão. Os pedidos existentes mantêm o locker salvo.

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 Sameday Easybox na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

Sameday e easybox são marcas comerciais de seus respectivos proprietários. Esta extensão não é afiliada nem endossada pela Sameday.