Principais lições deste artigo
- Integrar uma API de Credit as a Service exige criar uma camada de adapter para evitar acoplamento forte e permitir troca de provedor sem reescrever o produto.
- Definir a matriz de responsabilidade regulatória, incluindo quem é o credor, quem faz KYC e quem assume inadimplência, antes do primeiro commit e em alinhamento com a licença da fintech.
- Tratar a CCB como título executivo extrajudicial e usar assinatura eletrônica avançada como forma juridicamente suficiente de formalização, conforme a Circular BCB nº 4.036/2020.
- Desenhar webhooks de crédito em três camadas, com caminho rápido, sweep periódico e comparação diária, para garantir idempotência e evitar duplicidade.
- Usar a infraestrutura full stack da Celcoin, da originação ao funding, com APIs modulares, sandboxes, cel_agents e securitização via VERT Capital em um único ecossistema.
Veja como integrar crédito com a solução de crédito da Celcoin
O que é integrar uma API de Credit as a Service em uma fintech
Integrar uma API de CaaS em uma fintech significa conectar a infraestrutura tecnológica de um provedor regulado ao produto da empresa. A fintech delega ao provedor as camadas de licença, formalização e funding. Em paralelo, a fintech constrói a experiência do cliente, a política de crédito e a camada de integração.
No contexto financeiro, uma API é um contrato de software que permite que sistemas distintos troquem dados e acionem operações de forma padronizada. O que diferencia uma API de CaaS de uma API bancária tradicional é a abrangência. Em vez de expor apenas uma funcionalidade isolada, como consulta de saldo, a API de CaaS orquestra toda a jornada de crédito: da avaliação de risco à emissão do título, passando pelo desembolso e pela cobrança. Ela também carrega a responsabilidade regulatória do provedor sobre as etapas que ele opera.
Como integrar uma API de CaaS passo a passo
Integrar uma API de CaaS é um projeto de engenharia e compliance. O processo vai além de uma simples chamada de API. Os sete passos abaixo formam a sequência recomendada para colocar a primeira operação de crédito em produção nos primeiros 90 dias.
- Decisão de arquitetura: integrar direto vs. via adapter
- Escolha e homologação do provedor
- Modelagem do fluxo de originação
- Formalização e assinatura eletrônica
- Desembolso, cobrança e webhooks
- Matriz de responsabilidade regulatória
- Boas práticas de engenharia e monitoramento
Passo 1: decisão de arquitetura, integrar direto vs. via adapter
Pré-requisitos: definição do escopo do produto de crédito e dos times de engenharia envolvidos. Envolvidos: CTO, engenheiro sênior, head de produto. Resultado esperado: interface adapter documentada e repositório com segregação de ambientes desde o primeiro commit.
Integrar o frontend diretamente às APIs do provedor cria acoplamento forte. Qualquer mudança de contrato, credencial ou provedor exige reescrita em múltiplos pontos do produto. O padrão adapter reduz esse risco ao introduzir uma camada de abstração entre o produto da fintech e o provedor de CaaS.
A arquitetura em camadas funciona assim: o produto da fintech chama apenas a interface interna do adapter. O adapter traduz essas chamadas para o contrato específico do provedor CaaS. O provedor responde de forma síncrona ou via webhook, e o adapter normaliza a resposta antes de devolvê-la ao produto. Essa separação permite trocar de provedor alterando apenas o adapter, sem tocar na lógica de negócio.
Uma interface de exemplo para o adapter pode expor métodos como criarProposta(params), consultarStatus(propostaId) e registrarDesembolso(propostaId, dados). Cada método encapsula a complexidade do contrato do provedor.
Dica útil: configure variáveis de ambiente distintas para sandbox e produção desde o primeiro commit. Nunca compartilhe credenciais entre ambientes e use flags de feature para controlar qual ambiente está ativo em cada deploy.
Passo 2: escolha e homologação do provedor CaaS
Pré-requisitos: critérios de homologação documentados internamente. Envolvidos: CTO, jurídico, compliance. Resultado esperado: checklist de homologação preenchido e aprovado antes da assinatura do contrato.
Os critérios técnicos a avaliar em sandbox incluem cobertura funcional das APIs, qualidade da documentação e dos SDKs, suporte ao desenvolvedor, SLA de disponibilidade e limites operacionais de volume e valor por operação.
Os critérios regulatórios também exigem atenção.
- Licenças do provedor: SCD, IP ou outra autorização do Banco Central.
- Credor na CCB: definição de quem figura como credor na CCB emitida.
- KYC e LGPD: definição de quem executa o KYC e como os dados são tratados sob a LGPD.
- Risco de crédito: distribuição da matriz de risco de crédito e inadimplência entre provedor e fintech.
- Correspondente bancário: aplicação das regras da Resolução CMN nº 4.935/2021 quando o provedor opera como correspondente bancário.
Boas práticas: documente os critérios de homologação em um artefato versionado. Defina em contrato os procedimentos de governança para troca de fornecedor, incluindo prazo de migração, exportação de dados e continuidade das operações em curso.
Passo 3: modelagem do fluxo de originação de crédito via API
Pré-requisitos: adapter implementado, credenciais de sandbox ativas, política de crédito definida. Envolvidos: engenheiro sênior, head de produto, compliance. Resultado esperado: diagrama de sequência de chamadas validado em sandbox com casos de sucesso e falha.
A sequência típica de chamadas em uma originação de crédito via API segue esta ordem.
- KYC: coleta e validação de dados do tomador, como nome, CPF, documentos e biometria. A responsabilidade pode recair sobre a fintech, o provedor ou ambos, conforme o contrato.
- Scoring: consulta ao motor de crédito, que pode usar bureau externo, score proprietário ou dados de Open Finance com consentimento do cliente.
- Simulação: chamada à API de simulação com valor, prazo e taxa, retornando CET, parcelas e condições.
- Proposta: criação formal da proposta com os parâmetros aceitos pelo tomador.
- Formalização: emissão da CCB ou Nota Comercial e envio para assinatura eletrônica.
- Assinatura: coleta da assinatura eletrônica avançada do tomador.
- Desembolso: acionamento do desembolso via Pix ou TED após confirmação da assinatura.
A fintech concentra sua responsabilidade na experiência do cliente, na política de crédito e na camada de integração. O provedor CaaS responde pela infraestrutura regulatória, pela emissão do título e, conforme o modelo contratado, pelo funding.
A Lei nº 10.931/2004 define a CCB como título executivo extrajudicial. A assinatura eletrônica avançada é juridicamente suficiente para sua formalização, conforme a Circular BCB nº 4.036/2020, que aceita múltiplos métodos de autenticação eletrônica sem exigir certificado ICP-Brasil.
Passo 4: formalização e assinatura eletrônica
Pré-requisitos: fluxo de originação validado em sandbox. Envolvidos: jurídico, engenheiro sênior. Resultado esperado: CCB emitida com todos os requisitos essenciais e assinatura eletrônica avançada coletada e armazenada com trilha de auditoria.
Os requisitos essenciais da CCB, conforme o art. 29 da Lei nº 10.931/2004, incluem denominação “Cédula de Crédito Bancário”, promessa de pagar dívida certa, líquida e exigível, data e lugar do pagamento, nome da instituição credora, data e lugar da emissão e assinatura do emitente.
A Lei 14.063/2020 reconhece três níveis de assinatura eletrônica no Brasil.
- Simples: e-mail, CPF digitado ou clique de aceite. Essa modalidade tem força probatória baixa e não se recomenda seu uso para CCB.
- Avançada: SMS, biometria, selfie ou OTP. Essa modalidade é juridicamente suficiente para CCB, conforme a Circular BCB nº 4.036/2020.
- Qualificada: certificado digital ICP-Brasil. Essa modalidade é exigida para atos específicos, como transferência de imóveis.
Dica útil: preserve as evidências da assinatura, como hash do documento, log de eventos com IP, timestamp e método de autenticação, além da integridade do arquivo, em armazenamento imutável. Esses registros sustentam auditorias e a executividade do título em eventual cobrança judicial.
Passo 5: desembolso, cobrança e webhooks
Pré-requisitos: CCB assinada e registrada. Envolvidos: engenheiro sênior, time de operações. Resultado esperado: desembolso processado, parcelas registradas e handler de webhook idempotente em produção.
O desembolso ocorre via Pix ou TED após a confirmação da assinatura. A cobrança abrange o registro de parcelas, a baixa de pagamentos, a repactuação em caso de atraso e o acionamento de régua de cobrança.
Eventos assíncronos, como confirmação de desembolso, pagamento de parcela e inadimplência, chegam via webhook. O design adequado para webhooks em operações de crédito segue três camadas.
- Caminho rápido: verificar a assinatura criptográfica no início do handler, persistir o corpo bruto do evento e retornar HTTP 200 em menos de 50 ms, sem executar trabalho pesado de forma síncrona.
- Sweep periódico: a cada dois minutos, buscar eventos reivindicados há mais de cinco minutos e não concluídos, liberar a reivindicação e reprocessar.
- Comparação diária: confrontar o relatório de liquidação do provedor com os registros internos para detectar eventos que nunca chegaram.
Boas práticas: use chave de idempotência composta por
tenant_id + provedor + referência de transação do provedor. Evite usar timestamp ou hash do payload como chave de idempotência, pois provedores podem reformatar payloads entre tentativas. Reclame a chave antes de executar o trabalho comINSERT ... ON CONFLICT DO NOTHING RETURNING id. Se nada for retornado, o evento já está tratado.
Passo 6: matriz de responsabilidade regulatória
Pré-requisitos: modelo de negócio e licenças da fintech definidos. Envolvidos: jurídico, compliance, CTO. Resultado esperado: matriz de responsabilidade documentada e validada antes da assinatura do contrato com o provedor.
A distribuição de responsabilidades muda conforme a fintech possui ou não licença SCD ou IP. Em geral, a fintech sem licença tende a ter o provedor como credor na CCB e a negociar a assunção de risco de crédito em contrato. A fintech com SCD ou IP assume o papel de credora e responde diretamente pelo risco de crédito, pelo reporte ao SCR e pela formalização do título.
A Resolução CMN nº 4.935/2021 disciplina a atuação de correspondentes bancários e mantém a responsabilidade regulatória central com a instituição autorizada que os contrata. A Resolução Conjunta nº 1/2020 do CMN e do BCB institui o Open Finance e obriga grandes bancos, além de facultar às demais instituições, a compartilhar dados financeiros mediante consentimento prévio, expresso e granular do cliente.
Sob a LGPD, a fintech atua como controladora ou operadora dos dados pessoais dos tomadores, conforme o arranjo contratual. As obrigações incluem base legal para tratamento, finalidade específica, minimização de dados, transparência e garantia dos direitos dos titulares, inclusive revisão de decisões automatizadas de crédito. O SCR exige que cada instituição financeira reporte operações de crédito ao Banco Central, e qualquer consulta ao SCR depende de autorização prévia do titular. O Banco Central mantém o canal de consultas públicas para receber manifestações do mercado antes da publicação de normas definitivas, incluindo temas como BaaS e Open Finance.
Passo 7: boas práticas de engenharia e monitoramento
Pré-requisitos: integração em produção. Envolvidos: engenheiro sênior, SRE. Resultado esperado: trilha de auditoria completa, alertas de discrepância ativos e segregação de ambientes garantida.
Algumas práticas de engenharia funcionam melhor quando adotadas em conjunto, pois reforçam rastreabilidade, segurança e consistência operacional.
- Idempotency-key: incluir a chave em todo POST que modifica estado, para evitar duplicidade em retentativas. Compor a chave com
tenant_id + provedor + referência do provedor. - Correlation ID: propagar um identificador único em todas as chamadas e logs para garantir rastreabilidade ponta a ponta. Usar o mesmo ID desde a requisição do cliente até o webhook de confirmação.
- Criptografia: adotar TLS 1.2 ou superior em trânsito e criptografia em repouso para dados pessoais e financeiros, reduzindo risco de vazamento.
- Trilha de auditoria: registrar cada evento com timestamp, ator, operação e resultado em armazenamento imutável, o que facilita auditorias e investigações.
- Segregação de ambientes: manter sandbox e produção com credenciais, bancos de dados e pipelines de deploy distintos desde o início, evitando cruzamento de dados.
- Assinatura de webhook: validar a assinatura criptográfica antes de qualquer efeito colateral e rejeitar imediatamente eventos com falha de validação.
Dica útil: exiba a taxa de discrepância diária entre eventos do provedor e registros internos em um painel visível para o time. Acompanhe a tendência de queda ao longo do tempo para avaliar a maturidade da integração.
Como a Celcoin se encaixa
A Celcoin oferece infraestrutura tecnológica e financeira full stack para toda a jornada de crédito, da originação à cobrança, passando por formalização, gerenciamento e integração com gestoras de fundos. A solução abrange banking, pagamentos e crédito em um único ecossistema modular, em que o cliente contrata apenas as partes que fazem sentido para o seu negócio.
Com a aquisição da VERT Capital, anunciada em agosto de 2026, a Celcoin também conecta o mercado de capitais ao ecossistema, com securitização, estruturação de operações, administração fiduciária e gestão de fundos estruturados. A VERT já emitiu mais de R$142 bilhões em operações e administra aproximadamente R$97 bilhões em ativos, com mais de 490 operações estruturadas realizadas. A jornada do crédito passa a seguir até a transformação da carteira em ativos para captação de recursos.
O cel_agents, plataforma AI First lançada em 24 de agosto de 2026 no Febraban Tech, reduz de meses para poucas horas o tempo entre a decisão de desenvolver um novo serviço financeiro e a criação de uma versão funcional. A plataforma oferece ambiente gratuito de testes disponível em poucos minutos. A integração assistida por IA via Model Context Protocol (MCP) permite que o desenvolvedor informe o que pretende construir e receba apoio contextual durante o processo, sem precisar percorrer documentação dispersa.
A tabela a seguir resume como cada funcionalidade da infraestrutura Celcoin se traduz em benefício direto para a operação de crédito da sua empresa.
| Funcionalidade da Celcoin | Benefício para sua empresa |
|---|---|
| APIs modulares | Realizar integrações mais rápidas, reduzindo custos e prazos de desenvolvimento. |
| Experiência e suporte ao desenvolvedor | Usar documentação, SDKs e sandboxes que reduzem ciclos de integração e custos de engenharia. |
| Capacidade de lançamento rápido | Aproveitar módulos pré-construídos e entrega via SaaS para acelerar lançamentos e antecipar geração de receita. |
| Distribuição white-label e embutida (embedded) | Lançar produtos financeiros com marca própria, mantendo a experiência integrada ao seu ecossistema. |
| Ter escalabilidade com confiabilidade | Operar com alta disponibilidade e escalabilidade em nuvem, mantendo serviços estáveis mesmo com altos volumes. |
| Cobertura de diversas possibilidades de pagamentos, incluindo crédito | Oferecer pagamentos e emissão de crédito para aumentar conversão, ARPU e fidelização. |
| Acesso a dados e personalização | Usar dados e análises via Open Finance para criar ofertas personalizadas e melhorar conversão e retenção. |
| Compliance e conformidade como princípio | Aplicar KYC, AML e relatórios integrados para reduzir risco regulatório e acelerar ciclos de vendas. |
| Prevenção de fraude e controles de risco | Adotar monitoramento baseado em IA e autenticação robusta para reduzir estornos, perdas e exposição regulatória. |
| Força do ecossistema de parceiros da Celcoin | Aproveitar parcerias e integrações com bancos, redes e fintechs para ganhar cobertura, recursos e velocidade de entrada no mercado. |
Explore a infraestrutura de crédito da Celcoin
Perguntas frequentes
O que é uma API de Credit as a Service e como ela se diferencia de uma API bancária tradicional?
Uma API de Credit as a Service é uma interface que expõe toda a jornada de crédito, incluindo avaliação de risco, simulação, formalização do título, desembolso e cobrança, como um serviço consumível por empresas que não precisam deter licença bancária própria para operar. O provedor de CaaS assume a responsabilidade regulatória sobre as etapas que opera, incluindo a emissão da CCB em seu nome quando a fintech não possui SCD. Uma API bancária tradicional tende a expor funcionalidades isoladas, como consulta de saldo, transferência e emissão de boleto, sem orquestrar o ciclo completo de crédito nem oferecer a camada regulatória associada. Na prática, o CaaS permite que uma fintech lance um produto de crédito completo sem construir infraestrutura bancária própria, enquanto a API bancária tradicional exige que a empresa monte essa orquestração internamente.
Quem assume o risco de crédito na integração CaaS?
A distribuição do risco de crédito depende do modelo contratual e da estrutura regulatória da fintech. Quando a fintech não possui licença SCD ou IP, o provedor de CaaS costuma figurar como credor na CCB e pode assumir o risco de inadimplência, repassando-o total ou parcialmente à fintech conforme o contrato. Quando a fintech possui SCD, ela atua como credora e assume integralmente o risco de crédito e a inadimplência. Em modelos com gestora de fundos como funding, o risco pode ser transferido ao fundo mediante cessão da CCB por endosso em preto, conforme previsto na Lei nº 10.931/2004. A definição dessa distribuição precisa constar em contrato antes do início das operações, pois ela determina requisitos de capital, obrigações de reporte ao SCR e estratégia de cobrança.
Como testar uma API de crédito em sandbox antes de ir para produção?
O ambiente de sandbox deve replicar o fluxo completo de produção, com KYC usando dados fictícios, scoring simulado, criação de proposta, emissão de CCB de teste, assinatura eletrônica em ambiente controlado, desembolso simulado e disparo de webhooks de confirmação. Os critérios de aprovação do sandbox incluem cobertura de todos os casos de sucesso e falha documentados, validação da idempotência do handler de webhook, teste de segregação de ambientes e validação da assinatura criptográfica dos webhooks. O sandbox da Celcoin pode ser acessado por meio do pacote disponível em Acesse o pacote do sandbox da Celcoin. As credenciais são obtidas acessando a documentação da Celcoin, criando uma conta de desenvolvedor e registrando uma aplicação para obter credenciais OAuth2.
Quais são os requisitos regulatórios para uma fintech que oferece crédito via API?
Os requisitos variam conforme o modelo de operação. Fintechs sem licença própria que operam via provedor de CaaS precisam formalizar o relacionamento como correspondente bancário, nos termos da Resolução CMN nº 4.935/2021, em situações em que a contratação de entidade não integrante do Sistema Financeiro Nacional depende de prévia autorização do Banco Central do Brasil. Essas fintechs também precisam garantir que o provedor detenha as licenças necessárias, como SCD, IP ou outra autorização do Banco Central. Fintechs com SCD podem emitir CCBs em nome próprio e assumem diretamente as obrigações de reporte ao SCR e de conformidade com a LGPD como controladoras dos dados dos tomadores.
Em qualquer modelo, as obrigações de KYC, prevenção à lavagem de dinheiro e proteção de dados pessoais recaem sobre a fintech. A empresa deve manter trilha de auditoria, política de privacidade robusta e, quando aplicável, indicar um Encarregado de Proteção de Dados. O uso de dados de Open Finance para scoring exige consentimento granular, específico e revogável do cliente, conforme a Resolução Conjunta nº 1/2020. O Banco Central mantém canal de consultas públicas para acompanhar a evolução regulatória de temas como BaaS e Open Finance.
Conclusão: o próximo passo da sua integração
Integrar uma API de CaaS em uma fintech representa um projeto de engenharia e compliance que começa antes do código. A definição do padrão adapter, a clareza sobre a matriz de responsabilidade regulatória e o desenho de webhooks idempotentes influenciam diretamente a capacidade de escalar a operação com segurança e previsibilidade.
A solução de crédito da Celcoin oferece infraestrutura completa para percorrer esse caminho, com APIs modulares, documentação, SDKs, sandboxes, cel_agents com ambiente de testes rápido e, com a aquisição da VERT Capital, securitização e gestão de fundos estruturados no mesmo ecossistema. A fintech passa a cobrir da originação ao funding com um único parceiro.
Fale com nossos especialistas em crédito
