Cumbuca Gateway API

Referência para a API de compartilhamento de dados do Cumbuca Open Finance: diretório de participantes, ciclo de vida do consentimento de compartilhamento de dados, endpoints de consumo de dados da Fase 2 e o portal compartilhado de gestão de consentimentos.

Contexto - Open Finance Brasil

Esta seção é uma introdução de alto nível para leitores que não conhecem o ecossistema. Se você já sabe como o Open Finance Brasil funciona, vá direto para Visão geral.

O que é o Open Finance Brasil

O Open Finance Brasil é um programa regulado pelo Banco Central que permite que clientes (pessoas físicas e jurídicas) compartilhem seus dados financeiros entre instituições de forma padronizada e segura. A mesma ideia que impulsionou a interoperabilidade do Pix é aplicada ao restante da estrutura financeira: contas, cartões, crédito, investimentos e câmbio.

O Banco Central (BACEN) define as regras e publica as APIs reguladas; um Conselho Deliberativo coordenado por uma estrutura de governança de toda a indústria as operacionaliza por meio de grupos de trabalho (segurança, experiência do cliente, infraestrutura etc.). A conformidade não é opcional: toda instituição regulada deve expor as APIs padrão da forma como a especificação define.

Papéis de participação

Cada instituição participa do ecossistema em um ou mais papéis. Para o compartilhamento de dados, os papéis se dividem em um lado passivo (detém os dados) e um lado ativo (solicita os dados):

Uma instituição pode ter múltiplos papéis simultaneamente (dados e pagamentos). Para esta referência de compartilhamento de dados, a tag relevante no diretório de participantes é DADOS; é o que você verá filtrado em GET /consent-management/v1/participants.

Cliente vs. servidor no protocolo. A divisão passivo/ativo se alinha diretamente com a divisão cliente/servidor do OAuth. O Receptor de Dados desempenha o papel de cliente OAuth: ele se registra via DCR, solicita autorização, detém o token de acesso e realiza as chamadas de API. O Transmissor de Dados desempenha o papel de Servidor de Autorização (AS) e servidor de recursos: ele autentica o usuário, emite consentimentos e tokens, e serve os endpoints regulados. Portanto, quando você ler "AS" na especificação FAPI-BR, pense no banco que detém os dados do cliente; quando ler "cliente", pense na fintech que conduz a integração.

Fases de implementação

O programa foi implementado em quatro fases. Os rótulos ainda são usados em todo lugar na especificação e nas conversas:

• Fase 1 (Dados Abertos). Informações públicas, sem necessidade de consentimento, sobre instituições, produtos, tarifas e agências.
• Fase 2 (Dados do Cliente). Compartilhamento consentido de dados de propriedade do cliente: contas, cartões, operações de crédito, investimentos e câmbio. A maioria dos GETs que você encontrará em Consumo de Dados pertence a esta fase.
• Fase 3 (Serviços). Iniciação de pagamentos e portabilidade de crédito (fora do escopo desta referência).
• Fase 4 (Extensões). Refinamentos contínuos das fases anteriores.

Como as instituições se comunicam

Dois padrões transversais regem cada requisição entre instituições:

• mTLS (TLS mútuo). Ambos os lados apresentam certificados X.509 emitidos por ACs aprovadas (CertiSign, Serpro, Soluti). O handshake TLS em si é a primeira camada de autenticação: uma instituição que não está no diretório não consegue nem abrir uma conexão.
• Assinatura de mensagens (JWS). Corpos de requisição e resposta sensíveis (como a recuperação de consentimento recorrente) são encapsulados em um JWS compacto: o corpo é uma string header.payload.signature em base64url, assinada com um certificado de assinatura separado. Isso garante a integridade de ponta a ponta, mesmo quando a mensagem passa por proxies.

Esses dois combinados implementam o perfil de segurança FAPI-BR, uma versão regional brasileira do padrão Financial-grade API da OpenID Foundation. Sobre o FAPI-BR, os blocos de construção padrão OAuth 2.0 / OIDC são utilizados:

• DCR (Dynamic Client Registration): as instituições registram seus clientes OAuth de forma programática.
• PAR (Pushed Authorisation Request): a requisição de autorização é pré-registrada no lado do detentor, de modo que a URL de redirecionamento que o usuário vê é curta, assinada e à prova de adulteração.
• Fluxo de redirecionamento OIDC: o usuário é enviado ao banco do detentor, autentica-se, autoriza e é redirecionado de volta para o callbackApplicationUri do iniciador.

Para integrações pela primeira vez, toda essa orquestração (consulta ao diretório, DCR, troca de tokens, PAR, handshake mTLS) ocorre a cada chamada. São muitas partes móveis.

Fluxo simplificado de requisição. Juntando as peças para uma leitura típica de dados autorizada:

Cada seta entre cliente e AS usa mTLS. Etapas que expõem dados privados (etapas 2 e 5/6) também carregam payloads assinados com JWS. O navegador do cliente só está envolvido nas etapas 3 e 4: o redirecionamento que dispara a autenticação e traz o usuário de volta.

O consentimento no centro

Toda leitura de dados entre instituições é ancorada em um consentimento. O consentimento é um artefato regulado criado no lado do detentor e vinculado a:

• O documento de identificação do cliente (CPF ou CNPJ).
• As permissões sendo autorizadas.
• Uma janela de expiração.
• A instituição ativa (o receptor de dados) que o solicitou.

Até que o consentimento esteja no estado AUTHORISED, nenhum recurso protegido pode ser lido. Após expirar, o detentor recusará a chamada. Monitorar o estado do consentimento e reagir a ele (veja GET /consent-management/v1/consents/{consentId}) é, portanto, central para qualquer integração.

O papel da Cumbuca

A Cumbuca atua como a infraestrutura regulatória para instituições que desejam participar como receptores de dados sem precisar construir toda a pilha FAPI-BR internamente. A estrutura de dois prefixos que você verá ao longo desta referência reflete isso:

• /consent-management/...: camada de orquestração da Cumbuca. Uma única chamada HTTP encadeia internamente DCR → token → criação do consentimento → PAR → URL de redirecionamento, de modo que o integrador lida com apenas uma requisição por operação de negócio.
• /open-finance/...: proxy transparente para as APIs reguladas. mTLS e verificação JWS das respostas ocorrem dentro do proxy.

O restante deste documento é a referência da API dessas duas camadas.

{
  "errors": [
    {
      "code": "INVALID_REQUEST",
      "title": "Validation failed",
      "detail": "data.payment.amount must be a string"
    }
  ]
}

Autenticação

Toda requisição à Cumbuca Gateway API requer um token Bearer OAuth 2.0 no header Authorization. Obtenha um token chamando POST /auth/v1/token com as credenciais do seu cliente antes de qualquer outra chamada. Os tokens têm vida curta; reutilize-os até o vencimento e depois solicite um novo.

POST /auth/v1/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>

grant_type=client_credentials

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "refresh_expires_in": 2592000
}

Diretório

[
  {
    "CustomerFriendlyName": "Banco X",
    "CustomerFriendlyLogoUri": "https://...",
    "AuthorisationServerIds": ["asid-uuid"],
    "OrgDomainRoleClaims": [
      { "Role": "DADOS", "Status": "Active" },
      { "Role": "CONTA", "Status": "Active" }
    ],
    "ApiResources": [{ "ApiFamilyType": "accounts" }],
    "Organisations": [{ "RegisteredName": "BANCO X S.A." }]
  }
]

{
  "data": "code=LxSev...&id_token=eyJ...&state=dXJu..."
}

{
  "error": "authorization_failed",
  "error_description": "authorization could not be completed"
}

Consentimento de Compartilhamento de Dados

{
  "data": {
    "callbackApplicationUri": "https://.../consent/callback",
    "loggedUser": {
      "document": { "identification": "12345678901", "rel": "CPF" }
    },
    "businessEntity": { // opcional - quando o usuário logado atua como representante de pessoa jurídica
      "document": { "identification": "12345678000199", "rel": "CNPJ" }
    },
    "permissions": [
      "ACCOUNTS_READ", "ACCOUNTS_BALANCES_READ",
      "RESOURCES_READ"
    ],
    "expirationDateTime": "2026-05-28T15:10:00Z"
  }
}

{
  "data": {
    "consentId": "urn:cumbuca:C123ABC...",
    "redirectUrl": "https://auth.bank.example/oauth2/authorize?..."
  }
}

{
  "data": {
    "consentId": "urn:raidiambank:c4bb1a06-8dcf-4935-9696-b40bf6911f50",
    "consent": {
      "data": {
        "consentId": "urn:raidiambank:c4bb1a06-...",
        "status": "AUTHORISED",
        "creationDateTime": "2026-01-29T16:34:29Z",
        "statusUpdateDateTime": "2026-01-29T16:34:41Z",
        "expirationDateTime": "2026-07-29T16:34:27Z",
        "permissions": ["ACCOUNTS_READ", "ACCOUNTS_BALANCES_READ", "RESOURCES_READ"]
      },
      "links": { "self": "https://matls-api.<bank>/open-finance/consents/v3/consents/<consentId>" },
      "meta": { "requestDateTime": "2026-01-29T16:35:00Z" }
    }
  }
}

Ciclo de vida do consentimento. Além da criação e da consulta, três operações de ciclo de vida estão disponíveis na referência da API: DELETE /consent-management/v1/consents/{consentId} revoga o consentimento (retorna 204); POST .../consents/{consentId}/authorisation-retry gera uma nova redirectUrl quando a tentativa original de autorização caducou (ex.: o usuário abandonou o redirecionamento ao banco); e POST .../consents/{consentId}/extends renova a expiração de um consentimento AUTHORISED. Apenas este POST exige adicionalmente os headers x-customer-user-agent e x-fapi-customer-ip-address, e um GET no mesmo caminho lista o histórico de extensões.

Consumo de Dados (Fase 2) - GETs Autenticados

Todos os endpoints nesta seção seguem o mesmo formato:

• Método: GET
• Headers: Authorization: Bearer <access_token>, x-authorisation-server-id, x-consent-id
• Resposta: { "data": [...] } (formato regulado do OF Brasil)
• Retentativas: leituras de dados são cobráveis; veja Limites de requisições e Timeouts e retentativas antes de adicionar lógica de retentativa.

Clientes

Contas (Corrente / Poupança)

Cartões de Crédito

Operações de Crédito (4 famílias)

Formato genérico para os escopos loans, financings, invoice-financings e unarranged-accounts-overdraft:

Investimentos (5 famílias)

Escopos: bank-fixed-incomes, credit-fixed-incomes, variable-incomes, treasure-titles, funds.

Câmbio (FX)

Recursos (descoberta)

Reciprocidade

Como receptor de dados, você também deve disponibilizar ao ecossistema os dados cadastrais dos seus próprios correntistas (reciprocidade). A escrita abaixo popula o repositório de reciprocidade que a Cumbuca serve em seu nome: uma vez registrado o cliente, outros participantes do Open Finance que consultarem sua instituição recebem uma verificação positiva de correntista e os dados de identificação registrados.

{
  "data": { "cpf": "12345678901" }
}

Gestão de Consentimentos

Permite que o usuário final visualize, gerencie e revogue todos os consentimentos que autorizou para o cliente. A chamada retorna uma URL de uso único; redirecione o usuário para lá a fim de abrir o portal de gestão. Veja também Reciprocidade para a escrita de registro que mantém os dados dos seus próprios correntistas disponíveis ao ecossistema.

{
  "document": "12345678901",
  "representativeCpf": "98765432100"
}

{
  "redirectUrl": "https://.../management/?token=..."
}

Apêndice

Mapeamento de permissões

O Open Finance Brasil organiza as permissões por categoria de dados e agrupamento (a unidade granular de compartilhamento que o usuário autoriza). Cada agrupamento mapeia para um conjunto de strings de permissão reguladas. RESOURCES_READ deve sempre ser incluído ao criar um consentimento de compartilhamento de dados.

Cumbuca Gateway API - Compartilhamento de Dados.