Reciprocidade

Como a Cumbuca Gateway API cumpre o dever de reciprocidade do Open Finance, responder às consultas de outros participantes sobre os seus correntistas, nos dois modos de operação: sem delegação, em que a Cumbuca armazena os cadastros e responde por você, e com delegação, em que cada consulta é encaminhada ao vivo, via mTLS, para um serviço que você mesmo opera.

O que é Reciprocidade

Participar do Open Finance Brasil como receptor de dados traz consigo um dever de reciprocidade: outros participantes podem perguntar se um determinado documento pertence a um correntista da sua instituição e ler os dados cadastrais (identificação) desse cliente. A Cumbuca cumpre esse dever de duas formas, definidas por uma única configuração de instância, a delegação.

Com e sem delegação

Sem delegação (delegação desativada), o padrão. A Cumbuca armazena os cadastros dos clientes que conhece (pelo registro automático que segue um consentimento autorizado, ou pelas escritas PUT /personal/identifications/register e PUT /business/identifications/register) e responde ela mesma às consultas do ecossistema, a partir do próprio armazenamento. O seu serviço não é chamado.

Com delegação (delegação ativada). A Cumbuca não armazena nada. Toda consulta de reciprocidade é encaminhada ao vivo, via mTLS, para um serviço que você implementa e opera. Ele passa a ser a fonte da verdade.

Comparação

Registro Automático (sem delegação)

Quando a instância não delega, é a própria Cumbuca que precisa conhecer os seus correntistas para responder às consultas de reciprocidade. Ela popula esse armazenamento automaticamente, sem nenhuma ação do parceiro, a partir dos consentimentos de compartilhamento de dados criados pela sua instância:

1. Ao criar um consentimento de compartilhamento, a Cumbuca passa a acompanhá-lo.
2. O Open Finance não notifica mudança de status, então a Cumbuca faz polling do consentimento até ele chegar a AUTHORISED (ou expirar, quando o ecossistema recusa consentimentos não autorizados em ~1 h).
3. Uma vez autorizado, a Cumbuca lê as identificações do cliente pelo próprio consentimento (leitura billable) e grava cada registro no seu armazenamento, com x-data-source: internal. Um consentimento de pessoa física alimenta /personal/identifications; um consentimento de pessoa jurídica (que carrega businessEntity) alimenta /business/identifications.

Os dois são independentes: um consentimento que concede as duas permissions registra ambos, e uma falha em um lado nunca bloqueia o outro.

O registro é idempotente, então reexecuções são inofensivas. Para os registros de pessoa física, um dado escrito por você (via PUT /personal/identifications/register, com origem tenant) tem precedência sobre o registro automático interno e nunca é sobrescrito por ele.

Permissions obrigatórias

O registro automático só é possível se o consentimento carregar a permission que autoriza a Cumbuca a ler os dados de identificação do cliente. Por isso, quando a instância não delega, a Cumbuca adiciona a permission correspondente automaticamente na criação do consentimento, garantindo que o cadastro de reciprocidade possa ser populado:

Apenas a permission de identificações é adicionada. Os dados de qualificação e de relacionamento financeiro são derivados do mesmo corpo de identificações, portanto não exigem leitura separada.

Com Delegação: o Contrato do Seu Serviço

Quando a sua instância delega, você entrega à Cumbuca uma URL base no onboarding. HTTPS é obrigatório em produção e homologação. Sob essa URL base, seu serviço deve implementar os endpoints JSON POST abaixo; os caminhos são relativos a essa URL base. Os endpoints de pessoa jurídica (PJ) só são obrigatórios se a sua instituição atende clientes pessoa jurídica.

• Toda requisição enviada pela Cumbuca é um POST JSON com content-type: application/json. Os documentos trafegam apenas no corpo, nunca na query string.
• Toda requisição carrega o header x-nexus-request-id (UUIDv7). Registre-o em log: ele também é ecoado como header de resposta em toda resposta do gateway Cumbuca, funcionando como chave de correlação entre serviços para suporte.
• As respostas devem ser HTTP 200 com exatamente os formatos JSON documentados abaixo. Formatos errados não são tolerados em nenhum ponto da cadeia: eles falham a consulta (veja o mapeamento de erros).

{
  "cpf": "12345678901",
  "cnpj": "12345678000199" // opcional
}

{
  "data": { "isAccountHolder": true }
}

{
  "cpf": "12345678901"
}

{
  "data": [
    { /* registro personal-identifications do Open Finance Brasil */ }
  ]
}

{
  "cnpj": "12345678000199"
}

{
  "data": [
    { /* registro business-identifications do Open Finance Brasil */ }
  ]
}

{
  "cpf": "12345678901"    // "cnpj" nos caminhos de pessoa jurídica
}

{
  "data": { /* objeto de qualification / financial-relations do Open Finance Brasil */ }
}

mTLS no Trecho Delegado

Toda chamada da Cumbuca para o seu serviço trafega sobre TLS mútuo. Não há bearer token nem API key nesse trecho: o certificado de cliente do gateway é a única autenticação.

• O que a Cumbuca apresenta: um certificado de cliente do gateway em toda chamada delegada. Seu serviço deve exigir um certificado de cliente e validar / permitir explicitamente o da Cumbuca; conexões sem ele devem ser rejeitadas. O certificado é trocado durante o onboarding.
• O que você deve servir: um certificado TLS de servidor encadeado a uma CA pública. Se o seu não for, forneça sua cadeia de CA à Cumbuca no onboarding para que seja adicionada ao trust store do gateway.
• Sem fallback em texto claro: em produção e homologação, se o certificado de cliente do gateway estiver indisponível a Cumbuca recusa a chamada (502 DELEGATED_UNAVAILABLE) em vez de chamar sem mTLS. Além disso, uma instância delegada sequer inicializa sem o certificado configurado.

Orçamento de Timeout

• O gateway espera até 30 segundos pela sua resposta: o timeout de recepção configurado nele, que tem padrão de 30 s e pode variar por implantação (o trecho interno que a precede tem um orçamento fixo de 30 segundos). Responda com folga dentro desse limite, idealmente bem abaixo de um segundo, já que essas consultas ficam no caminho de requisição de outra instituição.
• Tentativa única, sem retry. Uma resposta lenta ou com falha falha imediatamente a consulta; o gateway não tenta de novo.

Semântica de Falhas

• Sem resposta padrão de fallback. Quando seu serviço está fora do ar, estoura o timeout ou responde com formato errado, a consulta de reciprocidade falha: a instituição solicitante recebe um erro, nunca um "não é correntista" por padrão.
• Seus corpos de erro são descartados. Quando seu serviço responde um status diferente de 200, a Cumbuca repassa o status com um envelope genérico DELEGATED_ERROR e descarta o seu corpo de resposta (proteção de PII). Não conte com a propagação de detalhes de erro; use o x-nexus-request-id e seus próprios logs.
• Envelope de erro. Os erros do gateway seguem o formato Open Finance {"errors":[{"code","title","detail"}]} e carregam os headers de resposta x-nexus-request-id e x-nexus-error-source (client | upstream | gateway).

Mapeamento de erros

O que cada comportamento do seu serviço produz na cadeia:

O Que Muda Quando Você Delega

Registro retorna 422

Em uma instância delegada, as duas escritas de registro voltadas ao parceiro, PUT /personal/identifications/register e PUT /business/identifications/register, são sempre recusadas: toda requisição autenticada e bem-formada recebe 422 e nada é armazenado (corpos malformados ainda recebem os genéricos 400/415, e autenticação ausente recebe 401):

HTTP/1.1 422
x-nexus-error-source: client
x-nexus-request-id: <uuidv7>

{
  "errors": [
    {
      "code": "UNKNOWN",
      "title": "Unknown Error",
      "detail": "Registration not supported for a delegated client"
    }
  ],
  "meta": { "requestDateTime": "2026-07-15T12:00:00Z" }
}

Não chame o registro em uma instância delegada; trate esse 422 como a resposta esperada e permanente.

Registro automático é ignorado

O registro automático que popula o armazenamento da Cumbuca não se aplica quando você delega. Depois que um consentimento chega a AUTHORISED, a Cumbuca ainda tenta a gravação interna, tanto de pessoa física quanto de pessoa jurídica, mas ela é recusada com o mesmo 422 (nada é armazenado na Cumbuca) e a etapa é silenciosamente ignorada. O seu serviço é o único lugar de onde vêm os dados de reciprocidade. A Cumbuca também deixa de adicionar a permission de identificações aos consentimentos em uma instância delegada, já que nunca precisa realizar essa leitura.

LGPD - nada armazenado na Cumbuca

Com a delegação habilitada, nenhum dado cadastral de cliente para reciprocidade é retido na Cumbuca: as escritas de registro são recusadas antes da validação, e toda leitura é respondida ao vivo pelo seu serviço. Os dados pessoais tratados para reciprocidade permanecem dentro da sua infraestrutura.

Cumbuca Gateway API - Reciprocidade.