Como integrar ERP com serviços de banking via APIs

Última atualização: 15 de agosto de 2026

Principais lições deste artigo

• A conciliação manual de pagamentos consome de 3 a 8 horas por mês em PMEs e pode ser eliminada com APIs agregadoras que consolidam Pix, boletos e extratos em um único endpoint.

• Adotar o padrão de adaptador e chaves de idempotência permite que o ERP integre serviços bancários sem duplicar transações e sem grandes refatorações no módulo financeiro.

• Usar mTLS combinado com OAuth 2.0 e webhooks assinados é requisito obrigatório para segurança e notificações em tempo real de Pix e boletos.

• Implementar fluxos de consentimento Open Finance e realizar testes exaustivos em sandbox asseguram conformidade regulatória e taxa de conciliação automática acima de 99%.

• Com a Celcoin, ERPs integram Pix, boletos, extratos, pagamentos e Open Finance via APIs modulares e escaláveis; conheça a solução completa.

Visão geral da integração

Integrar serviços bancários diretamente ao ERP elimina o uso de portais bancários separados pelo usuário final e centraliza a operação financeira em um único sistema. Os pré-requisitos técnicos incluem suporte a REST/JSON, capacidade de armazenar certificados X.509, infraestrutura para receber webhooks HTTPS e um ambiente de sandbox para homologação.

Do lado regulatório, a operação precisa respeitar as normas do Sistema de Pagamentos Brasileiro (SPB) e da Rede do Sistema Financeiro Nacional (RSFN). As equipes de produto e tecnologia precisam alinhar escopo de dados, fluxos de consentimento e políticas de retry antes de iniciar o desenvolvimento.

Para ERPs que buscam uma infraestrutura pronta que já atende a esses requisitos técnicos e regulatórios, o banking da Celcoin oferece um banking modular que simplifica essa integração.

Passo 1: definição da arquitetura de camada bancária com adaptadores e idempotência

Usar o padrão de adaptador é a base arquitetural recomendada para integrar serviços bancários em ERPs. Implementar um adapter pattern no módulo financeiro do ERP permite que o ponto de entrada existente conviva com um novo cliente de API de Open Finance e alimente a mesma estrutura de transação sem grandes refatorações.

Encapsular cada serviço bancário em um adaptador específico organiza a integração e reduz o acoplamento. Cada adaptador trata um serviço, como Pix, boleto, extrato ou pagamento, enquanto a camada agregadora traduz as diferenças entre provedores e mantém uma interface única para o ERP.

Tratar a idempotência como requisito obrigatório evita transações duplicadas em qualquer integração de pagamentos. Uma chave de idempotência, tipicamente um UUID, segue no header da requisição, por exemplo em X-Idempotency-Key, e permite que a API reconheça e retorne o resultado de uma requisição anterior idêntica em vez de criar uma nova transação.

No contexto do SPB e da RSFN, falhas de rede podem ocorrer durante liquidações. A garantia de exactly-once passa por entrega at-least-once combinada com escritas idempotentes no banco de dados, e não por garantias da rede. A chave de idempotência precisa ser armazenada com durabilidade, associada ao ID do usuário e ao tipo de operação, e ter uma política de TTL de pelo menos 24 horas, o que permite reconhecer retentativas legítimas dentro dessa janela.

Para que essa deduplicação funcione mesmo sob alta concorrência, o armazenamento da chave e a execução do pagamento devem ocorrer de forma atômica. Combinar essa operação com um lock distribuído evita que requisições duplicadas simultâneas contornem a verificação de idempotência.

Passo 2: autenticação mTLS e credenciais

Adotar mTLS como camada de base garante que apenas clientes autorizados consigam se conectar às APIs financeiras. No mTLS, cliente e servidor se autenticam mutuamente com certificados digitais X.509 durante o handshake TLS, o que cria um canal seguro antes mesmo da autenticação na aplicação.

APIs financeiras reguladas no Brasil exigem mTLS para conexões de terceiros, e o ERP precisa armazenar e gerenciar o certificado cliente emitido pela autoridade certificadora do provedor. O fluxo de autenticação combina mTLS com OAuth 2.0: o ERP apresenta o certificado cliente no handshake TLS e, em seguida, troca Client ID e Client Secret por um access token de curta duração.

Os padrões FAPI 2.0 exigem tokens com restrição de remetente, uso de mTLS e credenciais de curta duração para reduzir o risco de roubo de token e ataques de replay. Todo o tráfego precisa usar TLS 1.2 ou superior, com criptografia AES-256 para campos sensíveis como números de conta e identificadores de pagamento.

Passo 3: configuração de webhooks para Pix e boletos

Com a autenticação estabelecida, o próximo passo é garantir que o ERP receba notificações em tempo quase real sobre eventos de pagamento, e os webhooks cumprem esse papel. Webhooks são o mecanismo principal para notificações de eventos de Pix e boletos e evitam consultas constantes às APIs.

Registrar o endpoint de webhook via API do provedor define a URL HTTPS e os tipos de evento desejados. A validação de assinatura precisa ocorrer em todas as chamadas: a verificação deve ser feita sobre os bytes brutos da requisição, usando HMAC com a construção timestamp + "." + rawBody e comparação em tempo constante para reduzir riscos de ataques de timing.

Para mitigar replay attacks, o ERP deve aplicar uma janela de timestamp de ±300 segundos combinada com verificações de idempotência que armazenam IDs de eventos com TTL de 86.400 segundos. Essa dupla camada bloqueia tanto eventos antigos quanto eventos duplicados recentes. Como webhooks podem ser reenviados em caso de falha, o processamento precisa ser assíncrono: o endpoint retorna HTTP 200 imediatamente após receber o evento, processa em background e permanece disponível para retentativas.

Quando um webhook falha ou atrasa, um mecanismo de polling reverso ou um job de reconciliação periódico deve consultar a fonte autoritativa para recuperar o status atual da transação. Para boletos, a conciliação depende do arquivo de retorno CNAB 240, que confirma quais boletos foram pagos, incluindo data e valor. Pagamentos de boletos bancários recebidos até 13h30 são creditados no mesmo dia útil, D+0, conforme regras da Febraban vigentes a partir de 15 de março de 2024.

Passo 4: fluxo de consentimento Open Finance

Implementar o fluxo de consentimento de Open Finance garante acesso a dados bancários com base em autorização explícita do usuário. O Open Finance Brasil, regulado pelo Banco Central do Brasil, exige que as instituições participantes disponibilizem o ambiente de Open Finance no primeiro nível do menu principal de seus canais.

O ERP que atua como instituição receptora de dados precisa implementar a seção “Meus Compartilhamentos”, onde o usuário consulta e gerencia seus consentimentos de compartilhamento. O fluxo de consentimento segue estas etapas:

1. O usuário inicia o compartilhamento no ERP, que atua como IR, e o sistema redireciona para o banco transmissor, que atua como IT.

2. O banco transmissor autentica o usuário e apresenta o escopo de dados solicitado, como saldos, extratos e dados cadastrais.

3. Após a aprovação, o consentimento pode ser registrado com validade superior a 12 meses, desde que compatível com as finalidades do compartilhamento, e o usuário pode revogar esse consentimento a qualquer momento.

4. O ERP passa a receber os dados via API enquanto o token de consentimento permanecer ativo.

O consentimento PJ para Open Finance costuma exigir o envolvimento de titulares legais da conta e autorizações separadas por conta bancária, o que aumenta a fricção no onboarding. Uma camada agregadora com widget de jornada alinhado ao Guia UX do Banco Central reduz esse atrito e padroniza a experiência de autorização.

Passo 5: testes em sandbox e checklist de homologação

Validar a integração em sandbox antes da produção reduz incidentes e retrabalho. O ambiente de sandbox deve cobrir os seguintes cenários:

• Criação e consulta de cobranças Pix com EndToEndId válido.

• Emissão e baixa de boletos com arquivo CNAB 240 simulado.

• Recebimento e validação de assinatura de webhooks para eventos de pagamento e cancelamento.

• Rejeição de requisições com chave de idempotência duplicada e payload alterado, com resposta esperada HTTP 409 Conflict.

• Fluxo completo de consentimento Open Finance com dados de extrato e saldo.

• Cenários de erro, como timeout, certificado inválido, token expirado e webhook com timestamp fora da janela.

O checklist de homologação precisa confirmar certificado mTLS instalado e validado, fluxo OAuth 2.0 funcional, webhooks recebendo e processando eventos de forma idempotente, reconciliação automática operando com taxa acima de 99% de match automático e relatórios regulatórios gerados corretamente.

Erros comuns e pontos de atenção

Evitar erros recorrentes em integrações ERP e banking reduz custos operacionais e suporte. Os erros mais frequentes são:

• Conciliação manual residual: manter processos manuais paralelos à integração via API cria inconsistências entre sistemas. Cada método de pagamento usa seu próprio identificador de transação, o que exige uma tabela de tradução entre o identificador externo e o ID interno do ERP para garantir rastreabilidade.

• Duplicação de transações: deixar a idempotência para fases posteriores é a principal causa de cobranças duplicadas. Webhooks de Pix podem chegar duas ou três vezes para o mesmo evento, o que exige deduplicação baseada em EndToEndId e chaves de idempotência bem definidas.

• Falhas de webhook sem fallback: depender apenas de webhooks pode deixar pedidos pagos marcados como pendentes ou cancelados no ERP. Um job de reconciliação precisa rodar a cada 1 a 5 minutos para cobranças Pix abertas e corrigir divergências com base na fonte autoritativa.

• Assincronia de liquidação: prazos de liquidação diferentes entre Pix, que liquida em tempo real, boletos, que liquidam no mesmo dia se pagos até 13h30 e caso contrário em D+1, e outros métodos criam assincronia temporal. Regras de tolerância e janelas de conciliação reduzem discrepâncias temporárias nos relatórios.

Critérios de sucesso

Definir critérios de sucesso desde o início orienta decisões técnicas e de produto. Os principais indicadores são:

• Prazo de implementação: uma integração básica de extrato bancário com boa documentação e SDK pode ser concluída em 1 a 2 sprints, entre 10 e 20 dias úteis. Integrações com reconciliação automática e webhooks costumam exigir de 2 a 4 sprints adicionais.

• Taxa de conciliação automática: um processo saudável de reconciliação de Pix busca taxa de match automático acima de 99%, com exceções diárias abaixo de 0,5% do volume e tempo médio de resolução inferior a 4 horas.

• Conformidade regulatória: manter zero pendências em relatórios obrigatórios, como DIMP, CADOCs e CCS, e garantir aderência contínua às normas do Banco Central.

Celcoin: solução full-stack para ERPs

Usar o banking da Celcoin permite que ERPs integrem serviços financeiros sem construir toda a infraestrutura regulatória e tecnológica do zero. A Celcoin oferece licenças próprias e infraestrutura tecnológica robusta para que ERPs integrem Pix, boletos, extratos, pagamentos e Open Finance diretamente em suas plataformas via APIs modulares.

ERPs que ainda não possuem licença própria podem operar sob a infraestrutura regulatória da Celcoin no modelo BaaS. ERPs que já possuem licença podem utilizar o Core Banking da Celcoin para ganhar eficiência e escala sem reconstruir sua operação. A Celcoin medeia mais de R$ 30 bilhões em transações mensalmente e atende mais de 6 mil clientes.

Funcionalidade da Celcoin	Benefício para sua empresa
APIs modulares	Integrações mais rápidas, com redução de custos e prazos de desenvolvimento.
Documentação, SDKs e sandboxes	Redução de ciclos de integração e custos de engenharia.
Capacidade de lançamento rápido	Módulos pré-construídos e entrega via SaaS aceleram lançamentos, com melhor tempo para geração de receita e competitividade.
Distribuição white-label e embutida (embedded)	Suporte a produtos financeiros com marca própria.
Escalabilidade com confiabilidade	Solução com alta disponibilidade e escalável na nuvem mantém serviços funcionando mesmo com altos volumes, protegendo sua receita.
Cobertura de diversas possibilidades de pagamentos, incluindo crédito	Oferecer pagamentos e emissão de crédito aumenta conversão, ARPU e fidelização.
Acesso a dados e personalização	Dados e análises via Open Finance permitem ofertas personalizadas, com melhor conversão e retenção.
Compliance e conformidade como princípio	KYC, AML e relatórios integrados reduzem risco regulatório e aceleram ciclos de vendas.
Prevenção de fraude e controles de risco	Monitoramento baseado em IA e autenticação robusta reduzem estornos, perdas e exposição regulatória.
Força do ecossistema de parceiros da Celcoin	Parcerias e integrações com bancos, redes e fintechs garantem boa cobertura, recursos e velocidade de entrada no mercado.

Para entender como sua empresa pode operar sob a licença da Celcoin ou integrar o Core Banking, fale com o time de soluções da Celcoin.

Próximos passos

Expandir o escopo após estabilizar pagamentos e extratos aumenta o valor do ERP para o cliente final. Após a estabilização da integração de pagamentos e extratos, os próximos vetores de expansão são:

• Expansão para crédito: a infraestrutura da Celcoin permite que ERPs ofereçam produtos de crédito aos seus clientes finais, como antecipação de recebíveis e capital de giro. A Celcoin não oferece nenhum tipo de empréstimo para consumidores. A Celcoin fornece a infraestrutura tecnológica para que empresas consigam ofertar produtos de crédito aos seus clientes.

• Governança de APIs: implementar versionamento, rate limiting, monitoramento de SLA e alertas de degradação ajuda a garantir estabilidade à medida que o volume de transações cresce.

• Evolução regulatória: acompanhar as fases do Open Finance Brasil e as atualizações das normas do Banco Central, com atenção a novos escopos de dados e requisitos de consentimento para PJ.

Para avançar nessa jornada com crédito, governança de APIs e Open Finance em um único parceiro, veja como o banking da Celcoin acelera essa evolução.

Perguntas frequentes

Qual o prazo médio de integração de um ERP com a Celcoin?

O prazo varia conforme a complexidade da estrutura existente e a disponibilidade da equipe de tecnologia. Integrações básicas podem ser concluídas rapidamente com boa organização. Integrações completas com a Celcoin costumam levar dias, não meses.

A Celcoin disponibiliza documentação detalhada, SDKs e ambiente de sandbox para reduzir o ciclo de desenvolvimento, além de uma equipe dedicada de suporte técnico durante todo o processo.

Qual o custo de setup para usar as APIs da Celcoin?

A Celcoin adota um modelo de remuneração centrado em transações, sem custos de setup elevados que criem barreiras de entrada. O ERP não precisa de um grande investimento inicial para começar a integração, e os custos acompanham o volume de uso.

Esse modelo facilita o planejamento financeiro e permite que a solução escale junto com o crescimento da base de clientes do ERP.

É possível migrar de outra solução de banking para a Celcoin?

É possível migrar de outra solução de banking para o banking da Celcoin com suporte especializado. A Celcoin possui uma equipe dedicada que auxilia no processo de migração e oferece suporte técnico para facilitar a transição sem interrupção da operação.

O prazo de migração depende da complexidade da estrutura atual. Operações mais simples podem ser migradas em uma semana, enquanto arquiteturas mais complexas podem levar até três meses. A recomendação é operar em modo dual por 30 a 60 dias com um grupo piloto de clientes antes de migrar toda a base, o que ajuda a garantir estabilidade e validação dos fluxos de reconciliação.

Como funciona o suporte técnico durante e após a integração?

O suporte técnico da Celcoin acompanha todas as etapas da integração, do onboarding no sandbox até a operação em produção. O atendimento inclui acesso direto a especialistas com capacidade de decisão, o que reduz o tempo de resolução de incidentes.

Em caso de problemas em produção, a equipe atua rapidamente para minimizar o impacto sobre os usuários finais do ERP. O suporte cobre dúvidas sobre APIs, certificados mTLS, fluxos de consentimento de Open Finance e relatórios regulatórios.