1. Introdução

A API de Recursos constitui o componente de inventário do ecossistema Open Finance Brasil. Sua função primordial é atuar como uma camada de abstração e descoberta, permitindo que a Instituição Receptora identifique de forma granular quais ativos (contas, cartões, operações de crédito) foram efetivamente autorizados pelo titular para compartilhamento. Esta API é o ponto de transição crítico entre a fase de Consentimento e o consumo efetivo de dados transacionais.

1.1 Problema

Após a autorização de um consentimento, a instituição Receptora precisa saber quais produtos (recursos) do cliente estão acessíveis na Transmissora e em que estado de disponibilidade cada um se encontra. Sem uma camada padronizada de descoberta e de status, a Receptora teria de consultar todas as famílias de APIs (contas, cartões, crédito, investimentos) sem saber antecipadamente o que existe e em que condição está.

1.2 Oportunidade

A API de Recursos é a porta de entrada do consumo de dados após o consentimento: ela entrega o catálogo de resourceId (com seu status) que a Receptora deve usar nas APIs de produto. Isso reduz chamadas inúteis, padroniza a descoberta, permite identificar recursos que não aparecem nas APIs de listagem (ex.: UNAVAILABLE) e melhora a experiência de integração.

2. Escopo

O escopo abrange a listagem de recursos vinculados a um consentimento ativo, incluindo:

• Identificação de contas de depósito à vista, poupança e pagamento.

• Mapeamento de contas de cartão de crédito.

• Exposição de operações de crédito (empréstimos, financiamentos, adiantamentos e direitos creditórios).

• Gestão de status de disponibilidade do recurso para consumo.

3. Contexto Regulatório

Esta especificação está em estrita conformidade com as diretrizes do Open Finance Brasil, observando os padrões de segurança FAPI-BR e CIBA-BR e as normas de compartilhamento de dados. O tratamento de dados segue os preceitos da LGPD (Lei Geral de Proteção de Dados), garantindo que apenas recursos com finalidade específica e autorização explícita sejam expostos.

4. Regras de Negócio

5. Registro de Decisões Arquiteturais (ADRs)

ADR-001 — API de Recursos como camada de descoberta e status

• Contexto: a Receptora precisa enumerar os produtos do cliente e seu estado de disponibilidade sem conhecer previamente a oferta da Transmissora.

• Opções consideradas: (a) descoberta por chamadas a todas as APIs de produto; (b) API dedicada de recursos com status.

• Decisão: API dedicada (GET /resources), alinhada à especificação OFB, retornando resourceId, type e status.

• Consequências: menor volume de chamadas, padronização de identificadores e ponto único de auditoria de descoberta.

ADR-002 — resourceId estável e alinhado às APIs de produto

• Contexto: o identificador do recurso é usado em todas as APIs de produto.

• Decisão: resourceId opaco e estável, correspondente ao identificador do recurso na API específica (accountId, creditCardAccountId, etc.).

• Consequências: evita mapeamento extra na Receptora e garante rastreabilidade entre a API de Recursos e as APIs de produto.

ADR-003 — Status do recurso como composição (consentimento + disponibilidade)

• Contexto: o status deve refletir tanto o consentimento vinculado quanto a disponibilidade real do recurso na transmissora.

• Decisão: o status é calculado na transmissora considerando ambos os fatores (ex.: recurso bloqueado por fraude → TEMPORARILY_UNAVAILABLE mesmo com consentimento AUTHORISED).

• Consequências: maior precisão de informação para a Receptora, com overhead de consulta de disponibilidade (mitigado por cache de curta duração).

ADR-004 — Status do recurso rejeitado pelo aprovador de múltiplas alçadas (consentimento + disponibilidade)

• Contexto: o status deve refletir tanto o consentimento vinculado quanto a disponibilidade real do recurso na transmissora.

• Decisão: o status é calculado na transmissora considerando ambos os fatores (ex.: recurso específico rejeitado pelo aprovador de dados → UNAVAILABLE mesmo com consentimento AUTHORISED).

• Consequências: o status UNAVAILABLE pode representar que o recurso está indisponível pelo encerramento daquele recurso, ex. conta encerrada ou porque o aprovador de dados não aprovou o consumo daquele recurso pela receptora.

6. Considerações para Múltiplas Alçadas em PJ

Em cenários de contas de Pessoa Jurídica que exigem múltiplas aprovações, a API de Recursos deve observar o estado de Orquestração de Aprovações. Os recursos só deverão ser listados como AVAILABLE após a última assinatura necessária no fluxo de alçada. Recursos que foram rejeitados pelo aprovador deverão ser listados como UNAVAILABLE.

Ponto Importante:

• Está previsto na jornada que a identificação dos aprovadores de recursos devem ficar disponíveis para todos os operadores com acesso a área de gestão da Instituição Transmissora;

• Compete a Instituição Transmissora junto a sua cliente PJ a definição de como será a jornada de aprovação de recursos caso exista, no que tange a número de aprovadores por recursos, níveis de aprovação, etc.

• Não se aplica fluxo de múltiplas alçadas para clientes PF ou clientes PJ sócio único ou MEI.

7. Requisitos Técnicos

mTLS (Mutual TLS): É obrigatória a autenticação mTLS em todas as conexões, utilizando certificados emitidos pela ICP-Brasil, conforme o padrão do Diretório Central do Open Finance.

Idempotência: O endpoint deve ser idempotente, garantindo que múltiplas chamadas com o mesmo token de acesso retornem o mesmo conjunto de dados, salvo alteração real no status do recurso na Transmissora.

8. Fluxos e Comportamentos

O fluxo típico inicia-se após a Instituição Receptora obter o access_token via Authorization Code Flow. A Receptora invoca o endpoint de Recursos para mapear os resourceIds, para após consumir os dados dos recursos uma vez de posse dos IDs dos mesmos.

9. Glossário

• API: Interface de Programação de Aplicações.

• OFB: Open Finance Brasil.

• PRD: Documento de Requisitos de Produto.

• CIBA: Client-Initiated Backchannel Authentication – protocolo OIDF que permite autenticação desacoplada sem redirecionamento.

• Receptora: Instituição que solicita o consentimento e recebe os dados do cliente.

• Transmissora: Instituição que detém os dados do cliente e realiza a autenticação/autorização.

• mTLS: Mutual TLS – autenticação de duas vias entre cliente e servidor usando certificados.