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.
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.

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
- Em Módulos > Gestor de módulos, clique em Carregar um módulo e envie o ZIP.
- 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.

Square
- 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.
- 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.
- Clique em Ligar com Square, aceite as permissões e, depois, em Testar a ligação.
- Escolha a loja física que tem o stock e assinale aquelas cujas vendas são importadas (10 no máximo).
- 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.updatedeoauth.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.

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.


Zettle by PayPal
- 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.
- Guarde e, depois, teste a ligação.
- 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. - O controlo de stock tem de estar ativo nos produtos no Zettle. Os produtos enviados pelo módulo têm-no automaticamente.

SumUp
- Cole a sua chave API secreta (painel do SumUp, Developers > API keys) com o seu código de comerciante, ou ligue por OAuth.
- Teste a ligação. O código de comerciante é lido automaticamente se estiver em falta.
- 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.

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.

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.

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.
- 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.
- 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.

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.

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.

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.

- 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.

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.

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.

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.

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.

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.