DOU 12/05/2025 - Diário Oficial da União - Brasil

TEXTO OFICIAL · ÍNTEGRA

Documento assinado digitalmente conforme MP nº 2.200-2 de 24/08/2001, que institui a Infraestrutura de Chaves Públicas Brasileira - ICP-Brasil. Este documento pode ser verificado no endereço eletrônico http://www.in.gov.br/autenticidade.html, pelo código 05152025051200218 218 Nº 87, segunda-feira, 12 de maio de 2025 ISSN 1677-7042 Seção 1 São tratados neste manual aspectos como: formato para a troca de dados, desenho da interface, protocolo para transmissão de dados, versionamento, modelo de APIs e endpoints. Desse modo, o manual estabelece as diretrizes gerais sem esgotar todos os aspectos necessários à implementação das APIs para o Open Finance. As demais definições a cargo das instituições participantes, por meio da Estrutura de Governança do Open Finance, estarão disponíveis no Portal do Open Finance no Brasil, no qual poderão ser encontrados guias, tutoriais e outras informações operacionais sobre as APIs. Ao longo deste manual, será constante o uso de siglas e terminologia específica para designar algumas expressões cotidianas dos profissionais da área de tecnologia. Alguns exemplos das mais frequentemente utilizadas, com as correspondentes definições, são as seguintes: I - API (Application Programming Interface): um conjunto de definições sobre como um sistema pode acessar dados ou funcionalidades providos por um outro sistema; II - REST (Representational State Transfer): estilo arquitetural de software; III - API RESTful: API que adere às restrições do estilo arquitetural REST; IV - OpenAPI: linguagem de especificação de APIs RESTful; V - endpoint: elemento de uma especificação OpenAPI sobre o qual podem ser executadas operações para acessar dados ou funcionalidades; VI - HTTP (Hypertext Transfer Protocol): protocolo para sistemas hipermídia, distribuídos e colaborativos; VII - operação: elemento de uma especificação OpenAPI que declara uma maneira válida de se acessar um endpoint, informando qual método HTTP (GET, POST etc.) utilizar, nomes e tipos de parâmetros; VIII - provedor da API: instituição que disponibiliza uma API para ser consumida por outras instituições. Nas APIs de "Serviços de Iniciação de Pagamentos", é a instituição detentora de contas; no caso de APIs de "Dados Cadastrais e Transacionais", é a instituição transmissora de dados; IX - consumidor da API: instituição que consome uma API provida por outras instituições. Nas APIs de "Serviços de Iniciação de Pagamentos", é a instituição iniciadora de pagamentos; no caso de APIs de "Dados Cadastrais e Transacionais", é a instituição receptora de dados; e X - gateway de API: é um serviço, dispositivo ou proxy que atua como intermediário, aceitando, transformando, encaminhando e gerenciando o tráfego de APIs para serviços de back-end. Ele permite a comunicação e a transferência de dados entre endpoints e pode ser útil quando há várias plataformas que precisam interagir umas com as outras sem conceder acesso direto às APIs umas das outras. Além disso, um gateway de API pode lidar com tarefas como autenticação, limitação de taxas, armazenamento em cache e transformação de solicitação/resposta, reduzindo a carga sobre o aplicativo e melhorando a segurança geral e o desempenho do sistema. 2. APIs do Open Finance As APIs a serem providas pelas instituições no âmbito do Open Finance devem ser categorizadas em um dos seguintes tipos: I - Dados Abertos; II - Dados Cadastrais e Transacionais; III - Serviços; e IV - Relatórios e Métricas. 3. Princípios Os princípios abaixo norteiam as especificações e implementações das APIs do Open Finance. 3.1 Experiência do usuário As especificações e implementações das APIs devem oferecer uma boa experiência para os usuários, sejam eles implementadores ou consumidores das APIs. 3.2 Independência de tecnologia As especificações das APIs devem ser independentes de tecnologia, podendo ser implementadas e consumidas em diferentes linguagens, tais como Java, JavaScript e Python; ou plataformas, tais como Windows, Linux, Android e iOS. 3.3 Segurança Procedimentos e controles (assinaturas digitais, criptografia, protocolos de autenticação e autorização, entre outros) devem ser adotados de forma a proteger os participantes do Open Finance, seus clientes, os consumidores das APIs e demais participantes do ecossistema, observada a compatibilidade com a política de segurança cibernética da instituição. 3.4 Extensibilidade No futuro, as APIs poderão ser evoluídas para atender a novos casos de uso e, portanto, devem ser especificadas e implementadas de forma a permitir e facilitar extensões como, por exemplo, novos endpoints, operações, parâmetros e propriedades. 3.5 Padrões abertos Padrões abertos devem ser adotados sempre que possível. 3.6 APIs RESTful As especificações das APIs devem atender às restrições do estilo arquitetural REST sempre que possível. 3.7 ISO 20022 As respostas das APIs devem ter como base os elementos e componentes de mensagem ISO 20022 (https://www.iso20022.org/). Os casos particulares em que a adoção do padrão ISO não seja possível ou recomendada poderão sofrer adequações, desde que especificamente apontados para avaliação pelo Banco Central do Brasil. 3.8 Declaração de obrigatoriedade Todos os elementos que compõem as especificações das APIs (endpoints, operações, parâmetros, propriedades de respostas etc.) devem ser explicitamente declarados como "Obrigatório", "Opcional" ou "Condicional", caso sejam obrigatórios apenas em certas condições. Funcionalidades que sejam de implementação opcional pelo transmissor devem ficar explícitas na sua documentação, tanto para informar adequadamente ao público transmissor, que poderá ou não implementar a funcionalidade, quanto ao público consumidor, que pode não encontrar a funcionalidade disponível em alguns transmissores. 4. Definições e recomendações As definições e recomendações abaixo devem ser observadas pelas especificações e implementações das APIs do Open Finance. 4.1 Especificações As APIs devem ser especificadas com a versão 3.0.0 ou superior da linguagem OpenAPI (https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md). As especificações das APIs devem ser analisadas com a versão 5.9.0 ou superior do software livre e de código aberto Spectral (https://github.com/stoplightio/spectral/tree/v5.9.0). A análise deve ser feita com o conjunto de regras (ruleset) padrão desta versão do Spectral. O resultado da análise não deve conter erros ou alertas. É recomendado que a versão 3.0.25 ou superior do software livre e de código aberto Swagger Codegen (https://github.com/swagger-api/swagger-codegen/tree/v3.0.25) seja utilizada para gerar o código de clientes e também o código inicial de implementações das APIs a partir de suas especificações. Recomenda-se que o código gerado seja analisado com o intuito de identificar possíveis recursos da linguagem OpenAPI que foram utilizados nas especificações, mas que não são adequadamente suportados pelo Swagger Codegen e, possivelmente, por outros softwares que trabalham com especificações OpenAPI. Caso isso ocorra, deve-se avaliar se não é possível alterar as especificações para não mais fazer uso desses recursos. Devem ser disponibilizadas implementações de exemplo das APIs. Os dados retornados por elas não precisam ser dados reais e nem volumosos, pois o objetivo da disponibilização é dar ao Banco Central do Brasil, aos implementadores e aos consumidores das APIs mais um recurso para dirimir eventuais dúvidas acerca de suas especificações e implementações. É recomendado que o código inicial de implementações das APIs mencionado anteriormente seja complementado de forma a constituir-se nas implementações de exemplo. As informações disponibilizadas nos dicionários de dados devem ser consistentes com as especificações OpenAPI associadas. Todos os endpoints das APIs implementados devem ser previamente registrados no diretório de participantes. Todos os endpoints registrados que retornem listas, caso os parâmetros sejam válidos, devem retornar a lista associada, mesmo que seja lista vazia. Não é considerado um retorno válido o erro 404, neste cenário, quando não houver a informação associada. 4.2 Versionamento As versões das especificações das APIs serão tipificadas como "major", "minor", "patch" e "release candidate" de acordo com os critérios a seguir: I - major: inclui novas características da implementação, mudanças e correções a serem incorporadas, que podem ser incompatíveis com versões anteriores, por exemplo, v1.0.0 e v2.0.0; II - minor: pequenas mudanças nos elementos já existentes, com manutenção da compatibilidade com as versões até a major imediatamente anterior, por exemplo, v1.1.0 e v1.2.0; III - patch: esclarecimentos às especificações "minor", não incluem alterações funcionais, por exemplo, v1.1.1, v1.1.2; e IV - release candidate: versões de pré-lançamento de qualquer versão futura do tipo "patch", "minor" ou "major", por exemplo, v1.0.0-rc e v1.0.0-rc2. A Estrutura de Governança do Open Finance, de que trata o art. 44, § 1º, da Resolução Conjunta nº 1, de 2020, pode lançar novas versões das APIs. O Banco Central do Brasil pode definir: I - o cronograma de implantação das novas versões das especificações das APIs e de certificação das instituições participantes; e II - a tipificação de determinadas alterações como "minor" ou "patch" independentemente dos critérios definidos nos incisos de I a IV desta subseção. Alterações feitas na especificação de uma API devem sempre ser documentadas com um novo versionamento desta especificação. Por fim, credenciais de acesso associadas às APIs devem ser agnósticas às suas versões. 4.3 Portal do Open Finance no Brasil O sítio eletrônico de que trata o art. 15 da Resolução BCB nº 32, de 2020, deverá conter definições e recomendações acessórias não presentes neste manual, bem como outros artefatos necessários à especificação, implementação e consumo das APIs do Open Finance. Todas as definições e recomendações acessórias e artefatos publicados no portal deverão estar em concordância com este e com os demais manuais do Open Finance. 4.4 Cronograma O Portal do Open Finance deverá listar as APIs em produção, suas versões atuais, datas em que entraram em produção, link para suas especificações e lista de mudanças desde a última publicação. Também deverá apresentar o cronograma de homologação das APIs, indicando versão, data de divulgação, data prevista de entrada em produção e outras informações relevantes. 4.5 Logs de mudanças Todas as versões já publicadas das APIs devem ser listadas no Portal do Open Finance, juntamente com os respectivos logs de mudanças e períodos em que estiveram em produção. 4.6 Definições acessórias A Estrutura de Governança do Open Finance deverá estabelecer e publicar no Portal do Open Finance um guia de estilo de especificações de APIs contendo definições e recomendações para os seguintes elementos: I - estrutura de Uniform Resource Identifiers (URIs); II - cabeçalhos HTTP; III - códigos de status HTTP; IV - convenções de corpo de requisições e respostas; V - convenções de nomenclatura; VI - tipos de dados comuns; VII - paginação; e VIII - estabilidade de identificadores. 4.7 Processo de gerência de mudanças A Estrutura de Governança do Open Finance deve estabelecer e publicar no Portal do Open Finance o processo que ela adotará para gerenciar mudanças nas especificações das APIs. 4.8 Tutoriais Todas as informações necessárias para o desenvolvimento, testes e entrada em produção de aplicações ou APIs no Open Finance devem estar disponíveis em tutoriais publicados na Área do Desenvolvedor no Portal do Open Finance. Cada tutorial deve conter todos os passos necessários para o completo desenvolvimento da atividade em questão, como desenvolvimento e uso de aplicações e APIs, autenticação e autorização, uso da Sandbox, aplicação de testes de conformidade e cadastramento no diretório. Quando pertinente, devem ser fornecidos exemplos de código fonte ou de capturas de telas, tornando o processo o mais claro possível para todos os participantes e interessados. 4.9 Extensibilidade As especificações das APIs do Open Finance podem não dar acesso a todos os dados e funcionalidades que um ou mais participantes desejam expor para os consumidores das APIs. Isso pode ser necessário para melhor suportar casos de uso ou possibilitar inovações em produtos e serviços financeiros. Para atender estas e outras necessidades, é facultado aos participantes implementarem versões estendidas das APIs inteiramente compatíveis com as especificações padrões das APIs que são: I - novos endpoints; II - novas operações em endpoints pré-existentes; III - novos parâmetros em operações pré-existentes, desde que opcionais; e IV - novas propriedades em respostas pré-existentes. A Estrutura de Governança do Open Finance deverá publicar no Portal do Open Finance as definições e recomendações acessórias relacionadas às extensões das APIs. Todas as extensões implementadas pelos participantes deverão estar listadas, com sua documentação referenciada, em seção específica no Portal do Open Finance e disponíveis para consumo, observadas as regras de ressarcimento de despesas previstas na regulamentação vigente. 5. Requisitos não funcionais Esta seção apresenta os requisitos não funcionais que as instituições participantes devem observar na implementação das APIs do Open Finance. Para auxiliar na definição de alguns requisitos não funcionais, é necessário que cada endpoint seja classificado no Portal do Open Finance de acordo com a sua frequência de atualização dos dados, conforme as opções abaixo: I - alta frequência; II - média-alta frequência; III - média frequência; e IV - baixa frequência Os Limites de tráfego por origem, limites operacionais e tempo de resposta (desempenho) serão definidos baseados nessa classificação. Os endpoints das APIs do tipo "Serviços", das APIs de "Segurança" (Token - consumo OAuth 2.0 (FAPI), Token - DCR/DCM) e das APIs de "Recursos" e de "Consentimento" devem ser considerados como de alta frequência. Destaca-se que, especialmente em requisitos não funcionais, o termo "endpoint" deve considerar as operações específicas associadas a cada caminho. Por exemplo, as chamadas GET /consents/{consentId} e DELETE /consents/{consentId} representam operações distintas e, portanto, devem ser monitoradas de forma independente.