VibeFox Correos CityPaq for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e superior (testado na 4.1.0.3).
PHP: 8.0 ou superior.
Entrega na Espanha: os armários CityPaq existem apenas na Espanha, por isso o método só é oferecido para endereços de entrega na Espanha.
Credenciais da API dos Correos (somente para a lista de armários em tempo real): a lista CityPaq dos Correos lê os armários ativos pela API "terminals" dos Correos. No portal de desenvolvedores dos Correos, abra a API "terminals" e use Request access para a sua aplicação. Os Correos aprovam as solicitações de seus clientes corporativos e enviam um client ID e um client secret. Eles também aparecem em My applications no portal. Se os clientes informarem 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
O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3 vfd_correos_citypaq-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_correos_citypaq.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 painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_correos_citypaq-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. Acesse Extensions > Extensions, escolha o tipo de extensão Shipping. Localize VibeFox Correos CityPaq e clique em Install (o botão verde +).
3. Clique em Edit (o botão de lápis) para abrir a página de configurações.
4. Informe a sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Edit e clique em Activate (veja Chave de licença).
5. Preencha a tabela de preços, escolha como o cliente seleciona o armário (veja Configuração), ative Enable/Disable e clique em Save.
OpenCart 4
1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_correos_citypaq.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. Acesse Extensions > Extensions, escolha o tipo de extensão Shipping. Localize VibeFox Correos CityPaq, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).
4. Informe a chave de licença e as configurações como nos passos 4 e 5 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões.
Após a instalação, o método fica desativado até você ativar Enable/Disable e salvar. Se você instalar a extensão novamente após uma desinstalação, as configurações 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 Correos CityPaq > Edit. As seções são listadas à esquerda. Um único botão Save na parte inferior salva a página inteira sem recarregá-la. Preços e valores aceitam vírgula ou ponto decimal. Somente administradores com permissão de modificação para esta extensão podem salvar as configurações.
No topo da página aparecem avisos quando a tabela de preços não tem linha para a Espanha nem linha padrão, quando a seleção de armário escolhida não pode funcionar (não há armários na sua lista, não há credenciais da API), qual foi o último erro da API dos Correos, e quando a loja não tem uma classe de peso com a unidade kg (os pesos dos produtos são então convertidos pelo nome da unidade: kg, g, lb ou oz; unidades desconhecidas são lidas como kg). Verifique System > Localisation > Weight Classes. Se o nome estiver vazio, for inválido ou tiver mais de 64 caracteres, se um peso ou valor não for um número válido igual ou maior que 0, se Min weight (kg) for maior que Max weight (kg), ou se Sort order não for um número inteiro, a página mostra um erro e nada é salvo. Preços inválidos na tabela, linhas duplicadas e linhas inválidas ou duplicadas em My lockers são informados como avisos, e o restante é salvo.
Geral
Os armários CityPaq existem apenas na Espanha, então o método nunca é oferecido para outros países.
Enable/Disable: ativa ou desativa o envio com o Correos CityPaq. Padrão: desativado.
Name: o nome do método de envio exibido ao cliente na finalização da compra. Padrão: Correos CityPaq. Obrigatório, no máximo 64 caracteres, sem < > ; = # { }.
Tax class: o OpenCart adiciona o imposto desta classe aos preços da tabela. No tax significa que os preços são finais.
Sort order: a posição do método na lista de métodos de envio. Um número inteiro.
Preços (o título da seção mostra a moeda padrão da sua loja)
Os Correos não publicam uma API de tarifas para o CityPaq, então o preço vem desta tabela. Informe os preços do seu contrato com os Correos na moeda padrão da loja, sem impostos.
Price table: uma linha para Spain (ES) e/ou uma linha padrão * Default. Cada linha tem um Price base e preços opcionais para os tamanhos 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 botão × para remover uma. Sem uma linha correspondente, o método fica oculto. Se um país aparecer duas vezes, só a primeira linha é usada.
Calculation type: como o tamanho da encomenda é determinado.
Os pesos dos produtos são convertidos para kg a partir da classe de peso de cada produto.
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 encomendas de até 30 kg. 0 significa sem limite.
Minimum order amount: mostra o método somente quando o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) atinge este valor. Deixe vazio para sempre mostrar.
Frete grátis
Free shipping: ativa a entrega grátis com o CityPaq a partir do valor indicado abaixo.
Free shipping from: o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) a partir do qual este método custa 0. Usado somente quando Free shipping está ativado.
Escolha do armário CityPaq
A seção tem um link para o localizador oficial de armários CityPaq dos Correos.
Locker selection: como o cliente escolhe o armário antes de fazer o pedido. Padrão: o cliente informa o armário.
Se você escolher a lista dos 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á configurado com a sua lista. Um armário por linha: CODE | Name | Address | Postal code | City, por exemplo S0000213D | CityPaq Name | Street 1 | 46001 | Valencia. O código e o nome são obrigatórios. Se um código estiver listado duas vezes, somente a primeira linha é usada.
Lista CityPaq dos Correos (API) (usada somente com a lista CityPaq dos Correos)
A seção tem um link para a página da API "terminals" no portal de desenvolvedores dos 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 dos Correos.
API client secret: o client_secret da sua aplicação no portal de desenvolvedores dos Correos.
Após salvar, os dois campos ficam vazios e exibem Saved - leave empty to keep it. Informe um novo valor somente para alterá-lo. Marque Remove the saved client ID and client secret e clique em Save para excluí-los. Quando nada está salvo, a seção mostra No credentials saved. Ao alterar as credenciais ou a seleção de armário, as listas de armários em cache e o último erro da API são limpos.
Disponibilidade
Geo zone: oferece o método somente para endereços nesta zona geográfica. All zones (padrão) significa todos os endereços espanhóis. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.
Ignore geo zone: oferece o CityPaq para todos os endereços espanhóis, mesmo que não estejam na zona geográfica indicada acima.
Avançado
Debug log: grava linhas de depuração em storage/logs/vfd_cpq_debug.log.php (no OpenCart 4, system/storage/logs/vfd_cpq_debug.log.php). O arquivo não pode ser lido pela web. Os erros da API dos Correos são sempre gravados, mesmo com esta opção desativada. Credenciais e dados pessoais nunca são registrados.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativado, desinstalar a extensão exclui as configurações, as listas em cache e os logs. Os armários salvos nos pedidos são mantidos. Quando desativado (padrão), tudo é mantido para uma nova instalação.
Importação / Exportação
Export: clique em Download JSON para salvar as configurações em um arquivo JSON. O client ID e o secret da API não são incluídos.
Import: cole um JSON de configurações exportado por esta extensão e clique em Import. Os valores são verificados como em um salvamento normal. As credenciais salvas são mantidas.
Como funciona na finalização da compra
Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço do CityPaq. Se uma Geo zone estiver definida (e Ignore geo zone estiver desativado) e o endereço estiver fora dela, o CityPaq não é oferecido. Somente produtos com Requires Shipping definido como Yes contam: os demais produtos não somam peso e não entram no valor do pedido. A extensão então verifica que o endereço de entrega está na Espanha, o peso do carrinho e o valor mínimo do pedido, encontra a linha de preço para a Espanha (ou a linha *) e o tamanho da encomenda, e devolve o preço. Se o frete grátis se aplicar, o preço é 0. O preço é calculado na moeda padrão da loja, arredondado conforme as casas decimais dela, e exibido ao cliente na moeda dele com o imposto da Tax class selecionada. Nenhuma requisição é enviada aos Correos para o preço.
O campo CityPaq locker aparece abaixo do método CityPaq na etapa de método de envio. A escolha é salva assim que o cliente a faz. Um armário não aceitável é recusado com uma mensagem, e a escolha anterior permanece. Com a lista dos Correos, um código de armário só é aceito se os Correos o ofereceram para o CEP pesquisado, e seu nome e endereço são obtidos dos Correos. Um cliente pode pesquisar até 30 CEPs diferentes por sessão de finalização da compra. Depois disso, o cliente vê Too many searches. Please enter the CityPaq locker you found on the Correos map.
O botão Continue da etapa de método de envio não avança com o CityPaq sem um armário válido. Isso é verificado no servidor. O cliente vê, por exemplo, Please choose the CityPaq locker where you want to collect your parcel. Quando o pedido é feito, o armário é salvo no pedido.
No OpenCart 4, o cliente clica em Choose no bloco de método de envio da página de finalização da compra e escolhe o CityPaq na janela Shipping method options. O bloco CityPaq locker aparece nessa janela, abaixo da opção CityPaq, e funciona como descrito acima. O botão Continue da janela não avança com o CityPaq sem um armário válido. O OpenCart 4 mantém um único pedido para a finalização da compra e o atualiza cada vez que o cliente confirma novamente, e o armário do pedido é atualizado junto.
A lista dos Correos só é solicitada quando o CityPaq é o método selecionado, não enquanto a etapa é desenhada. Uma lista fica em cache por 12 horas por CEP. Uma requisição com falha fica em cache por 10 minutos, para que a finalização da compra não espere pelos Correos a cada atualização. O cliente nunca vê o erro técnico, apenas a mensagem The Correos CityPaq list cannot be loaded right now. e o campo manual.
A extensão não obtém tarifas em tempo real dos Correos, não mostra mapa, não pré-registra envios, não imprime etiquetas, não solicita coletas nem rastreia encomendas. Crie o envio na sua conta dos Correos usando o armário salvo no pedido.
Pontos de retirada
O armário escolhido é adicionado ao método de envio do pedido, por exemplo Correos CityPaq - CityPaq locker: .... Assim o cliente o vê no histórico de pedidos da conta e nos e-mails de pedido, e ele é impresso na nota fiscal e exibido em Sales > Orders. A página de sucesso do pedido do OpenCart não mostra o método de envio.
Na página do pedido no painel administrativo, o painel CityPaq locker acima do histórico mostra o armário e o seu Locker code: quando ele foi escolhido de uma lista. Para alterá-lo, use o campo Change CityPaq locker e clique em Save: com a sua lista, escolha outro armário no menu suspenso; com a lista dos Correos, informe um código de armário (ele é consultado nos Correos) ou um endereço; nos demais casos, informe um novo código ou endereço. Deixe o campo vazio, ou mantenha -- Keep the current locker --, para manter o armário atual. Cada alteração também atualiza o texto do método de envio do pedido e adiciona ao histórico uma entrada CityPaq locker changed to: ..., sem notificar o cliente. Alterar o armário exige a permissão de modificação de pedidos (sale/order). O acesso às configurações da extensão não é necessário. O painel é exibido para pedidos CityPaq mesmo quando a extensão está desativada.
Chave de licença
A extensão funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Correos CityPaq é o primeiro bloco da página Extensions > Extensions > Shipping > VibeFox Correos CityPaq > Edit, acima das configurações. Informe 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: opencart-shipping-correos-citypaq e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel administrativo (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 com 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 único domínio: o endereço da loja nas configurações do OpenCart. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, o método de envio Correos CityPaq não é exibido aos clientes na finalização da compra e nenhuma tarifa é calculada. Um usuário administrador conectado ao painel administrativo no mesmo navegador ainda vê o método na loja, marcado como (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 enxerga o login do painel administrativo, 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 painel administrativo. 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 exigem a renovação. O status é verificado novamente automaticamente quando você abre o Dashboard do painel administrativo ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é necessário cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.
Solução de problemas
O Correos CityPaq não aparece na finalização da compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o endereço de entrega está na Espanha. Verifique a Geo zone (ou ative Ignore geo zone). Verifique se a tabela de preços tem uma linha para a Espanha ou uma linha *, se o carrinho está dentro dos limites de peso e de Minimum order amount, e se os produtos têm Requires Shipping definido como Yes.
O cliente precisa digitar o armário mesmo com a lista dos Correos selecionada: verifique se API client ID e API client secret estão salvos e veja o aviso no topo da página de configurações. Ele mostra o último erro da API dos Correos. HTTP 401/403 significa que os Correos recusaram as credenciais: revise-as e verifique se a sua aplicação tem acesso à API "terminals". Após um erro, a próxima tentativa é feita após 10 minutos.
Não há armários para um CEP: os Correos não encontraram nenhum armário ativo para esse CEP, sua área ou sua província. O cliente pode pesquisar outro CEP ou informar o armário encontrado no mapa CityPaq dos Correos.
A lista suspensa de my lockers não aparece: My lockers está vazio ou suas linhas são inválidas. Cada linha precisa de pelo menos CODE | Name.
Onde os clientes encontram o código do armário: no mapa CityPaq dos Correos, vinculado abaixo do campo do armário.
A página diz "Warning: You do not have permission to modify VibeFox Correos CityPaq!": 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_correos_citypaq (OpenCart 3) ou extension/vfd_correos_citypaq/shipping/vfd_correos_citypaq (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: o armário de uma sessão de finalização da compra e o de um pedido são armazenados na tabela vfd_cpq_locker (com o prefixo do seu banco de dados). O endereço da API dos Correos pode ser substituído pela configuração vfd_cpq_api_url (para testes); ela não tem campo na página de configurações.
Desinstalação
Acesse Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Correos CityPaq. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable/Disable, Sort order, Tax class e Geo zone. As listas de armários dos Correos em cache e o último erro da API são sempre removidos. Se Remove data on uninstall estiver ativado, as configurações, o log e os armários de sessões de finalização sem pedido também são excluídos. Se estiver desativado, as demais configurações são mantidas e voltam a ser usadas quando você instalar a extensão novamente. Os armários salvos nos pedidos nunca são excluídos, e os pedidos existentes mantêm o método e o custo de envio.
No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer depois da desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Correos CityPaq na lista de extensões instaladas e depois em Delete (o botão vermelho de lixeira) para remover o pacote enviado.
Correos e CityPaq são marcas registradas de seus respectivos titulares. Esta extensão não é afiliada nem endossada pelos Correos.