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

Funcionamento

O PrestaShop é a referência do stock. Cada alteração de stock de um produto associado é enviada ao POS como quantidade absoluta. Cada venda no POS é importada, deduzida do stock do PrestaShop com o motivo de movimento «Venda na caixa», e o novo nível volta aos outros POS. As devoluções repõem os artigos em stock com o motivo «Devolução na caixa».

• Square: stock nos dois sentidos, vendas, devoluções, envio do catálogo.
• Zettle by PayPal: stock nos dois sentidos, vendas, reembolsos, envio do catálogo.
• SumUp: só importação de vendas. A API pública do SumUp não disponibiliza stock nem catálogo.

Requisitos

• PrestaShop 8.0 a 9.x.
• Uma tarefa cron no seu alojamento.
• HTTPS na loja para o webhook do Zettle.
• Uma conta Square, Zettle ou SumUp com acesso de programador.

Instalaçã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 POS.
3. O painel mostra uma lista «Primeiros passos» que se vai marcando à medida que configura o módulo.

Ligar os seus POS

Abra o separador Ligações. Cada POS tem o seu próprio bloco com a caixa Ativado. As credenciais são cifradas na base de dados: um campo deixado vazio mantém o valor guardado.

Square

1. Crie uma aplicação no Square Developer Dashboard e copie o token de acesso de produção.
2. Cole-o em Token de acesso, escolha o ambiente, guarde e clique em Testar a ligação.
3. Escolha a localização que recebe o stock. Se tiver várias, assinale aquelas cujas vendas devem ser importadas (10 no máximo).
4. Para importação imediata, crie uma subscrição de webhook no evento order.updated com o URL de notificação apresentado, e cole a chave de assinatura no módulo. O URL tem de ser idêntico dos dois lados.

Zettle by PayPal

1. No Zettle Developer Portal, crie uma chave API self-hosted com os scopes READ:PURCHASE, READ:PRODUCT, READ:USERINFO e WRITE:PRODUCT.
2. Introduza o Client ID e a chave API, guarde e teste a ligação.
3. Clique em Ativar o webhook para receber as vendas em poucos segundos.
4. O controlo de stock tem de estar ativo nos produtos do Zettle. Os produtos enviados pelo módulo têm-no automaticamente.

SumUp

1. Introduza a chave API secreta (sup_sk_...), guarde e teste a ligação. O código de comerciante é detetado automaticamente.
2. As vendas SumUp são associadas pelo nome do artigo: referência exata ou nome exato de um produto sem combinações.

Regras de sincronização

No topo do separador Ligações:

• Enviar os níveis de stock do PrestaShop para o POS e, opcionalmente, logo após cada alteração.
• Importar as vendas do POS e deduzi-las do stock do PrestaShop.
• Repor em stock os artigos devolvidos (Square e Zettle).
• Associação automática por referência, por EAN-13 / UPC e pelo nome no SumUp.
• Importar as vendas do POS a partir de: as vendas anteriores são ignoradas. Uma venda já importada nunca é duplicada.

Tarefa agendada e webhooks

O painel mostra dois URL. Agende o primeiro a cada 5 minutos e o segundo (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 importa as novas vendas, envia o stock pendente e deteta as diferenças criadas fora do PrestaShop (importação SQL, ERP). A sincronização noturna reenvia todos os níveis associados. O cron e os webhooks também funcionam em modo de manutenção.

Associar os produtos

Separador Associação de produtos:

• Ler o catálogo do Square ou do Zettle: associa automaticamente por SKU e código de barras.
• Sugerir produtos pelo nome: propõe um produto para cada artigo restante, com uma pontuação. As sugestões com 90 % ou mais podem ser aceites em massa, as outras uma a uma.
• Associação manual: pesquise um produto por nome, referência ou EAN.
• Enviar todo o stock para o POS, ou importar o stock do POS para o PrestaShop (use apenas uma vez, na configuração, se o stock do POS for o fiável).

Enviar o catálogo para o POS

Separador Envio do catálogo: escolha o POS, 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 do POS e associa o que já existe, e depois mostra o número de produtos e variantes a criar.
2. Criá-los no POS envia os produtos por lotes com uma barra de progresso. As combinações tornam-se variantes. Cada artigo criado fica associado e recebe o seu stock.

Não são enviados: os produtos já associados nesse POS, os produtos virtuais, os packs, as imagens e as categorias. O Zettle aceita no máximo 99 variantes por produto.

Controlo de stock

O separador Controlo de stock lê as quantidades reais do Square ou do Zettle e lista as diferenças com o PrestaShop, das maiores para as menores. Para cada linha:

• Enviar o stock do PrestaShop: o POS recebe o valor do PrestaShop.
• Usar o stock do POS: o PrestaShop recebe o valor do POS, com um movimento de stock.

Encomendas PrestaShop para as vendas na loja

Bloco Encomendas PrestaShop, desativado por predefinição. Depois de ativado, cada venda com todos os artigos associados cria uma encomenda:

• cliente de balcão dedicado com a morada da loja;
• transportadora gratuita «Venda na caixa», nunca proposta no checkout;
• preços do talão, com um desconto global repartido pelas linhas;
• encomenda datada à hora da venda, com a referência do POS na nota interna;
• estado «Venda na caixa» (paga, entregue, sem fatura nem email), alterável nas definições.

Nesse caso é a encomenda que deduz o stock. Não é enviado nenhum email durante a criação. Uma venda com artigos não associados não recebe encomenda: os seus artigos associados são deduzidos diretamente.

Registo de vendas

O separador Vendas POS lista cada venda com as suas linhas, POS, localização, pagamento e, se aplicável, a ligação para a encomenda. Filtros: POS, estado (por associar, associadas, devoluções, com encomenda), pesquisa por talão, artigo ou localização, intervalo de datas. O botão Exportar CSV exporta a seleção, uma linha por artigo.

Alertas por email

Bloco Alertas por email: é enviado um email quando a sincronização agendada falha 3 vezes seguidas (no máximo um a cada 6 horas) e outro quando volta a funcionar. Deixe o endereço vazio para usar o da loja. O botão 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 Envio do catálogo.

Webhook do Square recusado (assinatura inválida)

O URL de notificação declarado no Square tem de coincidir carácter a carácter com o do módulo, e a chave de assinatura tem de pertencer a essa subscrição.

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 sem a permissão «Ver» nesse módulo. O controlo de diferenças do cron apanha essas alterações na execução seguinte. Também pode conceder a permissão em Parâmetros avançados > Equipa > Permissões.

Uma venda não criou encomenda

O registo técnico indica o motivo: artigos não associados, moeda da venda ausente no PrestaShop, restrição de transportadora num produto ou quantidade inferior a uma unidade. Nesse caso o stock foi deduzido diretamente.

Desinstalação

A desinstalação apaga as tabelas do módulo (associações, registo de vendas, fila, registo técnico) 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.