VibeFox Sameday Easybox for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo não é instalado em versões mais antigas do PHP.

Nome de usuário e senha da API Sameday: o acesso à API faz parte de uma conta empresarial da 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, a transportadora não é oferecida, porque o cliente não conseguiria escolher um locker.

Condados no formulário de endereço: a estimativa da Sameday precisa do condado do endereço de entrega. O PrestaShop não tem condados para Romênia, Hungria e Bulgária por padrão. O módulo pode adicioná-los para você (veja Lockers easybox abaixo). Sem eles, os preços vêm da sua tabela ou do custo de reserva.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.

Instalação

1. No back office, vá em Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.

2. Quando o upload terminar, clique em Configure, ou encontre depois VibeFox Sameday Easybox na lista de módulos e clique em Configure.

3. Insira sua chave de licença VibeFox em License key, no bloco de licença no topo da página de configuração, e clique em Activate (veja Chave de licença).

4. Insira seu API username e API password da Sameday, escolha o Sameday country e clique em Save. A página deve mostrar "Conectado à Sameday ... lockers easybox". O Pickup point e o Easybox service são preenchidos a partir da sua conta.

5. 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.

6. Se a página indicar que a loja não tem condados para o seu país Sameday, clique em Add counties na seção Lockers easybox.

Na instalação, o módulo cria a transportadora Sameday easybox com o texto de prazo de entrega Delivery to a Sameday easybox locker. Ela é atribuída a todos os grupos de clientes e à zona da Romênia. Você pode alterar zonas, grupos de clientes, prazo de entrega e logotipo em Shipping > Carriers. Não defina preços ali: o preço sempre vem do módulo.

Configuração

Todas as configurações estão na página Configure do módulo, em seis seções. O botão Save de qualquer seção salva a página inteira.

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 rejeitou 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, uma unidade de peso da loja que o módulo não reconhece, ou que a transportadora não foi encontrada.

Todos os preços e limites aceitam vírgula ou ponto como separador decimal (4,99 ou 4.99). Um número inválido ou negativo não é salvo: um aviso indica o campo e o valor anterior é mantido.

Geral

Enable/Disable: ativa ou desativa a transportadora. É o mesmo que o status da transportadora em Shipping > Carriers.

Name: o nome do método de envio mostrado ao cliente (o nome da transportadora). Padrão: Sameday easybox.

Tax status: None significa que o preço é final. Taxable com uma regra de imposto faz o PrestaShop acrescentar esse imposto de envio ao preço.

Conta Sameday (API)

Ao salvar, o módulo faz login 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 Sameday.

API password: sua senha da API Sameday. Ela nunca é mostrada novamente: deixe o campo vazio para manter a salva. Esvaziar o nome de usuário também remove a senha. Se a Sameday a rejeitar, 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). Seus lockers são oferecidos, e a transportadora só aparece para este país de destino. Ao alterá-lo, a transportadora também é vinculada à zona do novo país.

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

Preços

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 fim, o custo de reserva. 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 retira as encomendas. Após um login bem-sucedido, é uma lista dos pontos de coleta da sua conta, e o padrão é escolhido automaticamente. 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), escolhido automaticamente. Necessário para a estimativa da Sameday.

Exchange rate of the estimate: a Sameday faz a estimativa 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 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. Lev e euro são convertidos automaticamente pela taxa fixa.

Table price: Per order cobra o preço uma vez. Per item (price x quantity) multiplica pelo número de itens. Isso vale para o preço da tabela e para o custo de reserva. 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 ícone de lixeira para removê-la. Cada linha tem uma coluna Price e colunas de peso: XS até 1 kg, S de 1 a 2 kg, M de 2 a 3 kg, L de 3 a 5 kg e XL acima de 5 kg. Uma coluna de peso deixada em 0 usa a coluna Price. A linha * Default é usada 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 válido, 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 a transportadora 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 é atingido, a transportadora é oferecida sem custo e nenhum preço é consultado. Deixe vazio para nunca oferecer frete grátis.

Disponibilidade

Minimum weight (kg): oculta a transportadora quando o carrinho pesa menos. O peso é convertido a partir da unidade de peso da sua loja (kg, g, lb ou oz). Vazio ou 0 significa sem limite.

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

Minimum cart subtotal: ofereça a transportadora somente quando o subtotal do carrinho (produtos que precisam de envio, após descontos, sem impostos) atingir este valor.

Ignore shipping zones: quando ativado, a transportadora é oferecida para os países selecionados abaixo (o país Sameday se a lista estiver vazia), mesmo que a zona deles não esteja definida para a transportadora. A transportadora fica então vinculada a todas as zonas ativas, inclusive às criadas depois. Quando você desativa de novo, a transportadora recupera as zonas que tinha antes. Quando desativado, a transportadora só é oferecida nas suas zonas em Shipping > Carriers.

Countries (ignore zones mode): os países de destino para esse modo. Países diferentes do país 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 desde quando. Refresh the locker list now carrega a lista novamente. A lista é atualizada ao salvar as configurações e, quando tem mais de um dia, após uma solicitação de finalização de compra. Para uma atualização diária fixa, chame uma vez por dia a Cron URL mostrada aqui a partir de um cron job do seu servidor. A URL contém um token secreto. Sem o token, ela responde com erro e não contata a Sameday.

Counties: a estimativa da Sameday precisa do condado do endereço. Se o PrestaShop não tiver condados (states) para o seu país Sameday, clique em Add counties. O módulo adiciona os condados da Romênia, Hungria ou Bulgária e o campo de condado ao formulário de endereço desse país. Condados que já existem não são adicionados de novo. Quando estiverem no lugar, a página mostra a quantidade.

Avançado

Debug log: grava os cálculos de tarifas, as chamadas à API e as escolhas de locker no arquivo logs/vfd_sdeb_debug.log.php na pasta do módulo, que não pode ser lido pela web. Erros da API são sempre registrados. Nenhuma senha, token ou dado pessoal do cliente é registrado. O campo Log abaixo mostra o fim do arquivo, com um botão Clear log. Desative o log quando terminar.

Remove data on uninstall: quando ativado, desinstalar o módulo apaga as configurações e a transportadora. Sem ele, desinstalar apenas desativa a transportadora. A lista de lockers e os caches são sempre removidos. O locker salvo nos pedidos é sempre mantido.

Como funciona na finalização de compra

Quando a loja calcula o envio de um carrinho, o PrestaShop pede ao módulo o preço da transportadora Sameday easybox. O módulo verifica as condições: país de entrega da sua conta Sameday, credenciais da API e uma lista de lockers utilizável, os países de Ignore shipping zones, peso do carrinho e subtotal mínimo. Produtos que não precisam de envio (produtos virtuais) não são contados. Se o frete grátis se aplicar, o cliente vê a transportadora sem custo.

Caso contrário, o módulo pede à Sameday uma estimativa, depois que o cliente informa uma cidade e um condado. Ele envia o seu ponto de coleta e serviço, o peso do pacote e o endereço do cliente (rua, cidade, condado e CEP). Nenhum nome, e-mail ou telefone é enviado. Bucareste é enviada como "Sector 1", como faz o plugin oficial da Sameday. A estimativa é convertida para a moeda da sua loja. Se não houver estimativa (não configurada, sem cidade ou condado ainda, erro, sem taxa de câmbio), o preço vem da tabela do país e, depois, do custo de reserva. Se não houver preço, a transportadora fica oculta.

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 tempo limite ou erro do servidor, nenhuma estimativa é solicitada por 5 minutos. As requisições expiram após 15 segundos. A lista de lockers é lida do seu servidor, e não da Sameday, durante a finalização de compra.

A transportadora funciona na etapa de entrega do tema Classic (PrestaShop 8) e do tema Hummingbird (PrestaShop 9).

O módulo não cria AWBs (envios), não imprime etiquetas, não rastreia encomendas nem trata pagamento na entrega. Não tem 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.

Pontos de coleta

Quando o cliente seleciona a transportadora, aparece abaixo um bloco easybox locker com duas listas: - Select city - e - Select easybox locker -. A cidade do endereço de entrega é pré-selecionada quando tem lockers. Cada locker mostra seu nome e endereço. A escolha é salva no carrinho imediatamente, então ela permanece quando a etapa de entrega é atualizada ou a página é recarregada.

O locker é obrigatório. Sem um locker, o cliente não consegue continuar e vê "Escolha um locker easybox da Sameday." Quando o cliente clica em Continue, o servidor verifica se o locker escolhido está na lista. Um ID de locker forjado ou removido é recusado com "O locker easybox selecionado não está mais disponível. Escolha outro locker easybox." Se a lista não puder ser carregada, o cliente vê "Não foi possível carregar os lockers easybox. Tente novamente em instantes ou escolha outro método de envio." Nome e endereço salvos com o pedido vêm da lista, e não do navegador. Depois que o pedido é feito, o locker dele não muda mais.

Página do pedido no back office: um bloco Sameday easybox locker com nome, endereço e Locker ID para o AWB da Sameday. Se um pedido easybox não tiver locker, o bloco informa "Nenhum locker easybox foi selecionado para este pedido."

Páginas de confirmação e histórico de pedidos: Sameday easybox locker: com nome e endereço.

E-mails de pedido: o nome e o endereço do locker são adicionados à transportadora no e-mail de confirmação do pedido. O novo e-mail de pedido enviado à loja (módulo Mail alerts) também inclui o Locker ID.

Chave de licença

O módulo funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Sameday Easybox é o primeiro bloco em Modules > Module Manager > VibeFox Sameday Easybox > Configure, 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 novamente, Change key para inserir outra chave e Remove key para remover a chave desta loja. Abaixo aparecem a linha Product: presta-shipping-sameday-easybox e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente funcionários com a permissão Configure do módulo podem alterar a chave. Os textos do bloco seguem o idioma do back office (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, o módulo continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o domínio da loja principal, também em uma configuração multiloja. 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 transportadora Sameday easybox não é mostrada aos clientes na finalização de compra, e nenhum preço é solicitado ou calculado. A vitrine do PrestaShop não sabe que você fez login no back office, então a transportadora também fica oculta para você: você pode configurar o módulo antes de comprar uma chave, mas não testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: 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 o módulo sempre remove a chave de licença e o status da licença. Reset deste módulo não apaga dados, então a chave e o status são mantidos.

Solução de problemas

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 preenchidos, se a página de configuração mostra "Conectado à 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) e os limites de peso e subtotal. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente, ou ative Ignore shipping zones. Os produtos também podem ser limitados a certas transportadoras na página do produto. Ative o Debug log para ver o motivo no campo Log.

A Sameday rejeitou o nome de usuário ou a senha da API: confira e salve novamente. As credenciais de demonstração funcionam somente com Test mode ativado, e as de produção somente com ele desativado. 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 no formulário de endereço e, quando a moeda da sua loja é 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 retorna erro, usa-se a tabela ou o custo de reserva; o motivo está no log.

A lista de lockers está desatualizada 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. Se a loja estiver em modo de manutenção, a URL de cron é bloqueada como o restante da loja, a menos que o IP do servidor de cron esteja liberado.

O frete está grátis por engano: verifique Free shipping from e as linhas de Country prices com Price 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 a unidade de peso da loja não é conhecida, defina kg, g, lb ou oz em International > Localization (Local units).

A página diz que a transportadora Sameday easybox não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente. A redefinição mantém as configurações e o status de uma transportadora existente.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Sameday Easybox e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. 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, a transportadora é excluída (os pedidos mantêm o histórico) e as configurações e o log são removidos. Se estiver desativado, a transportadora é apenas desativada e todas as configurações são mantidas. Instalar o módulo novamente devolve à transportadora salva o status que ela tinha. Os pedidos existentes mantêm o locker salvo.

Sameday e easybox são marcas comerciais de seus respectivos proprietários. Este módulo não é afiliado nem endossado pela Sameday.