PS PrestaShop Intermédio

Integrar POS com PrestaShop (Square, Zettle, SumUp): documentação

Instalar o módulo, ligar Square, Zettle ou SumUp, associar os produtos e sincronizar stock e vendas entre o POS e o PrestaShop.

Atualizado Versão do módulo 2.0.0

Funcionamento

O módulo liga o PrestaShop à sua caixa Square, Zettle by PayPal ou SumUp. Importa para um registo cada venda, devolução e reembolso da caixa, atualiza o stock no sentido que escolher e pode transformar cada venda numa encomenda PrestaShop. Também pode enviar o seu catálogo PrestaShop para a caixa.

O stock sincroniza-se num dos três sentidos seguintes, definido por caixa:

  • Da loja para a caixa: o PrestaShop é a referência. As vendas na caixa são deduzidas no PrestaShop e, depois, o novo nível volta para a caixa.
  • Da caixa para a loja: a caixa é a referência. O PrestaShop retoma as quantidades da caixa em cada execução do cron e em cada webhook de stock.
  • Nos dois sentidos: as alterações feitas em cada lado desde a última sincronização são somadas. Uma venda online e uma venda na loja contam cada uma uma única vez.
Painel do conector de caixa: vendas importadas, stock sincronizado, erros, fila e última sincronização
Painel do conector de caixa

O que faz cada caixa

  • Square: vendas, devoluções e reembolsos, stock nos três sentidos, várias lojas físicas, envio do catálogo com a imagem principal, webhooks assinados.
  • Zettle by PayPal: vendas e reembolsos, stock nos três sentidos, envio do catálogo, webhook assinado criado pelo módulo.
  • SumUp: vendas e reembolsos, deduzidos do stock do PrestaShop. A API pública do SumUp não disponibiliza stock, nem catálogo, nem webhook das vendas na caixa: a importação é feita pelo cron, e o stock apresentado no SumUp não é atualizado.

O módulo não substitui a sua caixa e não a transforma numa caixa certificada. Os talões, o fecho e as obrigações fiscais continuam a ser geridos pelo Square, pelo Zettle ou pelo SumUp.

Requisitos

  • PrestaShop 1.7.8 a 9.x. O módulo foi testado no PrestaShop 1.7.8.11 (PHP 7.4), 8.2.1 (PHP 8.1) e 9.1.5 (PHP 8.5).
  • Uma tarefa cron no seu alojamento.
  • Uma loja em HTTPS para os webhooks e para a ligação OAuth.
  • Uma conta Square, Zettle ou SumUp, e acesso à respetiva área de programador se ligar por token ou por chave API.

Instalação e atualização

  1. Em Módulos > Gestor de módulos, clique em Carregar um módulo e envie o ZIP.
  2. O módulo adiciona o menu Catálogo > Conector de caixa. O painel mostra uma lista Primeiros passos que se vai marcando à medida que configura o módulo.

Para passar de uma versão 1.x para a 2.0.0, envie o novo ZIP da mesma forma. A atualização mantém as correspondências, o registo de vendas, as ligações, os cursores de importação (nenhuma venda é importada de novo) e as definições. Os URL de webhook existentes continuam válidos. A atualização adiciona as novas tabelas, volta a encriptar os segredos antigos e retira do estado «Venda na caixa» o indicador de envio que provocava um segundo pagamento. As encomendas já criadas não são alteradas.

Ligar as suas caixas

O separador Ligações mostra o estado de cada caixa e as funções disponíveis. Cada caixa tem o seu próprio assistente. Os segredos são guardados encriptados e nunca voltam a ser apresentados nem são escritos no registo. Um campo deixado vazio mantém o valor guardado.

Ligações Square, Zettle e SumUp com as funções disponíveis
Ligações Square, Zettle e SumUp com as funções disponíveis

Square

  1. Escolha o modo de ligação. O OAuth é recomendado: autoriza o módulo a partir da sua conta Square, e o token é renovado automaticamente. Para uma única loja, também pode colar um token de acesso pessoal.
  2. Em OAuth, introduza o ID e o segredo da sua aplicação Square, e declare nessa aplicação o URL de redirecionamento apresentado. O módulo só pede as permissões necessárias: lojas físicas, encomendas, pagamentos, catálogo, stock e clientes em leitura, catálogo e stock em escrita.
  3. Clique em Ligar com Square, aceite as permissões e, depois, em Testar a ligação.
  4. Escolha a loja física que tem o stock e assinale aquelas cujas vendas são importadas (10 no máximo).
  5. Para a importação instantânea, adicione em Webhooks > Subscriptions o URL de notificação apresentado com os eventos order.updated, refund.created, inventory.count.updated e oauth.authorization.revoked, e cole a chave de assinatura no módulo. O URL tem de ser idêntico, carácter a carácter, dos dois lados.
Assistente de ligação Square: OAuth, permissões mínimas, lojas físicas
Assistente de ligação Square

O botão de ligação OAuth leva-o para a página de autorização da caixa, no próprio site desta, e depois traz-o de volta ao módulo. A captura abaixo foi feita em modo de demonstração, com um ecrã de autorização simulado.

Ecrã de autorização OAuth simulado (modo de demonstração)
Ecrã de autorização OAuth simulado (modo de demonstração)
Lojas físicas Square: loja de stock e importação de vendas
Lojas físicas Square

Zettle by PayPal

  1. Para uma única loja, recomenda-se a chave API autoalojada: crie-a no Zettle Developer Portal e cole-a com o respetivo ID de cliente. Também está disponível uma ligação OAuth para uma aplicação parceira, com renovação automática dos tokens.
  2. Guarde e, depois, teste a ligação.
  3. Clique em Ativar o webhook: o módulo cria ele próprio a subscrição (PurchaseCreated, InventoryBalanceChanged) e guarda a respetiva chave de assinatura encriptada. O Zettle exige uma loja em HTTPS.
  4. O controlo de stock tem de estar ativo nos produtos no Zettle. Os produtos enviados pelo módulo têm-no automaticamente.
Assistente de ligação Zettle: chave API ou OAuth e webhook assinado
Assistente de ligação Zettle

SumUp

  1. Cole a sua chave API secreta (painel do SumUp, Developers > API keys) com o seu código de comerciante, ou ligue por OAuth.
  2. Teste a ligação. O código de comerciante é lido automaticamente se estiver em falta.
  3. O SumUp não envia webhook para as vendas na caixa: são importadas pelo cron a cada 5 minutos. São associadas por referência ou pelo nome do artigo.
Assistente de ligação SumUp: chave API ou OAuth, importação pelo cron
Assistente de ligação SumUp

Desligar uma caixa

O botão Desligar revoga os tokens quando a caixa o permite (Square, Zettle) e elimina-os do PrestaShop. As correspondências e o registo de vendas são mantidos.

Sentido do stock

Em Definições > Stock, escolha o sentido do stock para o Square e para o Zettle: da loja para a caixa, da caixa para a loja, nos dois sentidos ou sem sincronização de stock. No SumUp, as vendas são deduzidas do stock do PrestaShop, mas a caixa não recebe stock.

  • Só uma caixa pode ser a principal no stock. Se escolher uma segunda, o módulo define-a como Nos dois sentidos.
  • Nos dois sentidos, a fonte de referência decide o primeiro alinhamento e os conflitos.
  • Um nível escrito pelo módulo nunca é reenviado, para evitar ecos. Quando a caixa já contabiliza as suas próprias vendas, a importação não as volta a deduzir.
  • A opção Enviar logo após cada alteração de stock no PrestaShop envia o nível de imediato. Caso contrário, é enviado na execução seguinte do cron.
Sentido de sincronização do stock por caixa e fonte de referência
Sentido de sincronização do stock por caixa e fonte de referência

Associar os produtos

O separador Correspondências liga cada artigo da caixa a um produto ou a uma combinação do PrestaShop.

  • Ler o catálogo do Square ou do Zettle: os artigos são associados automaticamente por SKU (referência do produto ou da combinação) e por código de barras EAN-13 / UPC.
  • Sugestões pelo nome: para cada artigo restante, o módulo propõe o produto mais próximo, com uma pontuação. As sugestões com 90 % ou mais podem ser aceites de uma só vez, as outras uma a uma. Nenhuma sugestão é guardada sem a sua validação.
  • Associação manual: pesquise um produto por nome, referência ou EAN.
  • Um artigo vendido na caixa mas ausente do catálogo lido também aparece na fila. Pode ocultá-lo se não for vendido online.
Correspondências entre artigos da caixa e produtos PrestaShop com sugestões
Correspondências entre artigos da caixa e produtos PrestaShop com sugestões

Associar um artigo acerta o stock das vendas já importadas, uma única vez. As linhas de vendas anteriores ficam ligadas à nova regra.

Enviar o catálogo para a caixa

O separador Catálogo cria os seus produtos PrestaShop no Square ou no Zettle: combinações como variações, preços, SKU, código de barras, imagem principal opcional e, depois, o stock. Escolha a caixa, uma categoria (subcategorias incluídas), o preço enviado (com ou sem IVA, sem descontos) e se apenas os produtos ativos são considerados.

  1. Verificar o que será enviado lê primeiro o catálogo da caixa, associa por SKU ou código de barras o que já existe e, depois, mostra o número de produtos e de variações a criar.
  2. Assinale a confirmação e clique em Criá-los na caixa: os produtos são enviados por lotes, com uma barra de progresso, e cada artigo criado fica associado de imediato.
Envio do catálogo PrestaShop para a caixa com pré-visualização antes de criar
Envio do catálogo PrestaShop para a caixa com pré-visualização antes de criar

Os artigos existentes na caixa nunca são alterados. No Square, cada artigo é ligado a um imposto Square existente com a mesma taxa: não é criado nenhum imposto. Os produtos virtuais e os packs são excluídos, e as categorias não são enviadas. O Zettle aceita no máximo 99 variações por produto. O SumUp não pode receber produtos através da sua API.

Controlo do stock e reconciliação

O separador Stock compara o stock do PrestaShop e o stock da caixa para cada artigo associado, e lista as diferenças. Para cada diferença, ou para uma seleção:

  • Manter o PrestaShop: a caixa recebe a quantidade do PrestaShop.
  • Manter a caixa: o PrestaShop recebe a quantidade da caixa, com um movimento de stock.

A sincronização completa noturna executa uma reconciliação e guarda o respetivo relatório. Os relatórios anteriores continuam disponíveis para consulta. Importar todos os níveis da caixa substitui o stock do PrestaShop de cada produto associado: use apenas uma vez, na configuração inicial, se o stock da caixa for o mais fiável.

Reconciliação do stock entre o PrestaShop e a caixa com relatório de diferenças
Reconciliação do stock entre o PrestaShop e a caixa com relatório de diferenças

Vendas na caixa

O separador Vendas na caixa lista cada talão com as suas linhas, a caixa, a loja física, o pagamento, o IVA por linha, a gorjeta e, se aplicável, a encomenda PrestaShop. Filtros: caixa, tipo (vendas, devoluções e reembolsos, encomendas PrestaShop), diferenças de montante, pesquisa por talão, artigo, loja física ou número de encomenda, e intervalo de datas. Exportar CSV exporta a seleção.

Registo de vendas na caixa com encomenda PrestaShop, IVA e gorjeta
Registo de vendas na caixa com encomenda PrestaShop, IVA e gorjeta

A importação é idempotente: uma venda já importada nunca é duplicada, mesmo que chegue por vários webhooks e pelo cron ao mesmo tempo. Os talões registados offline na caixa e transmitidos mais tarde também são importados. As vendas anteriores à data definida em Importar as vendas na caixa a partir de são ignoradas.

Encomendas PrestaShop para as vendas na loja

Em Definições > Encomendas e reembolsos, a opção Criar uma encomenda PrestaShop para cada venda na caixa cujos artigos tenham todos correspondência está desativada por predefinição. Depois de ativada:

  • um cliente de balcão por loja, com a morada da loja;
  • uma transportadora gratuita «Venda na caixa», nunca proposta no checkout;
  • o meio de pagamento «Caixa – Square / Zettle / SumUp», um único pagamento, e uma encomenda datada à hora da venda;
  • os preços e os descontos do talão, repartidos pelas linhas;
  • a gorjeta fora do total da encomenda, indicada na respetiva nota;
  • nenhum email, nem para o cliente nem para si.

O estado predefinido é «Venda na caixa» (paga, entregue, sem email nem fatura). Se o PrestaShop recalcular um total diferente do talão (regras de impostos, arredondamentos), a diferença é apresentada na venda e anotada no registo.

Definições de encomendas, faturas, reembolsos e clientes identificados
Definições de encomendas, faturas, reembolsos e clientes identificados
  • Permitir faturas para as encomendas da caixa: desativado por predefinição, porque a caixa já emite o talão. Sem esta opção, um estado que gera uma fatura é recusado. Com ela, a fatura é criada sobre o pagamento existente e indicada no registo.
  • Clientes identificados (Square): a encomenda pode ser ligada ao cliente PrestaShop existente que tem o mesmo endereço de email que o cliente Square. Só é utilizado um cliente existente com uma morada: não é criado nenhum cliente nem nenhuma morada.
Encomenda PrestaShop criada para uma venda na caixa, com o resumo do talão
Encomenda PrestaShop criada para uma venda na caixa, com o resumo do talão

Uma venda que contém artigos não associados não recebe encomenda: os seus artigos associados são deduzidos diretamente do stock.

Devoluções e reembolsos

As devoluções do Square, os reembolsos do Zettle e os reembolsos do SumUp são importados, incluindo os parciais. Os artigos devolvidos são repostos em stock uma única vez, pela linha de devolução. Um reembolso sem artigo devolvido não altera o stock. Na encomenda original, escolha:

  • Apenas uma nota na encomenda (predefinição);
  • Nota de crédito dos artigos devolvidos ou do montante reembolsado;
  • Nota de crédito e estado «Reembolsado» quando a encomenda estiver totalmente reembolsada.
Devolução parcial na caixa reposta em stock com nota de crédito
Devolução parcial na caixa reposta em stock com nota de crédito

Tarefas agendadas e webhooks

Definições > Tarefas agendadas mostra o URL do cron. Chame-o a cada 5 minutos, e o mesmo URL com full=1 uma vez por noite:

*/5 * * * * curl -s "https://a-sua-loja.pt/module/dfposconnector/cron?token=O_SEU_TOKEN" >/dev/null
0 3 * * * curl -s "https://a-sua-loja.pt/module/dfposconnector/cron?token=O_SEU_TOKEN&full=1" >/dev/null

O cron trata a fila dos webhooks, importa as novas vendas, renova os tokens e envia os níveis de stock pendentes. Duas execuções nunca se sobrepõem. A execução noturna reenvia todos os níveis associados e gera o relatório de reconciliação.

Cada webhook é verificado antes de ser aceite:

  • a chave de URL própria dos webhooks, distinta do token do cron;
  • a assinatura da caixa;
  • um tamanho máximo de 256 KB;
  • uma idade máxima de 96 horas;
  • um identificador de evento nunca visto.

O módulo responde de imediato e, depois, trata o evento. Uma notificação sem assinatura, com assinatura errada ou repetida é recusada e anotada no registo.

Registo técnico

O separador Registo lista os erros, avisos e informações, filtráveis por caixa, nível, problema, texto e data. Cada erro conhecido indica a sua causa e a sua solução, com uma ligação para o ecrã em causa. Os tokens, chaves e assinaturas são ocultados antes de serem escritos. As entradas são mantidas durante 30 dias por predefinição (configurável), e os últimos eventos de webhook recebidos são listados.

Registo técnico filtrável com causa e solução de cada erro
Registo técnico filtrável com causa e solução de cada erro

Alertas

O separador Alertas reúne os problemas em curso com a sua causa, a sua solução e um botão Corrigir agora. Um alerta fecha-se sozinho quando o problema desaparece.

  • sincronização falhada em 3 execuções seguidas e, depois, uma mensagem quando volta a funcionar;
  • token recusado ou impossível de renovar, permissão em falta, assinaturas de webhook recusadas;
  • atualizações de stock descartadas, cron que deixou de ser executado;
  • artigos vendidos na caixa sem produto PrestaShop;
  • diferenças encontradas pela reconciliação noturna.
Centro de alertas com causa, solução e emails
Centro de alertas com causa, solução e emails

Os alertas também podem ser enviados por email, no máximo um a cada 6 horas por alerta. Deixe o endereço vazio para usar o da loja. Enviar um alerta de teste verifica o envio.

Email de alerta do conector de caixa com explicação e solução
Email de alerta do conector de caixa com explicação e solução

Resolução de problemas

«Inventário não inicializado» no Zettle

Ative o controlo de stock em pelo menos um produto no Zettle, ou envie um produto a partir do separador Catálogo.

Webhook do Square recusado (assinatura inválida)

O URL de notificação declarado no Square tem de ser idêntico, carácter a carácter, ao do módulo, e a chave de assinatura tem de corresponder a essa subscrição.

Token recusado ou permissão em falta

Abra Ligações, volte a ligar a caixa com o respetivo assistente e aceite todas as permissões listadas.

O stock não é enviado após uma alteração no back office

O PrestaShop não executa os hooks de um módulo para um funcionário que não tem a permissão «Ver» nesse módulo. No sentido da loja para a caixa, o controlo de diferenças do cron apanha essas alterações na execução seguinte. Também pode conceder essa permissão em Parâmetros avançados > Equipa > Permissões.

Uma venda não criou encomenda

O registo indica o motivo: artigos não associados, moeda da venda inativa no PrestaShop, produto limitado a certas transportadoras ou quantidade inferior a uma unidade. Nesse caso, o stock foi tratado diretamente. Corrija a causa para as vendas seguintes. O botão Criar a encomenda PrestaShop só é proposto para uma venda cujo stock ainda não foi deduzido, para nunca o deduzir duas vezes.

O total da encomenda é diferente do talão

Verifique se a regra de impostos PrestaShop dos produtos corresponde à taxa de IVA usada na caixa. A diferença é apresentada na venda.

Desinstalação

A desinstalação apaga as tabelas do módulo (correspondências, registo de vendas, filas de espera, registo técnico, reconciliações, alertas) e as suas definições, e desativa a transportadora «Venda na caixa». As encomendas criadas, o estado de encomenda, o cliente de balcão e os motivos de movimento de stock são mantidos, porque o histórico faz referência a eles.

Esta página foi útil?

Ainda com dúvidas? Contacte o suporte