01. Introdução

O Open Finance ou Sistema Financeiro Aberto é uma iniciativa do Banco Central do Brasil que tem como principais objetivos trazer inovação ao sistema financeiro, promover a concorrência, e melhorar a oferta de produtos e serviços financeiros ao consumidor final. Este guia tem o objetivo de auxiliar os profissionais envolvidos no negócio e no desenvolvimento desse serviço, facilitando e esclarecendo dúvidas relacionadas ao Diretório e boas práticas envolvidas.

Antes de Começar!

Esse guia tem como objetivo demostrar de forma prática a operação do Diretório Central do Open Finance Brasil. Além disso, ele é complementar a outras documentações disponibilizadas pela governança e não fazem parte do escopo do mesmo quaisquer detalhamentos relacionados a experiência do usuário e desenvolvedor, definições de segurança e especificação de APIs.

Todas as funcionalidades estão disponíveis em sandbox e podem ser testadas em:

https://web.sandbox.directory.openbankingbrasil.org.br

Procedimentos em produção pendentes serão disponibilizados assim que possível.

As ações aqui apresentadas podem ser realizadas tanto por administradores quanto por contatos técnicos primários e secundários.

Para ilustrar este guia e tentar deixar as situações de uso mais palpáveis, foram criadas instituições e telas fictícias.

As instituições e marcas não são reais.
As telas desenvolvidas, os softwares e sites são meramente ilustrativos, para que seja possível ver um exemplo de como os requisitos e as recomendações podem ser aplicados em situações de uso real.
Nomenclaturas e imagens ilustrativas estão descritas na língua inglesa, devido sua ampla abrangência e por conter terminologia técnica que em algumas situações não dispõe de tradução literal. O ajuste do idioma no Diretório fica a critério do usuário, podendo ser ajustado a qualquer momento.

Tipos de Usuários

Neste exemplo, mostramos as diversas possibilidades suportadas de atribuições de função para um usuário cadastrado no Diretório.

Público	O Diretório possibilita o cadastramento de usuários sem vínculos com nenhuma instituição. Esse tipo de usuário não tem nenhum acesso ou poder no Diretório. O cadastramento de um usuário relacionado a um participante, até que não seja feito o vinculo no Diretório, possui essas mesmas características.

Público	O Diretório possibilita o cadastramento de usuários sem vínculos com nenhuma instituição. Esse tipo de usuário não tem nenhum acesso ou poder no Diretório. O cadastramento de um usuário relacionado a um participante, até que não seja feito o vinculo no Diretório, possui essas mesmas características.
Administrativo	Usuários com poderes de administração no Diretório, podendo realizar todas ações.
Operação	Usuários com poderes específicos no Diretório.
Plataforma	Usuários para gestão e operação das plataformas do ecossistema, como o Service Desk, Portal, Plataforma de Resolução de Disputas e Plataforma Centralizada (Ressarcimento).

Para obter mais detalhes sobre consulte Cadastrando um usuário de domínio de autorização e Poderes dos Usuários no Diretório.

Relação - Organização x Marcas

Neste exemplo, mostramos as diversas possibilidades suportadas para se realizar cadastros de organizações no Diretório. Assim, uma organização pode ser cadastrada de forma independente ou pertencente a um conglomerado. Já as marcas são uma forma mais amigável, democrática e fácil para identificação das instituições participantes. Uma Marca de um conglomerado pode estar correlacionada a mais de uma Instituição Participante, assim
como uma Instituição Participante pode estar
correlacionada a mais de uma marca.

Importante: a Marca cadastrada no diretório será a mesma apresentada para escolha do usuário na Jornada de Compartilhamento de Dados e Iniciação de Pagamentos. As Instituições Participantes (ou organizações) também serão apresentadas em tela, apenas em caráter informativo. Para maiores detalhes, consulte o Guia de Experiência do Usuário.

Para obter mais detalhes sobre como cadastrar uma marca veja a seção Cadastrando um Authorisation Server.

Pontos de Atenção no Cadastramento de Marca/Authorisation Server

Uma marca é representada por um Authorisation Server e o mesmo sempre deve ser cadastrado associado a uma organização;
O vinculo entre uma organização master (mãe) e uma organização que pertence ao conglomerado é realizado via o preenchimento do campo Parent Organization Reference ID no cadastro da organização filha, informando o CNPJ da organização mãe (caso seja necessário ajuste, favor entrar em contato com cadastro@openfinancebrasil.org.br);
Quando a estrutura for de um conglomerado (uma organização master e uma ou mais organizações relacionadas) é recomendado do cadastro da marca na instituição mãe, caso as filhas venham a utilizar somente a mesma marca e arquitetura de autenticação. Importante ressaltar que caso não seja cadastrado uma marca exclusiva para o organização filha, a mesma irá herdar a(s) marca(s) da organização mãe;
Caso uma marca pertença a uma organização filha o cadastro deve ser exclusivamente realizado na filha;
Caso a mesma marca pertença a mais de uma organização, deve ser realizado um cadastro de Authorisation Servers para cada uma das organizações. É recomendado que as configurações dos Authorisation Servers sejam iguais, principalmente o campo Customer Friendly Server Name (marca);
Quando for necessário cadastrar uma marca exclusiva para uma organização filha ela deixa de herdar a(s) marca(s) da organização mãe. Caso uma filha tenha que estar relacionada a uma marca exclusiva e também a da mãe, é necessário cadastrar a marca da mãe na filha.

API Participants: Prefira por consumir dados da API Participants. Ela permite que o conteúdo seja fornecido ao usuário através de um servidor mais próximo, acelerando, assim, a distribuição e melhorando a experiência de consumo.
Webhook do Diretório: Inscreva-se no webhook do Diretório para receber os eventos de notificação das principais atualizações, como alteração de cadastro, atualização de marca, entre outros.
Cache local: Alguns participantes optam pela utilização de estruturas de cache local. Assim, é recomendável a revalidação diária dos dados, a fim de mantê-los íntegros e com a versão mais recente possível.

Importante! Caso a instituição queira utilizar alguma chave forte, recomendamos utilizar o AuthorisationServerID. Os campos Customer Friendly Server Name e Description são especialmente susceptíveis a atualizações pelas organizações e não devem ser utilizados para esse fim

Cadastramento - Fase 1 x Fase 2

Se o cadastramento do Authorisation Server na Fase 1 já foi realizado com uma marca válida para a
Fase 2:
- É necessário cadastrar os recursos de Fase 2 no mesmo Authorisation Server, mantendo o Customer Friendly Server Name (marca) da Fase 1;
Se o cadastramento do Authorisation Server na Fase 1 não foi realizado com uma marca válida para a Fase 2:
- É necessário atualizar o Customer Friendly Server Name (marca) para a Fase 2 e cadastrar os recursos de Fase 2 no mesmo;
Os recursos da Fase 1 devem estar declarados em pelo menos um Authorisation Server do participante válido para a Fase 2;
Após esse processo, caso a instituição venha a ter Authorisation Servers / marcas oferecendo recursos exclusivos de fase 2, recomenda-se a criação de novos registros sem os recursos de Fase 1.

Exemplos de Possíveis Cenários

Organização e Marcas	Neste exemplo, temos uma “organização” que não possui “organizações filhas” e possui apenas um AS/marca, a “marca 1”.
Organização e Marcas	Neste exemplo, temos uma “Organização” que não possui “Organizações Filhas” mas que possui N AS/marca.
Conglomerado	O relacionamento entre as “organizações filhas” com a “organização mãe” é realizado via PARENT ORGANISATION REFERENCE ID, preenchendo o Parent das “organizações filhas” com o CNPJ da “organização mãe”. Quando uma “organização mãe” tem uma ou mais de uma “organização filha”, temos um conglomerado Neste exemplo, temos uma “organização mãe” que possui uma marca (“marca 1”) que é compartilhada com a “organização filha 1”. Já a “organização filha 2” possui sua próprio marca “marca 2”
Organização e Marcas	Neste exemplo, temos uma “organização mãe” que possui uma marca “marca 1”. A mesma “marca 1” está presente na “organização filha 1”, mas não na “organização filha 2”. A “organização filha 1” deve apresentar a “marca 1” e a “marca 2”, como ela possui uma marca não receberia a da “organização mãe” por isso ambas as marcas devem ser declaradas. Atenção! Uma “organização filha” que tenha qualquer marca cadastrada, não assume a marca da mãe! A “organização filha” só assume a marca da mãe se não tiver nenhuma marca cadastrada nela! Lembrando, o relacionamento entre as organizações é realizado via preenchimento do campo PARENT ORGANISATION REFERENCE ID na instituição filha referenciando a mãe.
Organização e Marcas	Neste exemplo, temos uma “organização mãe” que possui uma “marca 1” que é compartilhada com a “organização filha 3”. Logo, a “organização filha 3” assume a “marca 1”. Já a “organização filha 1” e “organização filha 2” possuem sua próprio marca, que é a “marca 2” e devem ser relacionada a cada uma delas. Se a “marca 2” fosse adicionada na “organização mãe” a “organização filha 3” iria receber também. Lembrado, o relacionamento entre as organizações é realizado via preenchimento do campo PARENT ORGANISATION REFERENCE ID na instituição filha referenciando a mãe.
Organização e Marcas	Neste exemplo, temos uma “organização mãe” que possui uma marca “marca 1” que é compartilhada com a “organização filha 4”. Já a “organização filha 1” e “organização filha 2” possuem sua própria marca igual “marca 2” mas que está relacionada a apenas a elas. A “organização filha 3” possui duas marcas exclusivas dela “marca 3” e “marca 4”. Lembrando, o relacionamento entre as organizações é realizado via preenchimento do campo PARENT ORGANISATION REFERENCE ID na instituição filha referenciando a mãe.