VibeFox ShipStation 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.
Conta da ShipStation: conecte suas transportadoras na ShipStation (Settings > Shipping > Carriers) e, em seguida, copie a API Key e a API Secret em ShipStation > Settings > Account > API Settings. O acesso à API depende do seu plano da ShipStation. Se a página não estiver disponível, o seu plano não inclui acesso à API. O módulo usa a API V1 da ShipStation (API Key e API Secret). Contas da ShipStation API V2 com uma única chave de API não são compatíveis. Sem as chaves, só são usados os preços de reserva.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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 envio terminar, clique em Configure ou, depois, encontre VibeFox ShipStation na lista de módulos e clique em Configure.
3. Insira a sua chave de licença VibeFox em License key no bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Cole a API Key e a API Secret, informe o CEP de origem e clique em Save. A página passará a listar os códigos de transportadora da sua conta. Informe o(s) que quiser em Carrier codes e salve novamente.
5. Se a moeda padrão da sua loja não for a moeda da sua conta da ShipStation, defina Exchange rate.
6. Opcionalmente, preencha os preços de reserva.
Na instalação, o módulo cria a transportadora ShipStation Shipping com o texto de prazo de entrega ShipStation carriers (USPS, UPS, FedEx, ...). A transportadora é atribuída a todas as zonas e a todos os grupos de clientes. Você pode alterar zonas, grupos de clientes, prazo de entrega, logotipo e limites de tamanho 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 do módulo: Modules > Module Manager > VibeFox ShipStation > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Cada salvamento limpa o cache das tarifas da ShipStation e verifica a API Key e a API Secret. Depois, a página mostra as transportadoras conectadas à sua conta com os respectivos códigos, por exemplo "stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)".
Os avisos no topo da página informam quando as tarifas em tempo real não podem funcionar: falta de chaves, falta de código de transportadora, falta de CEP de origem, taxa de câmbio ausente, falha na verificação da conexão ou códigos de transportadora não conectados à sua conta. Também aparece um aviso quando a unidade de peso ou de dimensão da loja é uma que o módulo não consegue converter. Defina kg, g, lb ou oz e cm, mm, m ou in em International > Localization (Local units). Um campo numérico com valor negativo ou com texto que não é número, ou um Minimum weight acima do Maximum weight, é informado como erro e nada é salvo.
Geral
Enable ShipStation shipping: liga ou desliga a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Name: o nome da transportadora exibido ao cliente na finalização de compra. Padrão: ShipStation Shipping. Obrigatório, no máximo 64 caracteres.
Tax: a regra de imposto da transportadora, ou No tax. As tarifas da ShipStation não incluem imposto sobre vendas. No tax as exibe como cotadas; uma regra de imposto acrescenta imposto ao frete conforme as suas regras fiscais.
Conta da ShipStation
API Key: a API Key de ShipStation > Settings > Account > API Settings. Ela é enviada somente à ShipStation e nunca é registrada em log. Após salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas para alterá-la.
API Secret: a API Secret da mesma página. Ela é tratada da mesma forma que a chave.
Remove the saved API key and secret: aparece quando as chaves estão salvas. Marque e salve para remover as duas.
Carrier codes: um ou mais códigos de transportadora da ShipStation, separados por vírgula, por exemplo stamps_com, ups_walleted. São usados até 5 códigos, com uma requisição à API por transportadora. Se você informar mais, apenas os 5 primeiros são mantidos, e a página avisa. É exibida a tarifa mais barata dessas transportadoras. Pegue os códigos na lista exibida após salvar.
Allowed services: opcional, códigos de serviço da ShipStation separados por vírgula, por exemplo usps_priority_mail, ups_ground. Deixe vazio para exibir o serviço mais barato das transportadoras indicadas acima.
Package code: "package" (padrão) cota a sua própria caixa e deixa de fora os envelopes e as caixas de taxa fixa da transportadora. Deixe vazio para cotar todos os tipos de pacote que a transportadora oferece.
Origem do envio
Ship-from postal code: obrigatório para tarifas em tempo real. A ShipStation calcula a tarifa somente a partir do CEP, e ele deve estar no país da sua conta da ShipStation. Deixe vazio para usar o CEP da loja em Shop Parameters > Contact > Stores.
Tarifas
Parcels: como o carrinho é enviado à ShipStation.
ShipStation account currency: a moeda em que a ShipStation devolve as tarifas: USD, CAD, GBP, AUD, NZD ou EUR. Padrão: USD (contas dos EUA).
Exchange rate: o preço de 1 unidade da moeda da conta na moeda padrão da sua loja, por exemplo 0.92. É necessário somente quando a moeda padrão é diferente da moeda da conta. Sem ele, as tarifas em tempo real não são usadas e valem os preços de reserva. As taxas de câmbio não são atualizadas automaticamente.
Preços de reserva (usados quando não há tarifa em tempo real: sem chaves de API, ShipStation inacessível, nenhuma tarifa de transportadora para o endereço; preços na moeda padrão da sua loja; deixe a tabela e Other countries vazios para ocultar a transportadora nesse caso)
Prices by country: uma tabela com um preço base por país e colunas de tamanho conforme o peso do pacote: XS ≤ 1 kg, S ≤ 2 kg, M ≤ 3 kg, L ≤ 5 kg e XL > 5 kg. Clique em Add country para adicionar uma linha e no ícone da lixeira para removê-la. Um tamanho vazio usa o preço base. Um preço base de 0 significa frete grátis. A linha * Default (all other countries) vale para os países que não têm linha própria. Uma linha sem nenhum preço não é salva.
Other countries: o preço quando a tabela não tem preço para o país. Deixe vazio para ocultar a transportadora nesse caso.
Condições
Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual o frete é grátis. Nesse caso, nenhuma requisição é feita à ShipStation. Deixe vazio para desativar.
Minimum subtotal: exibe a transportadora somente se o subtotal do carrinho (após descontos, antes dos impostos) for pelo menos este valor. Deixe vazio para exibi-la sempre.
Minimum weight: o peso mínimo do carrinho, na unidade de peso da sua loja, para exibir a transportadora. 0 significa sem limite.
Maximum weight: a transportadora é ocultada acima deste peso do carrinho, na unidade de peso da sua loja. 0 significa sem limite.
Disponibilidade sem zonas de envio
Normalmente, a transportadora é oferecida nas suas zonas em Shipping > Carriers. Como alternativa, ela pode ser oferecida por país.
Ignore shipping zones: oferece a transportadora para os países indicados abaixo, esteja ou não atribuída a zona deles. Enquanto estiver ativa, a transportadora é adicionada a todas as zonas, inclusive às criadas depois. Ao desativar, as zonas adicionadas são removidas.
Countries: os países de destino para este modo. Deixe vazio para usar todos os países ativos da loja. Este campo só é usado quando Ignore shipping zones está ativo.
Avançado
Debug log: registra as requisições à ShipStation em logs/vfd_shst_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros da API são sempre registrados, mesmo com esta opção desativada. A API Key, a API Secret e os endereços dos clientes nunca são registrados. O CEP é mascarado.
Log: mostra o tamanho e as últimas entradas do registro. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativo, desinstalar o módulo apaga as configurações, a transportadora, o registro e o serviço da ShipStation salvo nos pedidos. Quando desativado, tudo é mantido para uma reinstalação.
Como funciona na finalização de compra
Na etapa de envio, o PrestaShop pede ao módulo o preço. Só os produtos físicos contam: os produtos virtuais não acrescentam peso e não entram no subtotal. O módulo 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, a transportadora é exibida com preço 0 e nenhuma requisição é enviada à ShipStation.
Em seguida, o módulo envia à ShipStation o CEP de origem, o país de destino, o estado, a cidade e o CEP, o peso do pacote e o tamanho da caixa. Nenhuma requisição é feita antes de o cliente informar um CEP. Países sem CEP recebem os preços de reserva. Os itens são empilhados em uma caixa. Se um produto não tiver dimensões, o pacote é cotado apenas pelo peso.
A ShipStation é consultada uma vez por código de transportadora. O módulo usa a tarifa permitida mais barata, convertida para a moeda padrão da sua loja. Em seguida, o preço é exibido na moeda do carrinho do cliente.
Cada resposta fica em cache por 1 hora. Quando a ShipStation responde sem uma tarifa utilizável, a resposta é lembrada por 10 minutos. Quando a ShipStation rejeita as chaves ou está inacessível, as requisições são pausadas por 5 minutos. Após um limite de requisições, a pausa segue o horário de reinício informado pela ShipStation. O tempo limite da requisição é de 12 segundos. Desativar o módulo limpa as tarifas em cache.
Se não houver tarifa em tempo real, o preço vem da tabela de preços de reserva e, depois, de Other countries. Se nenhum deles se aplicar, a transportadora é ocultada. O cliente nunca vê mensagens de erro da ShipStation. Os detalhes vão para o registro de depuração.
Se você editar a transportadora em Shipping > Carriers depois que ela tiver pedidos, o PrestaShop a salva como uma nova versão da transportadora. O módulo segue a nova versão automaticamente.
O módulo calcula apenas tarifas. Ele não compra etiquetas, não cria pedidos ou remessas na ShipStation, não rastreia pacotes e não trata devoluções. Não há pontos de retirada, nem escolha entre vários serviços na finalização de compra, nem validação de endereço, seguro, confirmação de assinatura, embalagem em vários pacotes ou markup sobre as tarifas.
Pedidos
Quando um pedido é feito com uma tarifa em tempo real da ShipStation, o serviço escolhido é salvo com o pedido. A página do pedido no back office o exibe em um bloco ShipStation como Service, por exemplo "USPS Ground Advantage - Package", para que você crie a etiqueta correspondente na ShipStation. Recálculos posteriores do carrinho não o alteram. Pedidos feitos com preço de reserva ou frete grátis não têm bloco de serviço.
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 ShipStation é o primeiro bloco da página Modules > Module Manager > VibeFox ShipStation > 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 ficam a linha Product: presta-shipping-shipstation 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 de alterar o endereço da loja, 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, o módulo continua funcionando com o último status conhecido.
Uma chave funciona em um único 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 na sua conta vibefox.net.
Sem uma chave ativa, a transportadora da ShipStation não é exibida aos clientes na finalização de compra e nenhuma tarifa é calculada. A loja PrestaShop não sabe que você está conectado ao back office, então a transportadora também fica oculta para você: é possível 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 precisam de renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia durante os primeiros 14 dias após a inserção da chave, depois uma vez por semana. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A ShipStation não aparece na finalização de compra: verifique se a licença está ativa e se Enable ShipStation shipping está ligado. 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 e verifique Countries. Confira os limites de peso e o Minimum subtotal. Sem tarifa em tempo real, confirme que o país, * Default ou Other countries tem um preço. Além disso, os produtos podem ser limitados a determinadas transportadoras na página do produto.
A finalização de compra mostra o preço de reserva em vez da tarifa da ShipStation: verifique os avisos no topo da página do módulo (chaves, código de transportadora, CEP de origem, taxa de câmbio). Ative o Debug log, recarregue a finalização de compra e veja o campo Log. O CEP do cliente é obrigatório. Nenhuma requisição é feita antes de ele ser informado.
Qual código de transportadora informar: salve as configurações com a chave e o secret. A página lista os códigos de transportadora da sua conta. Use um ou mais deles.
A verificação de conexão com a ShipStation falhou: a mensagem mostra o motivo. Verifique a API Key e a API Secret e salve novamente para repetir a verificação.
A tarifa é diferente da ShipStation: o pacote é montado a partir dos pesos e das dimensões dos produtos, com os itens empilhados em uma caixa. Produtos sem dimensões são cotados apenas pelo peso. As tarifas ficam em cache por 1 hora. Clique em Save na página do módulo para limpar o cache.
A página informa que a transportadora da ShipStation não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para recriá-la.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox ShipStation e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. O cache de tarifas e o resultado da verificação de conexão são sempre removidos. Se Remove data on uninstall estiver ativo, a transportadora é excluída (os pedidos mantêm o histórico), e as configurações, o registro e o serviço salvo nos pedidos são removidos. Se estiver desativado, a transportadora apenas é desativada, e as configurações e o serviço dos pedidos realizados são mantidos. Reinstalar o módulo ou fazer um Reset devolve à transportadora o status que ela tinha antes.
A ShipStation é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado à ShipStation nem endossado por ela.