Como integrar emissão de CCB via API: guia técnico

Principais lições deste artigo

• Integrar emissão de CCB via API exige separar a camada de originação, que cuida da decisão de crédito e do motor de risco, da camada de escrituração, que cuida da formalização jurídica e do registro em sistema autorizado pelo BCB.
• A Circular BCB 4.036/2020 define estados obrigatórios do título, como DRAFT, AWAITING_SIGNATURE, REGISTERED e REJECTED, e exige controle de titularidade, fluxos financeiros e cadeia de endossos.
• Fintechs sem licença SCD ou IP precisam de um parceiro licenciado. Fintechs com licença própria se beneficiam de infraestrutura especializada para formalização e cobrança.
• HTTP 200 não confirma CCB emitida. A operação passa por múltiplos estados e o desembolso só deve ocorrer após confirmação do estado REGISTERED e obtenção do IPOC.
• Idempotência, máquina de estados e trilha de auditoria formam pilares técnicos que evitam duplicidade e garantem conformidade regulatória, e a Celcoin oferece essa infraestrutura completa para fintechs.

Conheça a solução de crédito da Celcoin

Modelo de parceria regulatória: licença própria (SCD/IP) vs. parceiro licenciado

A Lei nº 10.931/2004, alterada pela Lei nº 13.986/2020, define a CCB como título de crédito emitido em favor de instituição financeira ou entidade equiparada. A versão escritural está prevista nos arts. 27-A a 27-D da mesma lei. Ela é lançada em sistema eletrônico de escrituração mantido por instituição financeira ou entidade autorizada pelo Banco Central, com controle de informações do título, titularidade, fluxos financeiros, pagamentos, cadeia de endossos, aditamentos, retificações, notificações e garantias, conforme a Circular BCB 4.036/2020 e a regulamentação do sistema de escrituração.

Emitir CCB escritural exige que a parte credora seja uma instituição financeira autorizada pelo Banco Central, como uma Sociedade de Crédito Direto (SCD), regulada pela Resolução CMN 4.656/2018. A instituição financeira somente pode escriturar cédulas representativas de suas próprias operações de crédito, com possibilidade de transferir a escrituração a outra instituição financeira nas hipóteses previstas na regulamentação.

Gerar um PDF com o texto de uma CCB sem o respaldo de um sistema eletrônico de escrituração não produz o mesmo efeito jurídico de uma CCB escritural. A escrituração pode ser realizada pelos sistemas internos das próprias instituições financeiras, dispensada autorização específica do BC. Sem essa escrituração, o documento não é CCB escritural, não tem certidão de inteiro teor como título executivo extrajudicial (art. 27-C da Lei 10.931/2004) e não circula com a mesma segurança para cessão a FIDCs ou securitizadoras.

Fintechs que ainda não possuem licença SCD ou IP podem operar via parceiro licenciado no modelo Credit as a Service (CaaS), utilizando a licença e a infraestrutura de escrituração do parceiro. Fintechs que já possuem licença própria continuam se beneficiando de infraestrutura especializada para originação, formalização e cobrança, sem precisar construir e manter toda a pilha tecnológica internamente.

A solução de crédito da Celcoin fornece sua licença SCD quando a fintech ainda não tem a sua. Quando a fintech já possui licença própria, continua utilizando a infraestrutura da Celcoin para originação, formalização e cobrança. A Celcoin fornece infraestrutura tecnológica para que empresas ofereçam produtos de crédito aos seus clientes finais.

Conheça a solução de crédito da Celcoin

Arquitetura de integração em duas camadas: da originação ao desembolso

A integração de emissão de CCB via API se organiza em duas camadas funcionais com responsabilidades e pontos de falha próprios.

Camada 1, originação e assinatura:

1. O sistema da fintech submete a proposta de crédito aprovada, com dados do tomador, valor, prazo, taxa e garantias, ao endpoint de criação de CCB.
2. A API retorna um identificador de operação e o título entra no estado DRAFT.
3. O documento é apresentado ao tomador para assinatura eletrônica com identificação inequívoca do signatário.
4. Após a confirmação da assinatura, o estado avança para SIGNED.

Camada 2, escrituração e registro:

1. O título assinado é submetido ao sistema de escrituração, entrando no estado SUBMITTING.
2. O sistema de escrituração valida os dados e registra o título, que passa ao estado REGISTERED.
3. Somente após a confirmação de registro o sistema libera o desembolso.

O ponto crítico em operações reais é a lacuna entre SIGNED e REGISTERED. A fintech que libera o dinheiro antes da confirmação de escrituração assume risco jurídico e financeiro. O título pode ser rejeitado por inconsistência de dados, assinatura inválida ou falha no sistema de escrituração. O sistema deve condicionar o desembolso ao evento de registro confirmado, entregue via webhook ou polling com backoff exponencial.

Um payload conceitual de criação de CCB inclui campos como:

{ "borrower": { "cpf": "...", "name": "..." }, "principal": 10000.00, "interest_rate_monthly": 0.02, "installments": 12, "first_due_date": "2026-11-01", "idempotency_key": "uuid-v4-gerado-pelo-cliente" }

A resposta inicial retorna o identificador da operação e o estado DRAFT, e não a CCB emitida.

Veja como emitir CCB com a infraestrutura da Celcoin

Máquina de estados para emissão de CCB: por que HTTP 200 não significa CCB emitida

A emissão de CCB via API segue um processo assíncrono com múltiplos estados intermediários. Tratar a resposta HTTP 200 da chamada inicial como confirmação de emissão gera inconsistências em produção.

Estado	Descrição	Ação da fintech
DRAFT	Proposta recebida, com dados ainda não validados pelo sistema de escrituração.	Aguardar transição e não liberar desembolso.
VALIDATING	Sistema de escrituração validando dados do título, do tomador e das garantias.	Monitorar via webhook ou polling e registrar timestamp de entrada.
AWAITING_SIGNATURE	Título gerado e aguardando assinatura eletrônica do tomador e do garantidor, quando existir.	Acionar fluxo de assinatura e definir timeout e ação em caso de expiração.
SIGNED	Assinatura confirmada com identificação inequívoca do signatário.	Submeter à escrituração e armazenar hash, timestamp e evidências de assinatura.
SUBMITTING	Título em trânsito para o sistema de escrituração autorizado pelo BCB.	Aguardar confirmação e verificar idempotência antes de reenviar.
REGISTERED	CCB escriturada e registrada com IPOC atribuído, com validade jurídica.	Liberar desembolso e iniciar conciliação de parcelas com o IPOC.
REJECTED	Escrituração recusada por inconsistência de dados, assinatura inválida ou erro regulatório.	Registrar motivo, acionar fluxo de correção ou cancelamento e notificar o tomador.
CANCELLED	Operação cancelada antes do registro, por iniciativa da fintech ou do tomador.	Garantir que nenhum desembolso foi realizado e registrar o evento para auditoria.

Cada transição de estado deve ser persistida no banco de dados da fintech com timestamp, origem do evento, que pode ser webhook, polling ou ação manual, e payload completo. Esse registro forma a trilha de auditoria exigida em fiscalizações e em disputas judiciais sobre a validade do título.

Do ponto de vista de sistemas distribuídos, a máquina de estados da CCB segue um saga pattern. Cada etapa é uma transação local com compensação definida em caso de falha. A fintech que não modela as compensações, como o que fazer quando SUBMITTING não avança para REGISTERED em um tempo definido, opera com risco de estados órfãos e carteira inconsistente.

Aprofunde a modelagem de estados com a infraestrutura da Celcoin

Idempotência em API de crédito e tratamento de falhas

Idempotência em APIs de crédito evita a emissão duplicada de CCBs para a mesma operação. Sem esse controle, o sistema pode gerar dois desembolsos e duas obrigações jurídicas para o mesmo tomador. Idempotência significa que a mesma requisição, enviada múltiplas vezes, produz o mesmo resultado da primeira execução.

O mecanismo padrão é o cabeçalho Idempotency-Key, um UUID v4 gerado pelo sistema da fintech antes da primeira tentativa e reutilizado em todos os retries da mesma operação:

POST /ccb/v1/operations Content-Type: application/json Authorization: Bearer {access_token} Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000 { ... payload da operação ... }

O servidor armazena a chave e o resultado da primeira execução bem-sucedida. Requisições subsequentes com a mesma chave retornam o resultado armazenado sem reprocessar a operação. A fintech deve começar gerando a Idempotency-Key antes da primeira tentativa e persistindo o par de chave e identificador da operação no banco de dados local. Essa chave garante que um retry não crie uma segunda CCB.

Para falhas transitórias, o retry deve usar backoff exponencial com jitter apenas em erros 5xx e timeouts. Erros 4xx indicam problema na requisição e não devem ser repetidos. A fintech precisa definir um timeout máximo de espera por transição de estado e uma ação de compensação explícita quando esse limite é atingido. Manter uma tabela de mensagens, seguindo o outbox pattern, para eventos assíncronos também é essencial. O sistema grava o evento localmente antes de enviar, o que garante que nenhuma transição de estado se perca em caso de falha de rede.

Para conciliação de eventos assíncronos via webhook, a fintech deve validar a autenticidade do payload, por exemplo com assinatura HMAC ou mTLS no endpoint receptor. O processamento do evento precisa ser idempotente, com verificação prévia se o estado já foi aplicado antes de persistir. A aplicação deve responder HTTP 200 imediatamente e delegar o processamento a uma fila assíncrona.

Implemente idempotência de ponta a ponta com a Celcoin

Assinatura eletrônica e integridade do título

O art. 29, § 5.º, da Lei nº 10.931/2004, incluído pela Lei nº 13.986/2020, admite assinatura eletrônica na CCB desde que garantida a identificação inequívoca do signatário. A Circular BCB 4.036/2020 aceita múltiplos métodos de autenticação eletrônica para CCB, incluindo biometria e senha, sem exigir certificado ICP-Brasil.

A Lei 14.063/2020 classifica as assinaturas eletrônicas em três níveis: simples, avançada e qualificada. Para CCBs, a assinatura avançada, que vincula o documento à identidade do signatário de forma unívoca e detecta qualquer modificação posterior, é juridicamente suficiente, conforme decisão do STJ de 2024 que validou uma CCB assinada via plataforma não credenciada à ICP-Brasil. A assinatura qualificada com certificado ICP-Brasil (A1 ou A3) oferece presunção legal de veracidade mais robusta e se torna recomendada em operações de maior valor ou em estruturas de cessão que exigem maior segurança probatória.

O sistema deve armazenar, para cada assinatura:

• Hash SHA-256 do documento no momento da assinatura, em canal separado do arquivo assinado.
• Timestamp com carimbo de tempo, preferencialmente RFC 3161 emitido por Autoridade de Carimbo do Tempo credenciada pela ICP-Brasil.
• Evidências de autenticação, como IP, geolocalização, método utilizado, biometria, OTP ou selfie, e versão dos termos apresentados ao signatário.
• Trilha de auditoria imutável com registro de quem assinou, quando e por qual canal.

A diferença prática entre assinatura eletrônica avançada e qualificada ganha relevância quando a CCB será cedida a estruturas que exigem maior grau de certeza jurídica, como FIDCs com diligência rigorosa de investidores institucionais. A política de assinatura deve ser definida em conjunto com o time jurídico e o gestor do fundo antes da implementação técnica.

Defina sua política de assinatura com o apoio da Celcoin

O que é IPOC na CCB e como usá-lo para conciliação

O IPOC, Identificador Padronizado de Operação de Crédito, é o identificador único atribuído a todas as operações de crédito informadas ao Sistema de Informações de Créditos (SCR). Ele é formado pela concatenação do CNPJ da instituição, modalidade da operação, tipo do cliente, código do cliente e código do contrato. Esse identificador funciona como chave de unicidade para conciliação de parcelas, eventos de pagamento e cessões.

O IPOC é distinto do número de contrato interno da instituição. Enquanto o número de contrato é gerado pelo sistema da fintech ou do parceiro, o IPOC é o identificador padronizado de mercado que permite rastrear a operação em diferentes sistemas e instituições.

Na prática da integração, o sistema de escrituração atribui o IPOC no momento do registro, no estado REGISTERED. A fintech deve armazenar esse identificador imediatamente como chave primária de conciliação. Todas as parcelas, eventos de pagamento, aditamentos e cessões posteriores precisam referenciar o IPOC da operação original.

A ausência de IPOC consistente na base de dados da fintech gera três problemas concretos:

• Retrabalho de auditoria: sem o IPOC, a conciliação entre o sistema interno e o sistema de escrituração exige cruzamento manual de múltiplos campos, o que aumenta o custo operacional e o risco de erro.
• Falha na cessão: estruturas de cessão para FIDCs e securitizadoras exigem que o IPOC conste na documentação da operação cedida, e a ausência desse dado pode inviabilizar ou atrasar a cessão.
• Risco regulatório: o Banco Central do Brasil utiliza o IPOC para identificar de forma única as operações de crédito informadas ao SCR, que apoia o monitoramento do crédito no sistema financeiro. Inconsistências no reporte podem gerar notificações regulatórias.

A conciliação correta segue um fluxo simples. Ao receber o evento REGISTERED via webhook, a fintech extrai o IPOC do payload, persiste no registro da operação e usa esse identificador para reconciliar todos os eventos subsequentes, como pagamentos, inadimplência, liquidação antecipada e cessão.

Estruture sua conciliação com IPOC usando a Celcoin

Segurança de credenciais: mTLS, OAuth2 e KMS/HSM

APIs de crédito operam sobre dados financeiros e jurídicos sensíveis. A segurança de credenciais é requisito regulatório e pré-condição para a validade das operações.

mTLS, mutual TLS: a autenticação mútua exige que cliente e servidor apresentem certificados. O certificado do cliente identifica o sistema da fintech perante a API do parceiro e reduz o risco de requisições não autorizadas mesmo em caso de comprometimento de um token OAuth. O sistema deve armazenar certificados mTLS em KMS, Key Management Service, ou HSM, Hardware Security Module, e não em variáveis de ambiente em texto plano, repositórios de código ou imagens de container.

OAuth 2.0: o fluxo client_credentials é o padrão de mercado para comunicação segura servidor para servidor em APIs de crédito, como a da Creditas. Algumas APIs de crédito, como a do Mercado Pago, também oferecem outros fluxos OAuth 2.0, como o Authorization Code. O access token tem validade curta, com variação por provedor. No Google Cloud, por padrão, tokens de acesso são válidos por 1 hora, enquanto em muitas implementações o tempo típico fica entre 5 e 15 minutos. O sistema da fintech deve renovar o token automaticamente antes da expiração. O refresh token, quando existir, precisa de proteção equivalente à da chave privada.

Algumas boas práticas de segurança de credenciais incluem:

• Armazenar chaves privadas e certificados exclusivamente em KMS ou HSM gerenciado, com acesso auditado e controlado por IAM.
• Implementar rotação automática de credenciais com janela de sobreposição, em que a credencial antiga e a nova coexistem, para evitar indisponibilidade durante a rotação.
• Segregar completamente os ambientes de sandbox e produção, com credenciais, endpoints, bases de dados e pipelines de deploy distintos.
• Evitar logar tokens, chaves ou payloads completos de autenticação em sistemas de observabilidade, mascarando campos sensíveis antes do log.
• Monitorar tentativas de autenticação com falha e configurar alertas para padrões anômalos.

Reforce a segurança das suas integrações com a Celcoin

Como emitir o CCB: um fluxo de 7 passos

Com a arquitetura, os estados, a idempotência e a segurança definidos, o fluxo completo de emissão pode ser resumido em sete etapas.

1. Proposta: o sistema da fintech submete os dados da operação aprovada, com tomador, valor, prazo, taxa e garantias, à API de criação de CCB com Idempotency-Key gerada previamente.
2. Aprovação: o sistema de escrituração valida os dados regulatórios e contratuais, e a operação avança de DRAFT para VALIDATING.
3. Modelagem: o título é gerado com os requisitos essenciais da Lei nº 10.931/2004, como denominação, promessa de pagamento, datas, valores de parcelas, nome da instituição credora e lugar e data de emissão. O estado avança para AWAITING_SIGNATURE.
4. Assinatura: o tomador e o garantidor, quando houver, assinam eletronicamente com identificação inequívoca. O sistema coleta e armazena evidências, e o estado avança para SIGNED.
5. Submissão: o título assinado é enviado ao sistema de escrituração autorizado pelo BCB, e o estado avança para SUBMITTING.
6. Registro: o sistema de escrituração registra o título, atribui o IPOC e confirma via webhook. O estado avança para REGISTERED.
7. Desembolso: após a confirmação de REGISTERED, o sistema da fintech autoriza a liberação dos recursos ao tomador e inicia a conciliação de parcelas referenciada pelo IPOC.

Implemente esse fluxo de emissão de CCB com a Celcoin

A infraestrutura da Celcoin para emissão de CCB via API

Implementar esse fluxo internamente exige licença, escrituração e cobrança. A solução de crédito da Celcoin oferece infraestrutura tecnológica e financeira full stack para toda a jornada de crédito, da originação à cobrança, com SCD própria para emissão de CCB escritural. Para fintechs que ainda não possuem licença regulatória, a Celcoin fornece sua licença. Para fintechs que já possuem licença própria, a infraestrutura da Celcoin cobre originação, formalização, gestão de carteira e cobrança, com APIs modulares que permitem contratar apenas os módulos necessários.

Para reduzir o tempo de integração, a Celcoin lançou o cel_agents em agosto de 2026. Por meio do Model Context Protocol, MCP, a inteligência artificial acessa o contexto técnico dos produtos da Celcoin e apoia o desenvolvedor durante a implementação. Esse apoio reduz de meses para poucas horas o tempo entre a decisão de desenvolver um novo serviço e a criação de uma versão funcional. Um ambiente gratuito de testes fica disponível em poucos minutos. O cel_agents Studio permite que profissionais de produto visualizem e testem jornadas financeiras de forma interativa, sem necessidade de conhecimento em programação.

Com a aquisição da VERT Capital, anunciada em agosto de 2026, a jornada do crédito na Celcoin passa a conectar também securitização, estruturação de operações, administração fiduciária e gestão de fundos estruturados. Essa combinação cobre da originação ao funding em um único ecossistema, com contratação modular. A Celcoin atua com neutralidade e não compete com os clientes que atende.

A tabela a seguir resume como cada funcionalidade da infraestrutura da Celcoin se traduz em ganho concreto para a fintech que integra a emissão de CCB.

Funcionalidade da Celcoin	Benefício para sua empresa
APIs modulares	Integrações mais rápidas, com redução de custos e prazos de desenvolvimento.
Experiência e suporte ao desenvolvedor	Documentação, SDKs e sandboxes que reduzem 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 e melhoram o tempo para geração de receita.
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 em altos volumes e protege a receita.
Cobertura de diversas possibilidades de pagamentos, incluindo crédito	Oferta combinada de 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 e melhoram 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 contínuo e ferramentas de prevenção reduzem perdas e protegem a carteira.

Conecte sua emissão de CCB à infraestrutura completa da Celcoin

Saiba mais

• Melhor API para emissão de CCB: comparativo de soluções
• Vantagens da emissão eletrônica de CCB para fintechs
• Melhor solução para emissão de CCB para fintechs
• Segurança de dados em API para emissão de CCB: guia prático
• Como integrar emissão digital de CCB a sistemas financeiros