VibeFox ShipStation for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

Conta da ShipStation: conecte suas transportadoras na 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 da ShipStation. Se a página não estiver disponível, o seu plano não inclui acesso à API. O plugin 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ão usados apenas 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 WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta vfd_shipstation para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox ShipStation, ou clique em Settings abaixo do nome do plugin na página de Plugins.

4. Digite a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Cole a API Key e a API Secret, informe o CEP de origem do envio e salve. A página passa a listar os códigos de transportadora da sua conta. Digite o(s) que você quiser em Carrier codes e salve novamente.

6. Se a moeda da sua loja não for a moeda da sua conta da ShipStation, defina o Exchange rate.

7. Opcionalmente, preencha os preços de reserva.

8. Adicione o VibeFox ShipStation a uma zona de envio em WooCommerce > Settings > Shipping > Shipping zones, ou ative Ignore shipping zones e escolha os países.

Configuração

Todas as configurações estão em uma única página: WooCommerce > Settings > Shipping > VibeFox ShipStation. Elas se aplicam a todas as zonas de envio. Quando você adiciona o método a uma zona, a janela da zona tem apenas um campo:

Title (zone): o nome que o cliente vê nesta zona. Deixe em branco para usar o Name global.

Toda vez que você salva as configurações, as tarifas da ShipStation em cache são apagadas e a API Key e a API Secret são verificadas. A página mostra então as transportadoras conectadas à sua conta, com seus códigos, por exemplo "stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)". Os avisos acima das configurações informam quando as tarifas em tempo real não podem funcionar: falta de chaves, de código de transportadora, de CEP de origem, de taxa de câmbio, falha na verificação da conexão ou códigos de transportadora que não estão conectados à sua conta.

Geral

Enable/Disable: ativa ou desativa o método em todas as zonas ao mesmo tempo.

Name: o nome do método de envio exibido na finalização de compra. Uma zona pode substituí-lo pelo seu próprio Title. Padrão: ShipStation Shipping.

Conta da ShipStation

API Key: a API Key de ShipStation > Settings > Account > API Settings.

API Secret: a API Secret da mesma página.

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. É 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 em branco para mostrar o serviço mais barato das transportadoras acima.

Package code: "package" (o padrão) calcula a tarifa para a sua própria caixa e deixa de fora os envelopes e as caixas de taxa fixa da transportadora. Deixe em branco para calcular todos os tipos de embalagem que a transportadora oferece.

Origem do envio

Ship-from postal code: obrigatório para as tarifas em tempo real. A ShipStation calcula as tarifas apenas a partir do CEP, que deve estar no país da sua conta da ShipStation. Deixe em branco para usar o CEP da loja definido em WooCommerce > Settings > General.

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 da sua loja, por exemplo 0.92. Só é necessário quando a moeda da loja é 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.

Tax status: Taxable permite que o WooCommerce adicione imposto sobre o envio de acordo com as suas regras fiscais; None não adiciona. As tarifas da ShipStation não incluem imposto sobre vendas.

Preços de reserva (usados quando não há tarifa em tempo real: sem API Keys, ShipStation inacessível ou nenhuma tarifa de transportadora para o endereço; preços na moeda da sua loja; deixe a tabela e Other countries em branco para ocultar o método 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 X para remover uma. 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 que não têm linha própria.

Other countries: o preço quando a tabela não tem preço para o país. Deixe em branco para ocultar o método nesse caso.

Condições

Free shipping from: o subtotal do carrinho a partir do qual o frete é grátis. Nesse caso, nenhuma requisição é feita à ShipStation. Deixe em branco para desativar.

Minimum subtotal: mostra o método somente se o subtotal do carrinho for pelo menos este valor. Deixe em branco para sempre mostrá-lo.

Minimum weight: o peso mínimo do carrinho, na unidade de peso da sua loja, para exibir este método. 0 significa sem limite.

Maximum weight: o método fica oculto acima deste peso do carrinho, na unidade de peso da sua loja. 0 significa sem limite.

Disabled shipping classes: oculta o método se o carrinho contiver um produto de uma destas classes de envio do WooCommerce.

Disponibilidade sem zonas de envio

Ignore shipping zones: oferece o método para os países abaixo, esteja ou não adicionado a uma zona.

Countries: os países de destino para esse modo. Deixe em branco para usar todos os países para os quais a loja envia. Este campo só é usado quando Ignore shipping zones está ativado. Um método adicionado a uma zona de envio sempre funciona para os países dessa zona.

Avançado

Debug log: registra as requisições à ShipStation em WooCommerce > Status > Logs, origem vfd-shipstation. Erros de 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.

Remove data on uninstall: quando ativado, ao excluir o plugin suas configurações e seus métodos nas zonas de envio são removidos. Desativar o plugin nunca apaga as configurações.

Como funciona na finalização de compra

Quando o cliente informa um endereço de entrega, o WooCommerce pede uma tarifa ao plugin. O plugin verifica primeiro as condições: peso do carrinho, subtotal mínimo e classes de envio desativadas. Se o frete grátis se aplicar, o método é exibido com preço 0 e nenhuma requisição é enviada à ShipStation.

Em seguida, o plugin envia à ShipStation o CEP de origem, o país de destino, o estado, a cidade e o CEP de destino, 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. Pesos e dimensões são convertidos a partir das unidades da sua loja. Os itens são empilhados em uma caixa. Se um produto não tiver dimensões, o pacote é calculado apenas pelo peso.

A ShipStation é consultada uma vez por código de transportadora. O plugin exibe a tarifa permitida mais barata, convertida para a moeda da sua loja, abaixo do nome do método.

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 plugin apaga as tarifas em cache.

Sem tarifa em tempo real, o preço vem da tabela de preços de reserva e, depois, de Other countries. Se nenhum desses se aplicar, o método fica oculto. O cliente nunca vê mensagens de erro da ShipStation. Os detalhes vão para o log do WooCommerce.

O método funciona na finalização de compra clássica e nos blocos de Carrinho e Finalização de compra. Ele é compatível com o High-Performance Order Storage do WooCommerce (HPOS).

O plugin 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, divisão em vários pacotes ou acréscimo sobre as tarifas.

Pedidos

A linha de envio do pedido armazena o Service escolhido, por exemplo "USPS Ground Advantage - Package". Você o vê na tela de pedido do administrador e pode criar a etiqueta correspondente na ShipStation.

Chave de licença

O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Shipping > VibeFox ShipStation. Cole a chave em License key e clique em Activate. O bloco exibe o status, por exemplo a data até a qual a licença está ativa, e o seu domínio. Use Check now para verificar o status novamente, Change key para digitar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta na vibefox.net.

Uma chave funciona em um único domínio. Remover a chave de um site não libera a vaga do domínio. Libere-a na sua conta vibefox.net.

Sem uma chave ativa, a ShipStation não é exibida para os clientes na finalização de compra. Gerentes da loja conectados ainda a veem, marcada como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um aviso aparece na página de Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática em segundo plano.

Solução de problemas

A ShipStation não aparece na finalização de compra: verifique se a licença está ativa, se o Enable/Disable está ativado e se o método foi adicionado à zona do país do cliente (ou se o Ignore shipping zones está ativado e o país é permitido). Confira os limites de peso, o Minimum subtotal e as Disabled shipping classes. Sem tarifa em tempo real, verifique se o país, o * Default ou o Other countries tem um preço.

A finalização de compra mostra o preço de reserva em vez da tarifa da ShipStation: confira os avisos no topo da página de configurações (chaves, código de transportadora, CEP de origem, taxa de câmbio). Ative o Debug log e abra WooCommerce > Status > Logs, origem vfd-shipstation. 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 a secret. A página lista os códigos de transportadora da sua conta. Use um ou mais deles.

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 calculados apenas pelo peso. As tarifas ficam em cache por 1 hora. Salve as configurações para limpar o cache.

Para desenvolvedores: os filtros vfd_shst_rate_request, vfd_shst_selected_rate e vfd_shst_api_url alteram a requisição de tarifa por transportadora, a tarifa escolhida e a URL base da API.

O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças estiver inacessível, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém as configurações e apenas limpa as tarifas em cache. Para removê-lo, desative e exclua-o na página Plugins. A chave de licença e o status da licença deste plugin, as tarifas em cache e a lista de transportadoras salva são sempre removidos. Configurações e métodos de zona são removidos somente se Remove data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação posterior. Os pedidos existentes mantêm suas linhas de envio.

ShipStation é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela ShipStation.