VibeFox Correos CityPaq for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

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

PHP: 8.0 ou superior.

Credenciais da API da Correos (somente para a lista ao vivo de armários): a lista CityPaq da Correos lê os armários ativos pela API "terminals" da Correos. No portal de desenvolvedores da Correos, abra a API "terminals" e use Request access para a sua aplicação. A Correos aprova as solicitações dos seus clientes empresariais e envia um client ID e um client secret. Eles também aparecem em My applications no portal. Se os clientes digitarem o armário por conta própria ou escolherem na sua lista, você não precisa de credenciais da API.

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_correos_citypaq para /wp-content/plugins/ por FTP.

2. Clique em Activate.

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

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

5. Preencha a tabela de preços e escolha como o cliente seleciona o armário (veja Configuração).

6. Adicione VibeFox Correos CityPaq à zona de envio da Espanha em WooCommerce > Settings > Shipping > Shipping zones, ou ative Ignore shipping zones.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Shipping > VibeFox Correos CityPaq. Elas valem para 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 desta opção na finalização de compra para esta zona. Deixe vazio para usar o Name global.

Os avisos acima das configurações informam quando a tabela de preços não tem nenhuma linha utilizável, quando a seleção de armário escolhida não pode funcionar (nenhum armário na sua lista, nenhuma credencial da API) e qual foi o último erro da API da Correos. Preços e valores aceitam vírgula ou ponto decimal.

Geral

Os armários CityPaq existem apenas na Espanha, por isso o método nunca é oferecido para outros países.

Enable/Disable: liga ou desliga o método em todas as zonas de uma vez.

Name: o nome do método de envio que o cliente vê na finalização de compra. Padrão: Correos CityPaq.

Tax status: Taxable adiciona o imposto do WooCommerce sobre os preços da tabela; None não adiciona.

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

Price table: uma linha para Spain (ES) e/ou uma linha padrão *. Cada linha tem um Price base e preços opcionais para os tamanhos de pacote XS (até 1 kg), S (até 2 kg), M (até 3 kg), L (até 5 kg) e XL (acima de 5 kg). Um preço de tamanho igual a 0 ou vazio usa o preço base. Clique em + Add row para adicionar uma linha e no X para remover uma. Informe as tarifas do seu contrato com a Correos na moeda da loja. Sem uma linha correspondente, o método fica oculto. Preços inválidos e linhas duplicadas são informados ao salvar.

Calculation type: como o tamanho do pacote é determinado.

Per order (size by the total cart weight): um preço para o carrinho inteiro, escolhido pelo peso total. Esta é a opção padrão.

Per item (size by each item weight, multiplied by quantity): cada produto recebe o preço do seu próprio tamanho, multiplicado pela quantidade, e os preços são somados.

Os pesos dos produtos são convertidos para kg a partir da unidade de peso da sua loja (kg, g, lbs ou oz).

Condições

Min weight (kg): oculta o método quando o carrinho é mais leve. 0 significa sem limite.

Max weight (kg): oculta o método quando o carrinho é mais pesado. Padrão: 30, porque o CityPaq aceita pacotes de até 30 kg. 0 significa sem limite.

Minimum order amount: mostra o método somente quando o subtotal do carrinho (após descontos, antes dos impostos) atinge este valor. Deixe vazio para sempre mostrar.

Excluded shipping classes: oculta o método quando o carrinho contém um produto de uma destas classes de envio do WooCommerce, por exemplo itens volumosos que não cabem em um armário. O plugin não verifica as dimensões dos pacotes.

Frete grátis

Free shipping: ativa a entrega grátis do CityPaq a partir do valor abaixo.

Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual este método custa 0. Usado somente quando Free shipping está ativo.

Seleção do armário CityPaq

Locker selection: como o cliente escolhe o armário antes de fazer o pedido. Padrão: o cliente informa o armário.

Customer chooses from the Correos CityPaq list (Correos API, credentials below): o cliente vê os armários CityPaq ativos do código postal do endereço de entrega e pode pesquisar outro código postal de 5 dígitos. Quando um código postal não tem armário, são listados os armários da mesma área e, depois, da mesma província, com os códigos postais mais próximos primeiro. Cada armário mostra nome, endereço, código postal, cidade e horário de funcionamento. Se a lista não puder ser carregada ou não encontrar nada, o cliente informa o armário manualmente.

Customer enters the locker (code or address from the Correos finder): um campo obrigatório para o código do armário (por exemplo S0000213D) ou o endereço, com um link para o localizador oficial CityPaq da Correos.

Customer chooses from my list of lockers (below): uma lista suspensa obrigatória com os armários de My lockers. Os armários perto do código postal do cliente aparecem primeiro.

Do not ask for a locker: nenhuma pergunta sobre o armário na finalização de compra.

Se você escolher a lista da Correos sem credenciais da API, ou a sua própria lista enquanto My lockers estiver vazia, o cliente é solicitado a informar o armário manualmente.

My lockers: usado quando Locker selection está definido como a sua lista. Um armário por linha: CODE | Name | Address | Postal code | City. Código e nome são obrigatórios. Linhas inválidas e duplicadas são informadas ao salvar.

Lista CityPaq da Correos (API) (usada somente com a lista CityPaq da Correos)

A seção tem um link para a página da API "terminals" no portal de desenvolvedores da Correos. Somente a lista de armários é lida. Os preços sempre vêm da tabela de preços.

API client ID: o client_id da sua aplicação no portal de desenvolvedores da Correos.

API client secret: o client_secret da sua aplicação no portal de desenvolvedores da Correos.

Quando você altera as credenciais ou a seleção de armário, as listas de armários em cache são apagadas.

Disponibilidade sem zonas de envio

Ignore shipping zones: oferece o CityPaq para qualquer endereço espanhol, mesmo que nenhuma zona de envio contenha este método. Desativado (recomendado) significa que o método é oferecido onde você o adicionou a uma zona de envio.

Avançado

Debug log: grava linhas de depuração em WooCommerce > Status > Logs, origem vfd-correos-citypaq. Os erros da API da Correos são sempre registrados, mesmo quando esta opção está desativada. Credenciais e dados pessoais nunca são registrados.

Remove data on uninstall: quando ativo, excluir o plugin remove as suas configurações e os métodos das zonas. Desativar o plugin nunca apaga nada. Os armários salvos nos pedidos são mantidos.

Como funciona na finalização de compra

Quando o cliente informa um endereço de entrega na Espanha, o WooCommerce pede uma tarifa ao plugin. O plugin verifica o peso do carrinho, o valor mínimo do pedido e as classes de envio excluídas, encontra a linha de preço da Espanha (ou a linha *) e o tamanho do pacote, e mostra o preço. Se o frete grátis se aplicar, o preço é 0.

Quando o cliente seleciona o CityPaq, o campo do armário aparece abaixo do método. O pedido não pode ser feito sem um armário válido. Isso também é verificado no servidor, inclusive para pedidos feitos pelos blocos de Carrinho e Finalização de compra. Com a lista da Correos, um código de armário só é aceito se a Correos o tiver oferecido a este cliente, e o nome e o endereço são obtidos da Correos. O número de pesquisas de código postal por sessão do cliente é limitado. Quando o limite é atingido, o cliente informa o armário manualmente.

Uma lista da Correos fica em cache por 12 horas para cada código postal. Uma requisição com falha fica em cache por 10 minutos, para que a finalização de compra não espere pela Correos a cada atualização. O tempo limite da API é de 12 segundos. O cliente nunca vê o erro técnico, apenas uma mensagem curta e o campo manual.

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

O plugin não obtém tarifas em tempo real da Correos, não mostra mapa, não pré-registra envios, não imprime etiquetas, não solicita coletas e não rastreia pacotes. Crie o envio na sua conta da Correos usando o armário salvo no pedido.

Pontos de retirada

O armário escolhido é salvo no pedido. Ele aparece na administração do pedido abaixo do endereço de entrega, na página de pedido recebido, em My account > Orders e em todos os e-mails de pedido (HTML e texto simples) como CityPaq locker.

Na administração do pedido, você pode alterar o armário no campo Change CityPaq locker: escolha outro armário da sua lista ou digite um novo código ou endereço. Com a lista da Correos, um código de armário digitado é consultado na Correos. Deixe o campo vazio para manter o armário atual. Cada alteração adiciona uma nota ao pedido.

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 Correos CityPaq. Cole a chave em License key e clique em Activate. O bloco mostra 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 informar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta em 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 vaga na sua conta em vibefox.net.

Sem uma chave ativa, o Correos CityPaq não é mostrado aos clientes na finalização de compra. Os gerentes da loja conectados ainda o veem, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página 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

O Correos CityPaq não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, se o endereço está na Espanha e se o método foi adicionado à zona de envio correspondente (ou se Ignore shipping zones está ligado). Confira se a tabela de preços tem uma linha para a Espanha ou uma linha *, e se o carrinho está dentro dos limites de peso, de Minimum order amount e de Excluded shipping classes.

Os clientes precisam digitar o armário mesmo com a lista da Correos selecionada: verifique se API client ID e API client secret estão preenchidos e veja o aviso acima das configurações. Ele mostra o último erro da API da Correos. HTTP 401/403 significa que a Correos recusou as credenciais: confira-as e verifique se a sua aplicação tem acesso à API "terminals". Após um erro, a próxima tentativa é feita 10 minutos depois.

Nenhum armário para um código postal: a Correos não encontrou armário ativo para esse código postal, sua área ou sua província. O cliente pode pesquisar outro código postal ou informar o armário encontrado no localizador CityPaq da Correos.

A lista suspensa dos meus armários não aparece: My lockers está vazio ou as linhas são inválidas. Cada linha precisa de pelo menos CODE | Name.

Onde os clientes encontram o código do armário: no localizador CityPaq da Correos, linkado abaixo do campo do armário.

Notas para desenvolvedores: o armário é salvo nos metadados do pedido _vfd_cpq_locker (texto exibido em todos os lugares) e _vfd_cpq_locker_id (código do armário, quando escolhido na lista da Correos ou na sua lista). O plugin usa a API de produção "terminals" da Correos. Nenhum sandbox é documentado para esta 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 em 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 não puder ser acessado, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todos os dados. Para removê-lo, desative e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin são sempre removidos, assim como as listas de armários da Correos em cache e o último erro da API. As configurações e os métodos de zona só são removidos se Remove data on uninstall estava ativo. Caso contrário, permanecem para uma futura reinstalação. Os armários salvos nos pedidos nunca são excluídos, e os pedidos existentes mantêm suas linhas de envio.

Correos e CityPaq são marcas registradas de seus respectivos titulares. Este plugin não é afiliado nem endossado pela Correos.