VibeFox ShipStation for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e superior (testado na versão 4.1.0.3).
PHP: 8.0 ou superior.
Conta do ShipStation: conecte suas transportadoras no ShipStation (Settings > Shipping > Carriers) e depois copie a API Key e a API Secret em ShipStation > Settings > Account > API Settings. O acesso à API depende do seu plano do ShipStation. A extensão usa a API V1 do ShipStation (API Key e API Secret). Sem as chaves, apenas os preços de reserva são usados.
Chave de licença do 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_shipstation-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_shipstation.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 administrador, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_shipstation-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 e escolha o tipo de extensão Shipping. Localize VibeFox ShipStation e clique em Install (o botão verde +).
3. Clique em Edit (o botão com o lápis) para abrir a página de configurações.
4. Insira sua chave de licença do 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. Cole a API Key e a API Secret, informe o CEP de origem e clique em Save. A página agora lista os códigos de transportadora da sua conta. Digite o(s) que você quer em Carrier codes e salve novamente.
6. Se a moeda padrão da sua loja não for a moeda da sua conta do ShipStation, defina a Exchange rate. Opcionalmente, preencha os preços de reserva.
7. Ative Enable ShipStation shipping e clique em Save.
OpenCart 4
1. No administrador, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_shipstation.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. Localize VibeFox ShipStation, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).
4. Insira a chave de licença e as configurações como nos passos 4 a 7 do OpenCart 3. A página de configurações e os campos são iguais nas duas versões.
Depois da instalação, o método fica desativado até que você o ative e salve. Se você reinstalar a extensão após uma desinstalação, as configurações do ShipStation 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 ShipStation > Edit. As seções ficam listadas à esquerda. Um único botão Save salva a página inteira sem recarregá-la. Cada salvamento limpa as tarifas do ShipStation em cache e verifica a API Key e a API Secret. A página então mostra as transportadoras conectadas à sua conta com seus códigos, por exemplo "stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)". Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações.
Avisos no topo da página informam quando as tarifas em tempo real não podem funcionar: sem chaves, sem código de transportadora, sem CEP de origem, sem taxa de câmbio, verificação de conexão com falha ou códigos de transportadora que não estão conectados à sua conta. Um aviso também aparece quando a unidade de peso ou de comprimento da loja é uma que a extensão não consegue converter. Use kg, g, lb ou oz e cm, mm, m ou in (System > Settings > Option). Um nome inválido, um campo numérico ou uma célula de preço com valor negativo ou com texto em vez de número, um Minimum weight maior que o Maximum weight ou uma ordem de classificação que não seja um número inteiro são informados como erro, e nada é salvo.
Geral
Enable ShipStation shipping: mostra ou oculta o método na finalização de compra. Este é o status da extensão em Extensions > Extensions > Shipping.
Name: o nome do método de envio mostrado ao cliente na finalização de compra. Padrão: ShipStation Shipping. Obrigatório, no máximo 64 caracteres, sem os caracteres < > ; = # { }.
Tax class: a classe de imposto do custo de envio, ou No tax. As tarifas do ShipStation não incluem imposto sobre vendas. No tax as mostra como cotadas; uma classe de imposto acrescenta imposto sobre o envio de acordo com as suas regras fiscais.
Sort order: a posição do método entre os métodos de envio na finalização de compra. Um número inteiro.
Conta do ShipStation
API Key: a API Key de ShipStation > Settings > Account > API Settings. Ela é enviada somente ao ShipStation e nunca é registrada em log. Depois de salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo somente 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 depois que as chaves são salvas. Marque e salve para remover as duas.
Carrier codes: um ou mais códigos de transportadora do 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 você. É mostrada a tarifa mais barata dessas transportadoras. Pegue os códigos na lista exibida após salvar.
Allowed services: opcional, códigos de serviço do ShipStation separados por vírgula, por exemplo usps_priority_mail, ups_ground. Deixe vazio para mostrar o serviço mais barato das transportadoras acima.
Package code: "package" (o padrão) calcula as tarifas para a sua própria caixa e deixa de fora os envelopes e as caixas de tarifa fixa da transportadora. Deixe vazio para calcular as tarifas de todos os tipos de pacote que a transportadora oferece.
Envio a partir de
Ship-from postal code: obrigatório para as tarifas em tempo real, por exemplo 78703. O ShipStation calcula as tarifas somente pelo CEP, que deve estar no país da sua conta do ShipStation. O OpenCart não tem CEP de loja, então ele nunca é obtido do endereço da loja.
Tarifas
Parcels: como o carrinho é enviado ao ShipStation.
ShipStation account currency: a moeda em que o ShipStation retorna 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. Só é necessária quando a moeda padrão é diferente da moeda da conta. Sem ela, 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 ou sem tarifas de transportadora para o endereço; preços na moeda padrão da sua loja; deixe a tabela e Other countries vazios para ocultar o método nesse caso)
Prices by country: uma tabela com um preço Base por país e colunas de tamanho por peso do pacote: XS até 1 kg, S até 2 kg, M até 3 kg, L até 5 kg e XL acima de 5 kg. Clique em Add country para adicionar uma linha. Um tamanho vazio usa o preço base. Um preço base de 0 significa frete grátis. A linha * Default (all other countries) se aplica aos países sem 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 o método nesse caso.
Condições
Free shipping from: o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) a partir do qual o frete é grátis. Nesse caso, nenhuma requisição é feita ao ShipStation. Deixe vazio para desativar.
Minimum subtotal: mostrar o método somente se o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) for pelo menos este valor. Deixe vazio para sempre mostrar.
Minimum weight: o peso mínimo do carrinho, na unidade de peso da sua loja (indicada no nome do campo), para mostrar o método. 0 significa sem limite (padrão).
Maximum weight: o método fica oculto acima deste peso do carrinho, na unidade de peso da sua loja. 0 significa sem limite (padrão).
Disponibilidade
Geo zone: oferecer o método somente para endereços desta zona geográfica. All zones (padrão) significa sem limite. Não é verificada enquanto Ignore shipping zones estiver ativado. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.
Ignore shipping zones: oferecer o método para os países listados abaixo, independentemente da zona geográfica.
Countries: os países de destino para esse modo. Deixe vazio para usar todos os países ativados na loja. Este campo só é usado quando Ignore shipping zones está ativado.
Avançado
Debug log: registra as requisições ao ShipStation em storage/logs/vfd_shst_debug.log.php (no OpenCart 4, system/storage/logs/vfd_shst_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. A API Key, a API Secret e os endereços dos clientes nunca são registrados. O CEP é mascarado. Quando o arquivo chega a 5 MB, ele é movido para vfd_shst_debug.old.log.php e um novo log é iniciado.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativado, desinstalar a extensão apaga as configurações do ShipStation e o log. Quando desativado (padrão), elas são mantidas para uma reinstalação. As tarifas em cache são sempre removidas. O serviço do ShipStation dos pedidos já feitos é sempre mantido.
Importação / Exportação
Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A API Key e a API Secret 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. A API Key e a API Secret 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 do ShipStation. Se uma Geo zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, o método não é oferecido. Somente produtos com Requires Shipping definido como Yes contam: os demais não adicionam peso e não entram no subtotal. Em seguida, a extensão verifica as condições: países permitidos (com Ignore shipping zones), peso do carrinho e subtotal mínimo. Vale-presente, pontos de fidelidade e crédito da loja não são considerados. Se o frete grátis se aplicar, o método é mostrado com preço 0 e nenhuma requisição é enviada ao ShipStation.
A extensão então envia ao ShipStation o CEP de origem, o país de destino, o código do 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 é tarifado apenas pelo peso.
O ShipStation é consultado uma vez por código de transportadora. A extensão usa a tarifa permitida mais barata, convertida para a moeda padrão da sua loja e arredondada para as casas decimais dela. O preço é então mostrado na moeda do cliente com o imposto da Tax class selecionada.
Cada resposta fica em cache por 1 hora. Quando o ShipStation responde sem uma tarifa utilizável, a resposta é lembrada por 10 minutos. Quando o ShipStation rejeita as chaves ou está inacessível, as requisições são pausadas por 5 minutos. Depois de um limite de requisições, a pausa segue o horário de reset informado pelo ShipStation. O tempo limite da requisição é de 12 segundos.
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 dos dois se aplicar, o método fica oculto. O cliente nunca vê textos de erro do ShipStation. Os detalhes vão para o log de depuração.
A extensão calcula apenas tarifas. Ela não compra etiquetas, não cria pedidos ou remessas no 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 nem acréscimo sobre as tarifas.
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 ShipStation na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.
Pedidos
Quando um pedido é feito com uma tarifa em tempo real do ShipStation, o serviço escolhido é salvo com o pedido. Abra o pedido em Sales > Orders: o painel ShipStation, acima do histórico do pedido, mostra o serviço como Service, por exemplo "USPS Ground Advantage - Package", para que você crie a etiqueta correspondente no ShipStation. No modo por item, os serviços aparecem separados por vírgula. Alterações posteriores no carrinho não o modificam, e o painel continua sendo exibido mesmo depois de você desativar o método. Pedidos feitos com preço de reserva ou frete grátis não têm painel do ShipStation.
O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza sempre que o cliente confirma novamente. O serviço do ShipStation salvo é atualizado junto com ele. Se o cliente mudar para outro método de envio, ou se agora valer o preço de reserva, o serviço salvo é removido do pedido.
Chave de licença
A extensão funciona com uma chave de licença do VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox ShipStation é o primeiro bloco da página Extensions > Extensions > Shipping > VibeFox ShipStation > Edit, 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: opencart-shipping-shipstation e o link Manage licenses and domains in your account, que abre a sua conta em 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 administrador (inglês e russo estão incluídos).
Se a chave não for aceita, o bloco mostra 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 for alterado, 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 de domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, o ShipStation não é mostrado aos clientes na finalização de compra e nenhuma tarifa é calculada. Um usuário administrador conectado ao administrador 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 vê o login do administrador, então sem uma chave ativa o método fica oculto para todos. 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 de forma automática 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 nenhum cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.
Solução de problemas
O ShipStation não aparece na finalização de compra: verifique se a licença está ativa e se Enable ShipStation shipping está ligado. Confira Geo zone (ou, com Ignore shipping zones ligado, Countries), os limites de peso e o Minimum subtotal. Sem tarifa em tempo real, confira se o país, * Default ou Other countries tem um preço. Confira se os produtos têm Requires Shipping definido como Yes.
A finalização de compra mostra o preço de reserva em vez da tarifa do ShipStation: confira os avisos no topo da página da extensão (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 o ShipStation falhou: a mensagem mostra o motivo. Confira a API Key e a API Secret e salve novamente para repetir a verificação.
A tarifa é diferente da do ShipStation: o pacote é montado com os pesos e as dimensões dos produtos, com os itens empilhados em uma caixa. Produtos sem dimensões são tarifados apenas pelo peso. As tarifas ficam em cache por 1 hora. Clique em Save na página da extensão para limpar o cache.
A página mostra "Warning: You do not have permission to modify VibeFox ShipStation!": 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_shipstation (OpenCart 3) ou extension/vfd_shipstation/shipping/vfd_shipstation (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: o endereço da API do ShipStation pode ser substituído pela configuração vfd_shst_api_url (para testes); ela não tem campo 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 ShipStation. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable ShipStation shipping, Sort order, Tax class e Geo zone. As tarifas em cache e o resultado da verificação de conexão são sempre removidos. Se Remove data on uninstall estiver ativado, as configurações do ShipStation e o log de depuração também são apagados. Se estiver desativado, as demais configurações são mantidas e voltam a ser usadas quando você reinstalar a extensão. Os pedidos existentes mantêm o método de envio, o custo e o serviço do ShipStation.
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 ShipStation na lista de extensões instaladas, depois em Delete (o botão vermelho de lixeira) para remover o pacote enviado.
O ShipStation é uma marca registrada do seu respectivo proprietário. Esta extensão não é afiliada nem endossada pelo ShipStation.