Cumbuca Gateway API — Início rápido

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 /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:

   ┌─────────────────────┐                       ┌──────────────────────┐
   │     Cliente         │                       │     Diretório        │
   │  (navegador / app)  │                       │  (Open Finance BR)   │
   └──────────┬──────────┘                       └──────────┬───────────┘
              │                                             │
              │   1. clica em "conectar banco"              │ (lista participantes
              ▼                                             │  ativos, certificados,
   ┌─────────────────────┐    0. descoberta (GET lista) ────▶  metadados)
   │     Cliente         │◀────────────────────────────────┤
   │  (Receptor)         │                                 │
   │   lado ativo        │                                 └──────────────┘
   │  ─ cliente OAuth ─  │
   └──────────┬──────────┘
              │
              │  2. DCR + PAR + criação do consentimento
              │     (mTLS + JWS, via HTTPS)
              ▼
   ┌─────────────────────┐    3. redirect do navegador ──▶  ┌─────────────┐
   │   Servidor de       │       usuário autentica e        │  Cliente    │
   │   Autorização (AS)  │       autoriza o consentimento   │  autoriza   │
   │   Transmissor       │◀───── 4. callback ───────────────│  no AS      │
   │   de Dados          │                                  └─────────────┘
   │   lado passivo      │
   │  ─ servidor OAuth ─ │
   └──────────┬──────────┘
              │
              │  5. chamada de API autorizada
              │     (mTLS + token de acesso + payload JWS)
              ▼
   ┌─────────────────────┐
   │   Servidor de       │       6. resposta (assinada com JWS
   │   recursos no AS    │          para endpoints sensíveis)
   └─────────────────────┘

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 /consents/v1/consents/{id} — é, 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_token_expires_in": 2592000
}

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

grant_type=refresh_token&refresh_token=<seu-refresh-token>

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." }]
  }
]

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" }
    }
  }
}

Consumo de Dados (Fase 2) — GETs Autenticados

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

• Método: GET
• Headers: x-authorisation-server-id, x-consent-id, x-cumbuca-consent-token
• Resposta: { "data": [...] } — formato regulado do OF Brasil
• Retentativas: leituras de dados são cobráveis e podem ter limites de taxa; trate-as como não idempotentes para fins 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)

Gestão de Consentimentos (Portal Compartilhado)

Diferente do restante da API, o portal de gestão de consentimentos é servido por uma URL base separada e não utiliza os headers de autenticação padrão (mTLS + x-cumbuca-consent-token). Em vez disso, o cliente constrói um JWT assinado com PS256 e o envia via POST como corpo bruto da requisição com content-type: application/jwt. A resposta contém uma redirectUrl para a qual o usuário final deve ser enviado a fim de visualizar, gerenciar e revogar seus consentimentos.

Visão geral do fluxo

1. O usuário final solicita acesso para "gerenciar meus consentimentos".
2. O cliente obtém o CPF ou CNPJ do usuário (e, quando aplicável, o CPF do representante para fluxos de pessoa jurídica).
3. O cliente constrói as claims do JWT — o formato depende se o usuário é pessoa física ou jurídica.
4. O JWT é assinado com PS256 usando uma chave privada cujo kid foi pré-registrado no serviço de consentimento compartilhado.
5. O cliente envia via POST o JWS compacto para o endpoint de consentimento compartilhado.
6. O serviço retorna uma URL de uso único com a sessão embutida nela. O usuário final é redirecionado para essa URL.

JWT — claims & assinatura

{
  "alg": "PS256",
  "typ": "JWT",
  "kid": "<key-id-registered-with-cumbuca>"
}

{
  "jti": "01956c8e-...",
  "iat": 1748448000,
  "cpf": "12345678901",
  "brandId": "<your-brand-id>",
  "name": "Open Finance Brasil"
}

• jti — identificador único do JWT (UUIDv7 recomendado).
• iat — segundos em epoch, data de emissão.
• name — string constante.

{
  "jti": "01956c8e-...",
  "iat": 1748448000,
  "cnpj": "12345678000199",
  "brandId": "<your-brand-id>",
  "name": "Open Finance Brasil",
  "cpf": "12345678901"
}

cpf é opcional nas claims de pessoa jurídica — usado para carregar o CPF do representante.

Assine o mapa de claims com a chave privada registrada (PS256) e serialize como JWS compacto. Resultado:

eyJhbGciOiJQUzI1NiIsImtpZCI6IjwuLi4-IiwidHlwIjoiSldUIn0.<payload>.<signature>

A chave de assinatura (um JWK) é provisionada pela Cumbuca e identificada pelo seu kid. A rotação de chave pública segue o padrão de rotação JWKS padrão.

eyJhbGciOiJQUzI1NiIsImtpZCI6IjwuLi4-IiwidHlwIjoiSldUIn0.eyJqdGkiOiIuLi4iLCJpYXQiOjE3NDg0NDgwMDAsImNwZiI6IjEyMzQ1Njc4OTAxIiwiYnJhbmRJZCI6IjwuLi4-IiwibmFtZSI6Ik9wZW4gRmluYW5jZSBCcmFzaWwifQ.<signature>

{
  "redirectUrl": "https://shared-consent.../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 Open Finance — Compartilhamento de Dados.