Banco Central
Instrução Normativa
•
19/09/2022
Instrução Normativa BCB N° 306
Sumário Regulatório
INSTRUÇÃO NORMATIVA BCB Nº 306, DE 19 DE SETEMBRO DE 2022 Divulga a versão 4.0 do Manual de APIs do Open Finance. Os Chefes do Departamento de Regulação do Sistema Financeiro (Denor) e do Departamento de Tecnologia da Informação (Deinf), no uso das a...
Conteúdo do Documento
INSTRUÇÃO NORMATIVA BCB Nº 306, DE 19 DE SETEMBRO DE 2022 Divulga a versão 4.0 do Manual de APIs do Open Finance. Os Chefes do Departamento de Regulação do Sistema Financeiro (Denor) e do Departamento de Tecnologia da Informação (Deinf), no uso das atribuições que lhes conferem os arts. 23, inciso I, alínea "a", e 62, inciso IV, do Regimento Interno do Banco Central do Brasil, anexo à Portaria...
INSTRUÇÃO NORMATIVA BCB Nº 306, DE 19
DE SETEMBRO DE 2022
Divulga a versão 4.0 do Manual de APIs
do Open Finance.
Os
Chefes do Departamento de Regulação do Sistema Financeiro (Denor) e do
Departamento de Tecnologia da Informação (Deinf), no uso das atribuições que
lhes conferem os arts. 23, inciso I, alínea "a", e 62, inciso IV, do
Regimento Interno do Banco Central do Brasil, anexo à Portaria nº 84.287, de 27
de fevereiro de 2015, com base no art. 3º, inciso II, da Resolução BCB nº 32,
de 29 de outubro de 2020,
R
E S O L V E M :
Art.
1º Esta Instrução Normativa divulga a versão 4.0 do Manual de APIs do Open Finance,
de observância obrigatória por parte das instituições
participantes, conforme Anexo.
Parágrafo
único. O manual de que
trata o caput, em sua versão mais recente, estará acessível na página do
Open Finance no sítio eletrônico do Banco Central do Brasil na internet
e no Portal do Open Finance no Brasil, mantido pela Estrutura
Responsável pela Governança do Open Finance de que trata o art. 44, §
1º, da Resolução Conjunta nº 1, de 4 de maio de 2020.
Art.
2º Fica revogada a Instrução
Normativa nº 130, de 22 de julho de 2021.
Art. 3º Esta Instrução Normativa
entra em vigor em 1º de outubro de 2022.
João
André Calvino Marques Pereira Haroldo Jayme Martins Froes Cruz
Chefe
do Departamento de Regulação Chefe do Departamento de
do
Sistema Financeiro Tecnologia da
Informação
ANEXO À INSTRUÇÃO NORMATIVA BCB Nº 306,
DE 19 DE SETEMBRO DE 2022
Manual de APIs do Open
Finance Versão 4.0
Histórico de revisão
Data
Versão
Descrição das alterações
19/9/2022
4.0
Aprimoramentos na redação do texto, sem alteração de
mérito.
Substituição das expressões “Open Banking” por “Open
Finance”, conforme alteração promovida pela Resolução Conjunta nº 4, de
24 de março de 2022, na Resolução Conjunta nº 1, de 2020.
Atualização
da tabela de APIs do Open Finance, considerando fases 3 e 4 do Open
Finance.
Aprimoramento
do texto relativo à compatibilidade com o padrão ISO 20022.
Atualização
da seção “Versões”.
Ajustes
relativos a limites de tráfego, limites operacionais e desempenho das APIs.
Inclusão da
seção “Disposições transitórias”.
Termos
de Uso
Este manual
detalha os requisitos técnicos para a implementação dos elementos necessários à
operacionalização do Open Finance, complementando a regulamentação
vigente sobre o tema.
O manual será
revisto e atualizado periodicamente a fim de preservar a compatibilidade com a
regulamentação, bem como para incorporar os aprimoramentos decorrentes da
evolução do Open Finance e da tecnologia.
Informações
mais detalhadas e exemplos da aplicação deste manual poderão ser encontrados
nos guias e tutoriais disponíveis no Portal do Open Finance no Brasil,
na Área do Desenvolvedor.
Sugestões,
críticas ou pedidos de esclarecimento de dúvidas relativas ao conteúdo deste
documento podem ser enviados ao Banco Central do Brasil por meio dos canais
institucionais dessa autarquia.
Referências
As
especificações deste manual baseiam-se, referenciam e complementam, quando aplicável,
os seguintes documentos:
Referência
Origem
Resolução
Conjunta nº 1, de 2020
https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=Resolu%C3%A7%C3%A3o%20Conjunta&numero=1
Resolução
BCB nº 32, de 2020
https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=Resolu%C3%A7%C3%A3o%20BCB&numero=32
Hypertext
Transfer Protocol – HTTP/1.1
https://tools.ietf.org/html/rfc2616
ISO
20022
https://www.iso20022.org/
OpenAPI
Specification
https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md
Representational
State Transfer
https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
1. Introdução
O Open
Finance está intrinsecamente ligado ao uso de Application Programming
Interface (API), interfaces por meio das quais será possível interligar os
diferentes sistemas das instituições. Ao serem disponibilizadas pelos
participantes, as APIs precisam satisfazer condições tais como
padronização, robustez e segurança, a fim de que o compartilhamento de dados e
serviços seja realizado a contento.
Nesse sentido, este manual define os
principais aspectos relativos às especificações e implementações das APIs que
integram o Open Finance no País, observando as disposições da Resolução
Conjunta nº 1, de 4 de maio de 2020, e da Resolução BCB nº 32, de 29 de outubro
de 2020.
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 responsável pela governança, nos termos da Circular nº 4.032,
de 23 de junho de 2020, estão disponíveis no Portal do Open Finance no
Brasil, no qual podem 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; e
VII -
Operação: elemento de uma especificação OpenAPI que declara uma maneira válida
de se acessar um endpoint, informando, por exemplo, qual método HTTP
(GET, POST, etc.) utilizar, nomes e tipos de parâmetros, etc.
2.
APIs do Open
Finance
A tabela
abaixo exibe as APIs que integram o Open Finance.
Tipo
Nome
Descrição
Dados
Abertos
Produtos e
Serviços
Deve dar
acesso a dados abertos relacionados a produtos e serviços oferecidos pelos
participantes do Open Finance.
Canais de
Atendimento
Deve dar
acesso a dados abertos relacionados aos canais de atendimento ao público
oferecidos pelos participantes do Open Finance.
Títulos de
Capitalização
Deve dar
acesso a dados abertos relacionados aos títulos de capitalização oferecidos
pelos participantes do Open Finance.
Investimentos
Deve dar
acesso a dados abertos relacionados aos fundos de investimento oferecidos
pelos participantes do Open Finance.
Câmbio
Deve dar
acesso a dados abertos relacionados a câmbio oferecidos pelos participantes
do Open Finance.
Credenciamento
Deve dar
acesso a dados abertos relacionados a credenciamento oferecidos pelos
participantes do Open Finance.
Previdência
Deve dar
acesso a dados abertos relacionados a previdência oferecidos pelos
participantes do Open Finance.
Seguros
Deve dar
acesso a dados abertos relacionados a seguros oferecidos pelos participantes
do Open Finance.
Dados
Cadastrais e Transacionais
Consentimento
Deve
permitir a criação, consulta e revogação de consentimentos de acesso a dados.
Resources
Deve dar
acesso à lista de recursos consentidos pelo cliente.
Dados
Cadastrais
Deve dar
acesso aos dados cadastrais de clientes e seus representantes.
Contas
Deve dar
acesso aos dados transacionais de clientes relacionados a contas de depósito
à vista, contas de poupança e contas pré-paga.
Cartão de
Crédito
Deve dar
acesso aos dados transacionais de clientes relacionados a contas de pagamento
pós-paga.
Operações
de Crédito - Adiantamento a Depositantes
Deve dar
acesso a dados transacionais de clientes relacionados a operações de crédito na
modalidade adiantamento a depositantes.
Operações
de Crédito - Empréstimos
Deve dar
acesso a dados transacionais de clientes relacionados a operações de crédito na
modalidade empréstimo.
Operações
de Crédito - Direitos creditórios descontados
Deve dar
acesso a dados transacionais de clientes relacionados a operações de crédito na
modalidade direitos creditórios descontados.
Operações
de Crédito - Financiamentos
Deve dar
acesso a dados transacionais de clientes relacionados a operações de crédito na
modalidade financiamento.
Serviços
Iniciação
de Pagamentos
Deve
permitir a criação do consentimento do pagamento, criar a iniciação de
pagamento e acompanhar a situação das solicitações realizadas.
Relatórios
e Métricas
Situação do
Ambiente
Deve dar
acesso a dados sobre a disponibilidade atual das implementações das APIs, bem
como a dados sobre indisponibilidades programadas.
Métricas
Deve dar
acesso a dados de performance de todas APIs disponibilizadas.
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 e/ou plataformas tais como
Java, JavaScript, Python e 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 aprimoradas 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 isto
ocorra, deve-se avaliar se não é possível alterar as especificações para não
mais fazer uso destes recursos.
Implementações
de exemplo das APIs devem ser disponibilizadas. 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 Versões
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, poderá lançar novas versões das APIs. O Banco
Central do Brasil poderá definir o cronograma de implantação das novas versões major
e de certificação das instituições participantes.
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 site 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
frequência; e
III - Baixa
frequência
Limites de tráfego
por origem, limites operacionais e tempo de resposta (desempenho) serão definidos
baseados nessa classificação.
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 IF/organizationId 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.000
TPM, por endpoint e por origem, em endpoints classificados como
de média frequência; e
III - 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, Segurança (Token – consumo OAuth 2.0 (FAPI),
Token – DCR/DCM), Recursos e de Consentimento. A informação definindo se o
limite por origem é ‘aplicável’ ou ‘não aplicável’ deve estar explícita por endpoint
no site 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 o limite
de 300 TPS seja atingido, no contexto do Open Finance, a instituição 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 na instituição for atingido. Cada instituição deve criar
monitoramento preventivo, de acordo com critérios definidos; as evidências
devem estar a 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 implementarem 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 realizada por:
I
- mês;
II
- endpoint;
III
- objeto mais granular referenciado na chamada (consentimento/recurso/produto);
IV
- cliente (CPF ou CNPJ); e
V
- IF 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 endpoints das APIs do tipo Dados Cadastrais e Transacionais
(conforme classificação de Tipo),
destes excetuam-se aqueles endpoints das APIs de Consentimento
(Consents) e Recursos (Resources). As APIs dos tipos Dados Abertos e de Serviços
(como de Iniciação de Pagamento) 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 site do Open Finance. É facultada à instituição a
possibilidade de ampliar esses limites, mas vedada a implementação de limites
inferiores aos estabelecidos.
O site
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 - 240 chamadas
ao mês, para endpoint classificado como de alta frequência; e
IV - 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 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
requisições autenticadas em endpoints sujeitos ao limite operacional
devem possuir o atributo x-fapi-interaction-id preenchido no seu header
pela receptora, que deve ser copiado pela transmissora nos headers da
resposta. Essa definição objetiva permitir um adequado rastreamento de
divergências que podem ocorrer entre transmissoras e receptoras associadas ao
limite operacional.
5.3
Desempenho
Deverá ser
medido o tempo de resposta de cada requisição, ou seja, o tempo transcorrido
entre o recebimento de uma requisição que não ultrapassa os limites de tráfego
e o momento em que a requisição é completamente respondida. Adicionalmente,
esta medição deverá ser feita de maneira que os tempos medidos sejam os mais próximos
possíveis dos tempos de resposta experimentados por quem fez a requisição.
Neste contexto, os endpoints das APIs deverão manter o percentil 95 do
tempo de resposta em no máximo:
I - 1.500ms, em
endpoints classificados como de alta frequência;
II - 2.000ms,
em endpoints classificados como de média frequência; e
III - 4.000ms,
em endpoints classificados como de baixa frequência.
Por exemplo,
em um dia que um endpoint de alta frequência receba 10.000 requisições,
o tempo de resposta de pelo menos 9.500 requisições deve ser inferior a 1.500ms.
5.4
Disponibilidade
As APIs classificadas
como ‘Dados Abertos’, ‘Dados
Cadastrais e Transacionais’
e ‘Relatórios e métricas’, listadas na Seção 2 deste manual, deverão satisfazer
requisitos mínimos de disponibilidade abaixo. Cada um de seus endpoints
deverá estar disponível:
I - 95% do tempo a cada 24 horas; e
II - 99,5% do tempo a cada 3 meses.
As APIs classificadas
como ‘Serviços’ deverão possuir a mesma disponibilidade do arranjo de pagamento
ou do serviço aos quais estão associadas.
O Portal do Open
Finance deverá conter uma especificação detalhada de como a disponibilidade
de cada endpoint será calculada.
5.5
Timeout
Padronização
do timeout de tempo de resposta do servidor (server) e do tempo
de resposta do consumidor (client) em quinze segundos.
As
requisições que excederem o limite de timeout do servidor deverão ser
respondidas com o código de status HTTP 504 (Gateway Timeout).
6.
Disposições Transitórias
O processo de
publicação em produção da versão 2.0.1 das APIs de ‘Dados Cadastrais e Transacionais’, cuja especificação foi lançada no
portal do Open Finance em 20/06/2022, deverá considerar os seguintes
pontos de controle:
Data
Descrição
24/08/2022
Data limite
para início de execução dos testes no motor de conformidade
10/10/2022
Data limite
para pedido de certificação funcional das APIs
31/10/2022
Data limite
para certificação e publicação das novas APIs no diretório
23/02/2023
Último dia
do período de depreciação da versão 1. As instituições receptoras têm até essa
data para migrar suas soluções para a nova versão das APIs. As instituições transmissoras
devem descontinuar a versão anterior somente depois desta data.
As
modificações dos requisitos de qualidade, atualizados neste manual, devem ser
aplicadas a partir da data de publicação das novas APIs pelas instituições.
Brasília, 19 de setembro de 2022.
NOTA
1135/2022-BCB/DENOR, DE 13 de setembro de 2022.
Fundamenta
proposta de edição de instrução normativa que estabelece a versão 4.0 do Manual
de APIs do Open Finance.
Senhores Chefes do Denor e do
Deinf,
A presente Nota fundamenta
proposta de edição de instrução normativa pelo Departamento de Regulação do
Sistema Financeiro (Denor) e pelo Departamento de Tecnologia da Informação
(Deinf), no uso da atribuição que lhes confere o art. 23, inciso I, alínea
"a", do Regimento Interno do Banco Central do Brasil, anexo à
Portaria nº 84.287, de 27 de fevereiro de 2015, e observado o inciso IX do art.
51 da Resolução Conjunta nº 1, de 4 de maio de 2020.
2. A respeito, a proposta trata
de edição de instrução normativa que estabelece a versão 4.0 do Manual de APIs
do Open Finance, revogando a Instrução Normativa BCB nº 130, de 22 de
julho de 2021, que divulga a versão 3.0 do Manual de APIs do Open Banking.
3. As alterações referem-se à
atualização da expressão Open Banking por Open Finance, conforme mudanças
realizadas pela Resolução Conjunta nº 4, de 24 de março de 2022, a
esclarecimentos sobre o processo de lançamento de novas APIs e suas versões e à
adequação ao padrão ISO 20022; bem como à adequação técnica em pontos
concernentes a limites de tráfego e operacionais, à disponibilidade e
desempenho das APIs e à padronização de tempo de resposta (time-out). A
proposta de instrução normativa dispõe, ainda, sobre pontos de controle para
publicação da versão 2.0.1 das APIs de ‘Dados Cadastrais e Transacionais’, cuja
especificação foi lançada no portal do Open Finance em 20 de junho de
2022.
4. Por fim, em atendimento ao
previsto no art. 5º da Lei nº 13.874, de 20 de setembro de 2019, o Decreto nº
10.411, de 30 de junho de 2020, determina que as propostas de atos normativos
de interesse geral de agentes econômicos formuladas por órgãos e entidades da
administração pública federal direta, autárquica e fundacional, bem como por
colegiados por meio do órgão ou da entidade encarregada de lhe prestar apoio
administrativo, sejam precedidas de Análise de Impacto Regultório (AIR).
5. No entanto, vale destacar que
as alterações e os ajustes propostos não causam impactos significativos para o
conjunto de instituições participantes do Open Finance, por tratar-se de
esclarecimentos e adaptações em orientações já constantes em atos normativos
vigentes, como no caso do tópico sobre versões, e a adequações relacionadas a
tráfego, limites e métricas de chamadas com o objetivo de aperfeiçoar o fluxo
de informações entre as instituições participantes do Open Finance, de
forma a possibilitar o seu monitoramento e esclarecer eventuais disputas. Nesse
sentido, de acordo com o art. 4º, inciso III, do referido Decreto, o ato normativo ora proposto fica dispensado de elaboração de
AIR por ser considerado de baixo impacto.
À consideração de V.Sas.
Mardilson
Fernandes Queiroz Aristides Andrade Cavalcante Neto
Consultor
do Departamento Chefe Adjunto do Departamento de
de Regulação
do Sistema Financeiro Tecnologia da Informação
De acordo.
João
André Calvino Marques Pereira Haroldo Jayme Martins Froes Cruz
Chefe
do Departamento de Regulação Chefe do Departamento de
do
Sistema Financeiro Tecnologia da
Informação
DE SETEMBRO DE 2022
Divulga a versão 4.0 do Manual de APIs
do Open Finance.
Os
Chefes do Departamento de Regulação do Sistema Financeiro (Denor) e do
Departamento de Tecnologia da Informação (Deinf), no uso das atribuições que
lhes conferem os arts. 23, inciso I, alínea "a", e 62, inciso IV, do
Regimento Interno do Banco Central do Brasil, anexo à Portaria nº 84.287, de 27
de fevereiro de 2015, com base no art. 3º, inciso II, da Resolução BCB nº 32,
de 29 de outubro de 2020,
R
E S O L V E M :
Art.
1º Esta Instrução Normativa divulga a versão 4.0 do Manual de APIs do Open Finance,
de observância obrigatória por parte das instituições
participantes, conforme Anexo.
Parágrafo
único. O manual de que
trata o caput, em sua versão mais recente, estará acessível na página do
Open Finance no sítio eletrônico do Banco Central do Brasil na internet
e no Portal do Open Finance no Brasil, mantido pela Estrutura
Responsável pela Governança do Open Finance de que trata o art. 44, §
1º, da Resolução Conjunta nº 1, de 4 de maio de 2020.
Art.
2º Fica revogada a Instrução
Normativa nº 130, de 22 de julho de 2021.
Art. 3º Esta Instrução Normativa
entra em vigor em 1º de outubro de 2022.
João
André Calvino Marques Pereira Haroldo Jayme Martins Froes Cruz
Chefe
do Departamento de Regulação Chefe do Departamento de
do
Sistema Financeiro Tecnologia da
Informação
ANEXO À INSTRUÇÃO NORMATIVA BCB Nº 306,
DE 19 DE SETEMBRO DE 2022
Manual de APIs do Open
Finance Versão 4.0
Histórico de revisão
Data
Versão
Descrição das alterações
19/9/2022
4.0
Aprimoramentos na redação do texto, sem alteração de
mérito.
Substituição das expressões “Open Banking” por “Open
Finance”, conforme alteração promovida pela Resolução Conjunta nº 4, de
24 de março de 2022, na Resolução Conjunta nº 1, de 2020.
Atualização
da tabela de APIs do Open Finance, considerando fases 3 e 4 do Open
Finance.
Aprimoramento
do texto relativo à compatibilidade com o padrão ISO 20022.
Atualização
da seção “Versões”.
Ajustes
relativos a limites de tráfego, limites operacionais e desempenho das APIs.
Inclusão da
seção “Disposições transitórias”.
Termos
de Uso
Este manual
detalha os requisitos técnicos para a implementação dos elementos necessários à
operacionalização do Open Finance, complementando a regulamentação
vigente sobre o tema.
O manual será
revisto e atualizado periodicamente a fim de preservar a compatibilidade com a
regulamentação, bem como para incorporar os aprimoramentos decorrentes da
evolução do Open Finance e da tecnologia.
Informações
mais detalhadas e exemplos da aplicação deste manual poderão ser encontrados
nos guias e tutoriais disponíveis no Portal do Open Finance no Brasil,
na Área do Desenvolvedor.
Sugestões,
críticas ou pedidos de esclarecimento de dúvidas relativas ao conteúdo deste
documento podem ser enviados ao Banco Central do Brasil por meio dos canais
institucionais dessa autarquia.
Referências
As
especificações deste manual baseiam-se, referenciam e complementam, quando aplicável,
os seguintes documentos:
Referência
Origem
Resolução
Conjunta nº 1, de 2020
https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=Resolu%C3%A7%C3%A3o%20Conjunta&numero=1
Resolução
BCB nº 32, de 2020
https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=Resolu%C3%A7%C3%A3o%20BCB&numero=32
Hypertext
Transfer Protocol – HTTP/1.1
https://tools.ietf.org/html/rfc2616
ISO
20022
https://www.iso20022.org/
OpenAPI
Specification
https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md
Representational
State Transfer
https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
1. Introdução
O Open
Finance está intrinsecamente ligado ao uso de Application Programming
Interface (API), interfaces por meio das quais será possível interligar os
diferentes sistemas das instituições. Ao serem disponibilizadas pelos
participantes, as APIs precisam satisfazer condições tais como
padronização, robustez e segurança, a fim de que o compartilhamento de dados e
serviços seja realizado a contento.
Nesse sentido, este manual define os
principais aspectos relativos às especificações e implementações das APIs que
integram o Open Finance no País, observando as disposições da Resolução
Conjunta nº 1, de 4 de maio de 2020, e da Resolução BCB nº 32, de 29 de outubro
de 2020.
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 responsável pela governança, nos termos da Circular nº 4.032,
de 23 de junho de 2020, estão disponíveis no Portal do Open Finance no
Brasil, no qual podem 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; e
VII -
Operação: elemento de uma especificação OpenAPI que declara uma maneira válida
de se acessar um endpoint, informando, por exemplo, qual método HTTP
(GET, POST, etc.) utilizar, nomes e tipos de parâmetros, etc.
2.
APIs do Open
Finance
A tabela
abaixo exibe as APIs que integram o Open Finance.
Tipo
Nome
Descrição
Dados
Abertos
Produtos e
Serviços
Deve dar
acesso a dados abertos relacionados a produtos e serviços oferecidos pelos
participantes do Open Finance.
Canais de
Atendimento
Deve dar
acesso a dados abertos relacionados aos canais de atendimento ao público
oferecidos pelos participantes do Open Finance.
Títulos de
Capitalização
Deve dar
acesso a dados abertos relacionados aos títulos de capitalização oferecidos
pelos participantes do Open Finance.
Investimentos
Deve dar
acesso a dados abertos relacionados aos fundos de investimento oferecidos
pelos participantes do Open Finance.
Câmbio
Deve dar
acesso a dados abertos relacionados a câmbio oferecidos pelos participantes
do Open Finance.
Credenciamento
Deve dar
acesso a dados abertos relacionados a credenciamento oferecidos pelos
participantes do Open Finance.
Previdência
Deve dar
acesso a dados abertos relacionados a previdência oferecidos pelos
participantes do Open Finance.
Seguros
Deve dar
acesso a dados abertos relacionados a seguros oferecidos pelos participantes
do Open Finance.
Dados
Cadastrais e Transacionais
Consentimento
Deve
permitir a criação, consulta e revogação de consentimentos de acesso a dados.
Resources
Deve dar
acesso à lista de recursos consentidos pelo cliente.
Dados
Cadastrais
Deve dar
acesso aos dados cadastrais de clientes e seus representantes.
Contas
Deve dar
acesso aos dados transacionais de clientes relacionados a contas de depósito
à vista, contas de poupança e contas pré-paga.
Cartão de
Crédito
Deve dar
acesso aos dados transacionais de clientes relacionados a contas de pagamento
pós-paga.
Operações
de Crédito - Adiantamento a Depositantes
Deve dar
acesso a dados transacionais de clientes relacionados a operações de crédito na
modalidade adiantamento a depositantes.
Operações
de Crédito - Empréstimos
Deve dar
acesso a dados transacionais de clientes relacionados a operações de crédito na
modalidade empréstimo.
Operações
de Crédito - Direitos creditórios descontados
Deve dar
acesso a dados transacionais de clientes relacionados a operações de crédito na
modalidade direitos creditórios descontados.
Operações
de Crédito - Financiamentos
Deve dar
acesso a dados transacionais de clientes relacionados a operações de crédito na
modalidade financiamento.
Serviços
Iniciação
de Pagamentos
Deve
permitir a criação do consentimento do pagamento, criar a iniciação de
pagamento e acompanhar a situação das solicitações realizadas.
Relatórios
e Métricas
Situação do
Ambiente
Deve dar
acesso a dados sobre a disponibilidade atual das implementações das APIs, bem
como a dados sobre indisponibilidades programadas.
Métricas
Deve dar
acesso a dados de performance de todas APIs disponibilizadas.
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 e/ou plataformas tais como
Java, JavaScript, Python e 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 aprimoradas 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 isto
ocorra, deve-se avaliar se não é possível alterar as especificações para não
mais fazer uso destes recursos.
Implementações
de exemplo das APIs devem ser disponibilizadas. 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 Versões
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, poderá lançar novas versões das APIs. O Banco
Central do Brasil poderá definir o cronograma de implantação das novas versões major
e de certificação das instituições participantes.
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 site 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
frequência; e
III - Baixa
frequência
Limites de tráfego
por origem, limites operacionais e tempo de resposta (desempenho) serão definidos
baseados nessa classificação.
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 IF/organizationId 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.000
TPM, por endpoint e por origem, em endpoints classificados como
de média frequência; e
III - 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, Segurança (Token – consumo OAuth 2.0 (FAPI),
Token – DCR/DCM), Recursos e de Consentimento. A informação definindo se o
limite por origem é ‘aplicável’ ou ‘não aplicável’ deve estar explícita por endpoint
no site 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 o limite
de 300 TPS seja atingido, no contexto do Open Finance, a instituição 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 na instituição for atingido. Cada instituição deve criar
monitoramento preventivo, de acordo com critérios definidos; as evidências
devem estar a 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 implementarem 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 realizada por:
I
- mês;
II
- endpoint;
III
- objeto mais granular referenciado na chamada (consentimento/recurso/produto);
IV
- cliente (CPF ou CNPJ); e
V
- IF 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 endpoints das APIs do tipo Dados Cadastrais e Transacionais
(conforme classificação de Tipo),
destes excetuam-se aqueles endpoints das APIs de Consentimento
(Consents) e Recursos (Resources). As APIs dos tipos Dados Abertos e de Serviços
(como de Iniciação de Pagamento) 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 site do Open Finance. É facultada à instituição a
possibilidade de ampliar esses limites, mas vedada a implementação de limites
inferiores aos estabelecidos.
O site
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 - 240 chamadas
ao mês, para endpoint classificado como de alta frequência; e
IV - 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 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
requisições autenticadas em endpoints sujeitos ao limite operacional
devem possuir o atributo x-fapi-interaction-id preenchido no seu header
pela receptora, que deve ser copiado pela transmissora nos headers da
resposta. Essa definição objetiva permitir um adequado rastreamento de
divergências que podem ocorrer entre transmissoras e receptoras associadas ao
limite operacional.
5.3
Desempenho
Deverá ser
medido o tempo de resposta de cada requisição, ou seja, o tempo transcorrido
entre o recebimento de uma requisição que não ultrapassa os limites de tráfego
e o momento em que a requisição é completamente respondida. Adicionalmente,
esta medição deverá ser feita de maneira que os tempos medidos sejam os mais próximos
possíveis dos tempos de resposta experimentados por quem fez a requisição.
Neste contexto, os endpoints das APIs deverão manter o percentil 95 do
tempo de resposta em no máximo:
I - 1.500ms, em
endpoints classificados como de alta frequência;
II - 2.000ms,
em endpoints classificados como de média frequência; e
III - 4.000ms,
em endpoints classificados como de baixa frequência.
Por exemplo,
em um dia que um endpoint de alta frequência receba 10.000 requisições,
o tempo de resposta de pelo menos 9.500 requisições deve ser inferior a 1.500ms.
5.4
Disponibilidade
As APIs classificadas
como ‘Dados Abertos’, ‘Dados
Cadastrais e Transacionais’
e ‘Relatórios e métricas’, listadas na Seção 2 deste manual, deverão satisfazer
requisitos mínimos de disponibilidade abaixo. Cada um de seus endpoints
deverá estar disponível:
I - 95% do tempo a cada 24 horas; e
II - 99,5% do tempo a cada 3 meses.
As APIs classificadas
como ‘Serviços’ deverão possuir a mesma disponibilidade do arranjo de pagamento
ou do serviço aos quais estão associadas.
O Portal do Open
Finance deverá conter uma especificação detalhada de como a disponibilidade
de cada endpoint será calculada.
5.5
Timeout
Padronização
do timeout de tempo de resposta do servidor (server) e do tempo
de resposta do consumidor (client) em quinze segundos.
As
requisições que excederem o limite de timeout do servidor deverão ser
respondidas com o código de status HTTP 504 (Gateway Timeout).
6.
Disposições Transitórias
O processo de
publicação em produção da versão 2.0.1 das APIs de ‘Dados Cadastrais e Transacionais’, cuja especificação foi lançada no
portal do Open Finance em 20/06/2022, deverá considerar os seguintes
pontos de controle:
Data
Descrição
24/08/2022
Data limite
para início de execução dos testes no motor de conformidade
10/10/2022
Data limite
para pedido de certificação funcional das APIs
31/10/2022
Data limite
para certificação e publicação das novas APIs no diretório
23/02/2023
Último dia
do período de depreciação da versão 1. As instituições receptoras têm até essa
data para migrar suas soluções para a nova versão das APIs. As instituições transmissoras
devem descontinuar a versão anterior somente depois desta data.
As
modificações dos requisitos de qualidade, atualizados neste manual, devem ser
aplicadas a partir da data de publicação das novas APIs pelas instituições.
Brasília, 19 de setembro de 2022.
NOTA
1135/2022-BCB/DENOR, DE 13 de setembro de 2022.
Fundamenta
proposta de edição de instrução normativa que estabelece a versão 4.0 do Manual
de APIs do Open Finance.
Senhores Chefes do Denor e do
Deinf,
A presente Nota fundamenta
proposta de edição de instrução normativa pelo Departamento de Regulação do
Sistema Financeiro (Denor) e pelo Departamento de Tecnologia da Informação
(Deinf), no uso da atribuição que lhes confere o art. 23, inciso I, alínea
"a", do Regimento Interno do Banco Central do Brasil, anexo à
Portaria nº 84.287, de 27 de fevereiro de 2015, e observado o inciso IX do art.
51 da Resolução Conjunta nº 1, de 4 de maio de 2020.
2. A respeito, a proposta trata
de edição de instrução normativa que estabelece a versão 4.0 do Manual de APIs
do Open Finance, revogando a Instrução Normativa BCB nº 130, de 22 de
julho de 2021, que divulga a versão 3.0 do Manual de APIs do Open Banking.
3. As alterações referem-se à
atualização da expressão Open Banking por Open Finance, conforme mudanças
realizadas pela Resolução Conjunta nº 4, de 24 de março de 2022, a
esclarecimentos sobre o processo de lançamento de novas APIs e suas versões e à
adequação ao padrão ISO 20022; bem como à adequação técnica em pontos
concernentes a limites de tráfego e operacionais, à disponibilidade e
desempenho das APIs e à padronização de tempo de resposta (time-out). A
proposta de instrução normativa dispõe, ainda, sobre pontos de controle para
publicação da versão 2.0.1 das APIs de ‘Dados Cadastrais e Transacionais’, cuja
especificação foi lançada no portal do Open Finance em 20 de junho de
2022.
4. Por fim, em atendimento ao
previsto no art. 5º da Lei nº 13.874, de 20 de setembro de 2019, o Decreto nº
10.411, de 30 de junho de 2020, determina que as propostas de atos normativos
de interesse geral de agentes econômicos formuladas por órgãos e entidades da
administração pública federal direta, autárquica e fundacional, bem como por
colegiados por meio do órgão ou da entidade encarregada de lhe prestar apoio
administrativo, sejam precedidas de Análise de Impacto Regultório (AIR).
5. No entanto, vale destacar que
as alterações e os ajustes propostos não causam impactos significativos para o
conjunto de instituições participantes do Open Finance, por tratar-se de
esclarecimentos e adaptações em orientações já constantes em atos normativos
vigentes, como no caso do tópico sobre versões, e a adequações relacionadas a
tráfego, limites e métricas de chamadas com o objetivo de aperfeiçoar o fluxo
de informações entre as instituições participantes do Open Finance, de
forma a possibilitar o seu monitoramento e esclarecer eventuais disputas. Nesse
sentido, de acordo com o art. 4º, inciso III, do referido Decreto, o ato normativo ora proposto fica dispensado de elaboração de
AIR por ser considerado de baixo impacto.
À consideração de V.Sas.
Mardilson
Fernandes Queiroz Aristides Andrade Cavalcante Neto
Consultor
do Departamento Chefe Adjunto do Departamento de
de Regulação
do Sistema Financeiro Tecnologia da Informação
De acordo.
João
André Calvino Marques Pereira Haroldo Jayme Martins Froes Cruz
Chefe
do Departamento de Regulação Chefe do Departamento de
do
Sistema Financeiro Tecnologia da
Informação
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Acesso Exclusivo para Assinantes
Cadastre-se ou faça login com sua conta do Radar Finsiders Brasil para visualizar esta regulação na íntegra, fazer download dos arquivos e ter acesso a relatórios exclusivos do mercado financeiro.
