03/05/2026 · Equipe GálagoTEF

Como integrar a maquininha ao seu sistema (ERP/PDV)

Integrar a maquininha ao seu ERP ou PDV elimina digitação de valor, reduz erros de caixa e permite conciliar automaticamente cada venda. Este guia explica os caminhos técnicos de integração, o que muda entre eles e como fazer a escolha que não vai te prender a uma única administradora.

Por que integrar em vez de digitar

Na operação sem integração, o operador digita o valor na maquininha manualmente. Isso abre espaço para erro (valor trocado), dificulta a conciliação (a venda no sistema não bate com a captura na adquirente) e torna impossível automatizar comprovantes. Integrar significa que o próprio sistema envia o valor e a modalidade para a maquininha e recebe de volta o resultado da transação, com NSU e código de autorização. Se esses termos não são familiares, vale ler NSU e código de autorização: o que significam no comprovante.

Os caminhos de integração

Existem basicamente três formas de conectar a maquininha ao seu sistema:

• TEF local (SDK/DLL): o software fala com um gerenciador de TEF instalado na máquina, que controla o pinpad. Bom desempenho, mas amarra você ao ambiente Windows e ao equipamento específico.
• API REST da administradora: o sistema chama a API da administradora por HTTPS, ela envia a cobrança para a maquininha (POS-comanda) e você acompanha o status. Mais flexível e independente de plataforma.
• Hub de TEF: uma camada neutra que expõe uma API única e traduz para cada administradora por adapters, sem prender seu código a uma delas.

Como funciona a integração por POS-comanda

No modelo POS-comanda, a maquininha fica conectada à internet e recebe a cobrança de forma remota. O fluxo típico é:

1. Seu PDV cria a transação informando valor, modalidade e o POS de destino.
2. A plataforma envia a cobrança para a maquininha certa.
3. O operador finaliza no equipamento (cliente insere ou aproxima o cartão, ou paga no PIX).
4. Seu sistema recebe a confirmação por webhook ou consultando o status.

O passo 1 depende de um bom roteamento por POS: o sistema precisa saber para qual maquininha mandar a cobrança quando há várias no estabelecimento. Detalhamos isso em POS-comanda e por que restaurantes usam.

Confirmação: webhook e polling

Uma integração de pagamento nunca deve assumir que a venda foi aprovada só porque a requisição saiu. Você confirma o resultado de duas formas complementares:

• Polling: seu sistema consulta o status a cada poucos segundos até chegar a um estado final (confirmada, negada, cancelada).
• Webhook: a plataforma avisa seu sistema assim que o status muda, sem você precisar perguntar.

O ideal é suportar as duas. Aprofundamos o assunto em webhooks de pagamento: como usar para confirmar vendas.

Cuidados que separam integração boa de dor de cabeça

• Idempotência: envie uma chave única por cobrança para que reenvios (por timeout de rede) não gerem venda duplicada.
• Estados intermediários: trate “pendente” como pendente; não libere o pedido antes do status final.
• Cancelamento e estorno: implemente o caminho de reversão desde o início, não como remendo.
• Homologação: teste em ambiente de homologação antes de ir para produção com dinheiro real.

Escolhendo o caminho certo

Se você atende só um cliente com uma administradora fixa, a API direta pode bastar. Mas se você vende software para muitos lojistas, ou quer poder trocar de administradora sem reescrever, um hub compensa: você integra uma vez e ganha várias administradoras. Antes de decidir, use nosso guia API de pagamento: o que avaliar antes de integrar e consulte a documentação da API.

Comece pela integração que não te prende

O maior custo de integrar pagamento não é o primeiro projeto: é o segundo, quando você precisa suportar outra administradora e descobre que acoplou tudo à primeira. Uma API única com roteamento por POS e confirmação por webhook resolve o hoje sem hipotecar o amanhã.

Com o GálagoTEF você integra o ERP ou PDV uma única vez e passa a falar com várias administradoras de TEF, começando pela Elgin. Veja o painel e a documentação em app.galagotef.com.br e conecte sua maquininha ao sistema sem retrabalho.

← Voltar ao blog