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 o cadastro da marca na instituição mãe, caso as filhas venham a utilizar a mesma marca e arquitetura de autenticação. Importante ressaltar que caso não seja cadastrado uma marca exclusiva para o organização filha, será inferido que os cadastros de marcas para atendimento dos papéis regulatórios foi realizado na organização mãe;
Caso a mesma marca pertença a mais de uma organização, esta deverá ser cadastra como um único Authorisation Server em apenas uma das organizações. É vedado a duplicação de marcas, ou seja, marcas que possuem o mesmo Customer Friendly Server Name;
Caso uma marca pertença exclusivamente a uma organização filha o cadastro poderá ser realizado apenas na filha;
É permitido que o papel regulatório pertencente apenas à uma organização filha seja replicado na organização mãe para permitir o reuso de solução arquitetural e Authorisation Server.

Importante! Devido a questões históricas, algumas instituições apresentam marcas duplicadas. Por isso, é essencial que os clients das receptoras e iniciadoras de pagamento estejam preparadas para lidar com essa situação até que esses participantes migrem ou unifiquem seus servidores, a fim de regularizar a questão.

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

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 os papéis regulatórios DADOS e CONTA. Neste cenário a organização possui apenas um AS/marca, a “Marca 1”, que possui todos os recursos necessários para atendimento dos seus papéis regulatórios.
Organização e Marcas	Neste exemplo, temos uma “Organização” que não possui organizações filhas e possui os papéis regulatórios DADOS e CONTA. Neste cenário a organização possui três AS/marcas, a “Marca 1” que possui os recursos necessários para atendimento do papel DADOS, a “Marca 2” que possui os recursos referente ao papel “CONTA” e a “Marca 3” atende a ambos os papéis regulatórios.
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 duas filhas e todas possuem os mesmos papéis regulatórios DADOS e CONTA. Neste cenário a “organização mãe” possui um AS/marca, a “Marca 1”, que possui apenas um AS/marca, a “Marca 1” que possui todos os recursos necessários para atendimento dos seus papéis regulatórios. Ambas as suas organizações filhas compartilham da mesma arquitetura e infraestrutura de autenticação, utilizando o mesmo AS/marca para compartilhamento dos seus recursos.
Organização e Marcas	Neste exemplo, temos uma “organização mãe” que possui duas filhas que possuem papéis regulatórios distintos. A “organização mãe” e a “organização filha 1” possuem o papel regulatório DADOS, enquanto a “Organização Filha 2” possui o papel regulatório CONTA. Neste cenário a “organização mãe” possui um AS/marca, a “Marca 1”, que possui apenas um AS/marca, a “Marca 1”, entregando todos os recursos necessários para atendimento do papéis regulatórios tanto para a “Organização Mãe”, quanto para a “Organização Filha 1”, compartilhando a mesma arquitetura e infraestrutura de autenticação. A “Organização Filha 2” possui a “Marca 2” que entrega os recursos necessários para atender ao seu papel regulatório. Neste caso, a “Organização Filha 2” possui a sua própria arquitetura e infraestrutura de autenticação.
Organização e Marcas	Neste exemplo, temos uma “organização mãe” que possui duas filhas que possuem papéis regulatórios distintos. A “Organização Mãe” e a “Organização Filha 1” possuem o papel regulatório DADOS, enquanto a “Organização Filha 2” possui o papel regulatório CONTA. Com a intenção de reuso da arquitetura e infraestrutura de autenticação, o participante replicou o papel regulatório da “Organização Filha 2” para a “Organização Mãe” e desta forma, com uso de uma única marca/AS, a “Marca A”, entrega todos os recursos necessários para atender aos papéis regulatórios do conglomerado.
Organização e Marcas	Neste exemplo, temos uma “Organização Mãe” que possui duas filhas e todas possuem os mesmos papéis regulatórios DADOS e CONTA. Neste cenário a “organização mãe” possui um AS/marca, a “Marca 1”, que possui apenas um AS/marca, a “Marca 1” que possui todos os recursos necessários para atendimento dos papéis regulatórios da “Organização Mãe” e “Organização Filha 1”. A “Organização Filha 2” possui a “Marca 2” que entrega os recursos necessários para atender dos seus papéis regulatórios. Neste caso, a “Organização Filha 2” possui a sua própria arquitetura e infraestrutura de autenticação.

Draft - Área do Desenvolvedor