Antes de integrar a API financeira de um banco ou fintech, uma empresa deve perguntar quais operações estão disponíveis, qual volume a API suporta, quais são os limites de requisição, como funcionam disponibilidade, autenticação, idempotência, webhooks, Sandbox, conciliação e suporte técnico. Também é importante entender como a integração reage a falhas, picos e indisponibilidades.
A documentação dos endpoints é apenas uma parte da decisão.
Quando pagamentos, recebimentos e movimentações passam a depender de uma API, aquela integração entra na operação da empresa.
Por isso, CFOs, CTOs e times de engenharia deveriam avaliar o fornecedor em três dimensões:
o que a API permite fazer;
como ela se comporta em escala;
o que acontece quando alguma coisa falha.
Por que avaliar uma API financeira antes de integrar?
Porque trocar uma integração financeira depois que ela está em produção pode ser muito mais complexo do que comparar fornecedores antes da implementação.
A empresa pode precisar alterar:
- autenticação;
- endpoints;
- estruturas de dados;
- regras de aprovação;
- webhooks;
- conciliação;
- tratamento de erros;
- monitoramento;
- processos internos.
Quanto mais profundamente o banco estiver conectado ao ERP e aos sistemas da empresa, maior tende a ser o custo de uma mudança.
A escolha, portanto, não deveria começar apenas por preço ou pela existência de uma API.
Deveria começar pela arquitetura.
APIs já são relevantes para o sistema financeiro brasileiro?
Sim.
A Pesquisa Febraban de Tecnologia Bancária 2025 registrou 112,3 bilhões de chamadas de APIs de Open Finance em 2024, contra 51,9 bilhões no ano anterior.
Foi um crescimento de 116% em apenas um ano.
Os bancos participantes da pesquisa também disponibilizavam, em média, 324 APIs externas em 2024.
APIs de Open Finance não são a mesma coisa que APIs proprietárias utilizadas por empresas para executar pagamentos ou cobranças. Ainda assim, os números ajudam a dimensionar quanto a comunicação entre sistemas já faz parte do setor financeiro.
Para uma empresa, a questão deixa de ser apenas se existe API.
Passa a ser qual API consegue sustentar sua operação.
1. Quais operações podem ser feitas pela API?
Essa deveria ser a primeira pergunta.
“Temos API” diz muito pouco.
Pergunte se é possível:
- enviar Pix;
- pagar boletos;
- pagar tributos;
- emitir boletos;
- criar cobranças Pix;
- consultar saldo;
- consultar extrato;
- acompanhar pagamentos;
- receber informações de transações;
- operar cartões;
- consultar recebimentos.
Depois, compare essa lista com os processos reais da empresa.
Se o ERP consegue consultar saldo, mas pagamentos continuam sendo realizados manualmente, a integração resolveu apenas parte do problema.
LEIA MAIS:
O que é uma API? Definição, funcionamento e TUDO sobre
Pix via API: como integrar pagamentos e recebimentos na sua empresa
API bancária é segura? Entenda como funciona a segurança de uma integração financeira
2. A API permite executar ou apenas consultar?
Existe uma diferença importante entre APIs de consulta e APIs transacionais.
Uma API pode permitir consultar saldo e movimentações sem permitir iniciar um pagamento.
Para automação financeira, é importante entender quais ações podem efetivamente ser executadas pelo sistema.
Pergunte:
meu ERP consegue criar a operação ou apenas enxergá-la?
Essa resposta define o potencial de automação.
3. Qual volume a API suporta?
Uma integração que funciona para 500 pagamentos pode não se comportar da mesma maneira com 500 mil.
Por isso, informe ao fornecedor:
- volume médio diário;
- volume mensal;
- pico esperado;
- concentração por horário;
- crescimento projetado.
Depois, pergunte qual capacidade a arquitetura suporta.
Média é importante.
Pico é ainda mais importante.
Uma folha de pagamento, repasse de marketplace ou operação de cashback pode concentrar grande volume em poucos minutos.
4. Quais são os rate limits?
Rate limits determinam quantas requisições podem ser realizadas dentro de determinado intervalo.
Pergunte:
- qual é o limite?
- ele varia por endpoint?
- varia por cliente?
- pode ser aumentado?
- o que acontece quando é atingido?
- como a API informa que o limite foi excedido?
Essa informação precisa chegar ao time de engenharia antes da produção.
Descobrir um limite quando milhares de pagamentos já estão na fila é tarde demais.
5. Qual é o uptime da API?
Disponibilidade precisa ser mensurável.
Pergunte:
qual é o SLA?
qual foi o uptime observado nos últimos meses?
existe status page pública?
quais serviços entram no cálculo?
manutenções programadas são excluídas?
Uma diferença aparentemente pequena pode representar horas.
Em um ano:
99,9% de disponibilidade permite aproximadamente 8h46min de indisponibilidade.
99,99% permite aproximadamente 52min34s.
O percentual precisa ser interpretado de acordo com a criticidade da operação.
6. Qual é a latência?
Uptime responde se o serviço está disponível.
Latência responde quanto ele demora para responder.
Uma API pode estar tecnicamente disponível e ainda apresentar lentidão suficiente para prejudicar determinada operação.
Pergunte pela:
- latência mediana;
- latência em períodos de pico;
- distribuição de latência;
- diferença entre endpoints.
Para operações síncronas, essa informação pode ser especialmente relevante.
7. Existe Sandbox?
Simular antes de movimentar dinheiro real deveria ser parte da avaliação.
Pergunte se o Sandbox permite testar:
- pagamentos;
- cobranças;
- erros;
- rejeições;
- webhooks;
- mudanças de status;
- duplicidades;
- retries.
Também pergunte o quanto esse ambiente se aproxima da produção.
Um Sandbox que demonstra apenas o cenário perfeito ajuda no desenvolvimento inicial, mas diz pouco sobre como a integração se comportará diante de falhas.
8. Como funciona a autenticação?
APIs financeiras movimentam informações e, em muitos casos, dinheiro.
Por isso, autenticação não deveria ser tratada como detalhe de implementação.
Pergunte:
- quais credenciais são utilizadas?
- existem certificados?
- as requisições são assinadas?
- como ocorre rotação de credenciais?
- permissões podem ser segmentadas?
- existe separação entre ambientes?
- como acessos são revogados?
O time de segurança da empresa deveria participar dessa avaliação antes do go-live.
9. A API possui idempotência?
Essa é uma pergunta essencial para pagamentos.
Imagine:
o ERP envia R$ 100 mil;
a instituição processa;
a conexão cai antes da resposta;
o ERP tenta novamente.
A segunda requisição vai criar outro pagamento?
Uma API preparada para operações financeiras deve oferecer mecanismos para lidar com esse cenário.
Com idempotência, o sistema consegue reconhecer que duas tentativas representam a mesma operação.
Isso permite fazer retries sem necessariamente duplicar o pagamento.
10. Como funcionam os webhooks?
Pergunte quais mudanças podem gerar eventos.
Por exemplo:
- pagamento concluído;
- pagamento rejeitado;
- Pix recebido;
- boleto pago;
- transferência devolvida;
- estorno.
Depois, vá além:
há retry se meu endpoint estiver indisponível?
eventos podem chegar duplicados?
podem chegar fora de ordem?
posso recuperar um evento perdido?
cada evento possui identificador único?
Ter webhook é diferente de possuir uma arquitetura de eventos confiável.
11. Como a empresa recupera uma informação perdida?
Essa pergunta testa resiliência.
Imagine que um webhook não tenha sido processado.
Como descobrir?
Uma boa arquitetura deveria oferecer alguma forma de consultar o estado atual ou recuperar eventos.
Em sistemas financeiros, depender de uma única mensagem para manter duas bases consistentes aumenta o risco operacional.
Por isso, pergunte:
como reconciliamos nosso sistema com a fonte oficial depois de uma falha?
12. Como funciona a conciliação?
Criar um pagamento é apenas metade da integração.
A outra metade é saber exatamente o que aconteceu com ele.
Pergunte:
- quais IDs acompanham a operação?
- posso enviar meu próprio identificador?
- consigo relacionar pagamento e transação?
- como identifico uma devolução?
- quais informações retornam ao ERP?
- existe metadata?
- o histórico fica disponível pela API?
Quanto melhor a rastreabilidade, menor a necessidade de investigação manual.
13. Como funciona o suporte técnico?
Essa pergunta costuma aparecer tarde demais.
Antes de integrar, descubra:
- existe time técnico?
- desenvolvedores falam diretamente com especialistas?
- existe suporte durante o go-live?
- como incidentes críticos são escalados?
- existe atendimento fora do horário comercial?
- qual é o tempo esperado de resposta?
- existe canal de emergência?
Uma documentação excelente reduz dependência do suporte.
Mas quando uma operação crítica apresenta problema, acesso rápido às pessoas certas importa.
14. A documentação pode ser avaliada antes da contratação?
Documentação pública é uma evidência importante da maturidade de uma API.
Antes de assinar, o time técnico deveria conseguir avaliar:
- endpoints;
- exemplos;
- autenticação;
- objetos;
- erros;
- webhooks;
- SDKs;
- changelog;
- Sandbox.
Quanto menos informação estiver disponível antes da decisão, mais difícil é estimar esforço de implementação.
15. Como mudanças na API são comunicadas?
Integrações financeiras podem permanecer em produção por anos.
Pergunte:
- existe versionamento?
- como breaking changes são tratados?
- existe período de migração?
- há changelog?
- clientes são avisados previamente?
- versões antigas permanecem disponíveis por quanto tempo?
Uma API não precisa apenas funcionar no dia da integração.
Precisa continuar previsível depois.
Como comparar dois bancos antes da integração?
Uma matriz simples ajuda a retirar a decisão do campo das percepções:
| Critério | Banco A | Banco B |
| Pagamentos necessários | ✓ / ✕ | ✓ / ✕ |
| Sandbox | ✓ / ✕ | ✓ / ✕ |
| Webhooks | ✓ / ✕ | ✓ / ✕ |
| Idempotência | ✓ / ✕ | ✓ / ✕ |
| Rate limits documentados | ✓ / ✕ | ✓ / ✕ |
| Uptime publicado | % | % |
| Status page | ✓ / ✕ | ✓ / ✕ |
| Latência publicada | ms | ms |
| SDKs | quantidade | quantidade |
| Suporte técnico | modelo | modelo |
| Recuperação de eventos | ✓ / ✕ | ✓ / ✕ |
| Documentação pública | ✓ / ✕ | ✓ / ✕ |
O objetivo não é encontrar o fornecedor com mais checkmarks.
É identificar qual arquitetura atende melhor ao caso de uso da empresa.
Como o Stark Bank responde a essas perguntas?
O Stark Bank mantém documentação pública da API, Sandbox, SDKs e status de seus serviços.
A documentação informa atualmente 99,99% de uptime da API, latência mediana inferior a 200 milissegundos, nove SDKs oficiais e tempo médio de integração de aproximadamente dois dias.
A API utiliza identificadores externos em operações de escrita para permitir retries sem criar duplicidades.
Webhooks comunicam mudanças nos recursos e podem ser combinados com consultas posteriores para recuperação e conciliação.
A autenticação utiliza criptografia de chave pública, com requisições assinadas digitalmente.
A documentação também orienta empresas com picos elevados de tráfego a discutir antecipadamente os limites necessários para sua operação.
Esses números não substituem uma avaliação técnica.
Eles tornam parte dessa avaliação mensurável.
Checklist: 20 perguntas antes de integrar uma API financeira
Antes do go-live, responda:
- Quais operações estão disponíveis?
- Posso executar pagamentos ou apenas consultar?
- Qual volume a API suporta?
- Qual é o pico suportado?
- Quais são os rate limits?
- Existe SLA?
- Qual é o uptime histórico?
- Existe status page?
- Qual é a latência?
- Existe Sandbox?
- Consigo testar falhas?
- Como funciona a autenticação?
- Existe idempotência?
- Como funcionam retries?
- Quais eventos possuem webhook?
- Como eventos perdidos são recuperados?
- Como funciona a conciliação?
- Existe documentação pública?
- Como funciona o suporte técnico?
- Como mudanças na API são comunicadas?
Se essas respostas não estiverem claras antes da integração, parte do risco técnico ainda não foi dimensionada.
Afinal, o que perguntar a um banco antes de integrar uma API financeira?
Antes de integrar, pergunte quais operações a API permite executar, qual volume suporta, quais são seus rate limits, uptime e latência, como funcionam Sandbox, autenticação, idempotência, webhooks, recuperação de eventos, conciliação, versionamento e suporte técnico.
A decisão não deveria ser baseada apenas na pergunta:
“vocês têm API?”
Para uma empresa que depende daquela integração para movimentar dinheiro, a pergunta mais relevante é outra:
“o que acontece com nossa operação quando o volume cresce ou alguma coisa não funciona como esperado?”
É a resposta a essa pergunta que separa uma API disponível de uma API preparada para fazer parte de uma operação financeira crítica.
