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

                            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.

                            

Fechar