DOU 01/03/2024 - 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 05152024030100105
105
Nº 42, sexta-feira, 1 de março de 2024
ISSN 1677-7042
Seção 1
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, correções a
serem incorporadas e 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 Responsável pela 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 Responsável pela 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 URIs (Uniform Resource Identifiers);
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 Responsável pela 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 Responsável pela 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.
5.1 Limites de tráfego
5.1.1 Limites por origem
Cada endpoint implementado no Open Finance pode ter uma restrição quanto
ao tráfego a partir de determinada origem. Em APIs do tipo "Dados Abertos" a origem é
o IP de onde partiu a requisição, em APIs autenticadas é a organizationId da instituição que
fez a requisição.
No caso de uma instituição implementar limites, eles devem respeitar os
valores mínimos de Transações por Minuto (TPM). conforme definido abaixo:
I - 2.000 TPM, por endpoint e por origem, em endpoints classificados como de
alta frequência;
II - 1.500 TPM, por endpoint e por origem, em endpoints classificados como de
média-alta frequência;
III - 1.000 TPM, por endpoint e por origem, em endpoints classificados como de
média frequência; e
IV - 500 TPM, por endpoint e por origem, em endpoints classificados como de
baixa frequência.
Aplicabilidade: Alguns endpoints não podem ter limites de tráfego definidos por
origem, como nas APIs do tipo "Serviços", nas APIs de "Segurança", e de "Recursos" e de
"Consentimento". A informação se o limite por origem é "aplicável" ou "não aplicável"
deve estar explícito por endpoint no Portal do Open Finance.
As
requisições que
excederem
os
limites implementados
deverão
ser
respondidas com o código de status HTTP 429 (Too Many Requests).
Por fim, as requisições que ultrapassarem os limites deverão ser desprezadas
no cálculo do tempo de resposta das implementações das APIs.
5.1.2 Limites globais
A infraestrutura das instituições provendo APIs no Open Finance deve ter a
capacidade de, no mínimo, atender a 300 requisições simultâneas por segundo (TPS).
Caso uma instituição atinja o limite de 300 TPS, no contexto do Open Finance,
a mesma deve ampliar sua capacidade de infraestrutura para possibilitar um acréscimo de
150 TPS ao limite anterior. Tal aumento deve ocorrer novamente a cada vez que o limite
vigente naquela instituição for atingido. Cada instituição deve criar monitoramento
preventivo, de acordo com critérios definidos; as evidências devem estar à disposição do
Banco Central do Brasil por um período de doze meses.
As requisições que excederem os limites de TPS deverão ser respondidas com
o código de status HTTP 529 (Site is overloaded).
O Portal do Open Finance deverá conter uma especificação detalhada de como
TPS e gatilhos para aumento ou diminuição da capacidade serão calculados.
Endpoints criados dentro do conceito de extensibilidade, sejam dentro de novas
APIs ou em APIs existentes, não podem ser considerados para controle do limite global de
transações simultâneas.
5.2 Limites operacionais
É facultado às instituições participantes que implementem um limite de acesso
mensal por endpoint e por cliente.
Em endpoints que acessem recursos ou produtos, os limites serão também
considerados por recurso ou produto.
A contabilização dos acessos deve ser feita por:
I - mês;
II - endpoint;
III
-
objeto
mais
granular
referenciado
na
chamada
(consentimento/recurso/produto);
IV - cliente (CPF ou CNPJ); e
V - instituição consumidora da informação.
Por exemplo: uma instituição receptora "A" pode acessar um endpoint "B",
acessando o recurso "C", de um cliente "D" da instituição transmissora "E", no mínimo "N"
vezes (ou chamadas) com sucesso por mês.
Aplicabilidade dos limites operacionais: todos os endpoints das APIs do tipo
Dados Cadastrais e Transacionais (conforme classificação por tipo), excetuando-se os
endpoints das APIs de Consentimento (Consents) e Recursos (Resources). As APIs dos tipos
Dados Abertos, de Serviços (como de Iniciação de Pagamento) e de Segurança não podem
ter restrições de limites operacionais.
A implementação dos limites operacionais é opcional pelas instituições
transmissoras, mas, uma vez que sejam implementados, devem garantir o consumo
mínimo estabelecido no Portal do Open Finance. É facultada à instituição a possibilidade de
ampliar estes limites,
mas vedada a implementação de
limites inferiores aos
estabelecidos.
O Portal do Open Finance deve listar os valores mínimos de limites operacionais
a serem considerados, por endpoint, que devem ser iguais ou maiores que os abaixo, de
acordo com a classificação de frequência de utilização:
I - 4 chamadas ao mês, para endpoint classificado como de baixa frequência;
II - 30 chamadas ao mês, para endpoint classificados como de média
frequência;
III - 120 chamadas ao mês, para endpoint classificados como de média-alta
frequência;
IV - 240 chamadas ao mês, para endpoint classificado como de alta frequência; e
V - 420 chamadas ao mês, para os seguintes endpoints da API de Contas:
"Saldos da conta" e "Limites da conta".
Só
deverão
ser
contabilizadas nos
limites
operacionais
as
requisições
respondidas com código de status HTTP 2XX (com sucesso), sendo que as requisições
adicionais a um endpoint para fins de paginação não devem ser contabilizadas.
As requisições que excederem os limites operacionais deverão ser respondidas
com o código de status HTTP 423.
Todas as requisições autenticadas em endpoints sujeitos ao limite operacional
devem possuir o atributo x-fapi-interaction-id preenchido no seu header pela instituição
receptora de dados, que deve ser copiado pela instituição transmissora de dados nos
Fechar