02/07/2026 · Equipe GálagoTEF

Migrando de uma integração direta para um hub de TEF

Você já tem pagamento em maquininha funcionando, integrado direto na administradora, e decidiu passar para um hub de TEF — para suportar mais de uma administradora, centralizar relatórios ou parar de manter protocolo. A boa notícia: migração de TEF não precisa ser um big bang. Dá para fazer de forma incremental, com fallback, sem parar de vender. Este guia mostra o caminho seguro.

Por que migrar (e o que você ganha)

Antes do “como”, vale alinhar o “porquê”. Uma integração direta acopla seu código ao protocolo de uma administradora: autenticação, polling, webhook, mapeamento de códigos, idempotência — tudo dentro do seu produto. Migrar para um hub troca isso por uma API única e move a complexidade de administradora para adapters mantidos pelo hub. Se você ainda pesa a decisão, o artigo por que usar um hub de TEF em vez de integrar direto detalha os ganhos.

O objetivo da migração é chegar a um estado onde: você cria transações sempre igual (valor, modalidade, POS de destino), recebe status normalizado e tem todas as vendas num ledger único.

Estratégia incremental (não big bang)

A regra de ouro: nunca desligue a integração antiga antes de a nova provar valor em produção. A migração acontece por camadas:

1. Mapear o estado atual — liste como você cria cobrança, acompanha status, estorna e concilia hoje. Anote onde ficam NSU, código de autorização e comprovante.
2. Modelar no hub — traduza cada operação para a API do hub. Modalidades, POS de destino e chave de idempotência têm de ter equivalência clara.
3. Homologar — rode o fluxo completo no ambiente de testes do hub antes de tocar produção. O roteiro de testar integração de TEF em homologação cobre os casos que não podem faltar.
4. Piloto com fallback — direcione uma fatia do tráfego (um caixa, uma loja) para o hub, mantendo a integração antiga pronta para assumir.
5. Ampliar gradualmente — cresça a fatia conforme a confiança sobe, monitorando erros e conciliação.
6. Cutover — quando 100% roda pelo hub de forma estável, desligue a integração antiga.

Escolha o modelo de credencial certo

Um passo específico do GálagoTEF: definir de quem é a credencial. Se você mantém o contrato com a administradora, usa o Modelo B (credencial própria, override na cascata). Se prefere a credencial da plataforma, fica no Modelo A. Essa escolha afeta faturamento, não capacidade técnica — entenda a diferença em Modelo A vs Modelo B. Definir isso cedo evita retrabalho na virada.

Cuidados durante a migração

• Idempotência é obrigatória. Durante o período com dois caminhos ativos, o risco de duplicar venda cresce. Use chave de idempotência por transação — reveja idempotência em pagamentos.
• Não perca histórico. Mantenha o acesso aos dados da integração antiga para conciliar vendas anteriores à virada.
• Reconcilie nos dois lados. No piloto, bata as vendas do hub com o extrato para confirmar que valores e taxas conferem.
• Trate POS offline e timeout igual (ou melhor) do que na integração antiga; degradação de rede não pode virar venda perdida silenciosa.
• Comunique a operação. Caixas e garçons precisam saber que a maquininha continua igual — a mudança é no backstage.

Checklist rápido de migração

• Inventário das operações atuais (criar, status, estorno, conciliação)
• Mapeamento de modalidades e POS de destino para a API do hub
• Modelo de credencial definido (A ou B)
• Fluxo completo aprovado em homologação
• Idempotência ativa nos dois caminhos
• Piloto em produção com fallback funcionando
• Conciliação batendo no piloto
• Plano de rollback documentado
• Cutover só após estabilidade comprovada

Depois do cutover

Migrar não termina no cutover. Nas primeiras semanas com 100% no hub, mantenha monitoramento reforçado e concilie diariamente. Aproveite o ledger único para ativar os relatórios de vendas que a integração antiga não entregava — mix de pagamento, taxa efetiva por modalidade e vendas por POS agora vêm de uma fonte só.

Só considere a migração concluída quando a integração antiga puder ser desligada sem nenhum plano B ativo — e quando o item de checklist de TEF em produção estiver todo verde.

Pronto para migrar sem parar de vender? Comece pela documentação da API do GálagoTEF ou crie um ambiente de homologação no painel e rode seu piloto com segurança.

← Voltar ao blog