Introdução

Sejam bem-vindos à área do desenvolvedor do Portal do Open Banking Brasil.

Nessa área os desenvolvedores encontrarão informações para observância obrigatória de todos os participantes, sejam eles obrigatórios ou voluntários, incluindo padrões técnicos de interfaces, glossário de termos técnicos, especificações dos diferentes tipos de APIs - incluindo seu versionamento, requisitos não funcionais como SLAs e limites de tráfego de requisições, informações de desempenho e disponibilidade, FAQ com diversas orientações aos desenvolvedores, entre outros elementos necessários à implementação do Sistema Financeiro Aberto. Todas as informações foram definidas de acordo com a regulamentação vigente no País, respeitando instruções normativas e resoluções do Banco Central do Brasil e do Conselho Monetário Nacional.

Este sítio eletrônico e seu conteúdo foram criados e são mantidos pela Estrutura responsável pela Governança do Open Banking Brasil, formada por integrantes de múltiplas associações: Febraban, ABBC, ACREFI, ABBI, OCB, Abecs, Abipag, Abranet, Câmara e-net, ABCD e ABFintechs.

Notificações

Workshops com OpenID Foundation

publicado em 26 de maio de 2021

A OpenID Foundation promoveu dois workshops para os participantes do Open Banking Brasil sobre o perfil de segurança FAPI e o conjunto de testes de conformidade e certificação FAPI.

Os workshops tiveram 5 objetivos principais:

• Atualizar os participantes dos últimos desenvolvimentos no perfil OIDF Financial-Grade API (FAPI) e nos requisitos brasileiros;

• Demonstrar as respectivas ferramentas de conformidade e os benefícios da certificação;

• Oferecer aos participantes apoio no uso dessas ferramentas;

• Incentivar um maior número de certificações;

• Ajudar a expandir o ecossistema de Open Banking, aumentando a segurança e os benefícios para os participantes e clientes finais.

No dia 17 de maio de 2021 foi realizado o primeiro workshop, que consistiu em uma introdução à OpenID Foundation, padrões OpenID incluindo FAPI e o programa de certificação OpenID. A gravação do workshop pode ser acessada pelo link

No dia 24 de maio de 2021 foi realizado o segundo workshop, que possuiu um aprofundamento mais técnico. Neste workshop, foi abordado o detalhamento das características do FAPI, incluindo o FAPI 2.0, e uma demonstração abrangente do pacote de conformidade FAPI, incluindo uma demonstração ao vivo de uma implementação FAPI. A gravação do workshop pode ser acessada pelo link

Atualização das APIs no diretório

publicado em 14 de abril de 2021

Seguindo determinação do Banco Central do Brasil, todas as instituições financeiras vinculadas à Fase 1 do Open Banking deverão especificar todas as ramificações (endpoints) de suas famílias de APIs no diretório de < target="_blank" href="https://auth.directory.openbankingbrasil.org.br/interaction/asl3sZulHvQW1SjMnXLtu">participantes do Open Banking</>. Essa atualização deverá ser feita em até 15 dias a partir da data de envio deste documento.

Na prática, as instituições deverão excluir a entrada que já existe no diretório de participantes e incluir cada uma das ramificações que entenda serem válidas para o seu próprio caso.

Tratam-se de 4 famílias de APIs, com até 20 ramificações no total. Essa atualização proporcionará mais transparência ao consumidor, que terá mais facilidade para localizar as informações das instituições. A ação também evitará distorções nas métricas de disponibilidade de interfaces, já que as instituições não deverão cadastrar endpoints relativos a dependências ou a produtos e serviços que não tenham, não ofertem ou não distribuam.

Dessa maneira, a mensagem de erro 404 não será mais exibida nestes casos. Até o dia 16 de abril de 2021, uma FAQ com as principais dúvidas será disponibilizada, assim como um manual com passo a passo para a atualização das APIs.

São Paulo, 14 de abril de 2021

Grupo de Trabalho de Infraestrutura do Open Banking Brasil

Como realizar a publicação das APIs da Fase 1 do Open Banking

publicado em 14 de abril de 2021

Para a primeira fase do Open Banking Brasil, conhecida como Open Data, as instituições registradas no ecossistema com o papel “instituição transmissora e receptora de dados” deverão realizar a publicação das suas APIs no diretório de participantes.

O papel “instituição transmissora e receptora de dados”, abreviada por DADOS no diretório de participantes, é destinado a todas as instituições dos agrupamentos S1 e S2, em caráter obrigatório, e a qualquer outra instituição regulada pelo Banco Central do Brasil, em caráter voluntário.

Para publicar as APIs da fase 1 descritas no Portal do Desenvolvedor do Open Banking o administrador da instituição no diretório de participantes com papel “DADOS” deve seguir as instruções contidas no Guia do diretório.

Caso a publicação tenha sido realizada de forma correta os endpoints das APIs poderão ser consultados através do JSON retornado pela API de participantes do diretório: https://data.directory.openbankingbrasil.org.br/participants. O acesso a essa API é livre e seu conteúdo é atualizado a cada 15 minutos.

Qualquer dúvida em relação ao processo de cadastro deverá ser enviado ao service desk do Open Banking.

Materiais adicionais:

Comunicado atualização do diretório

FAQ Diretório atualizado

Cadastro endpoints

Guia de experiência de compartilhamento de dados

Esse guia é parte integrante do regulamento do Open Banking no Brasil e engloba um conjunto de requisitos mínimos que devem ser seguidos pelas instituições participantes com o objetivo de nortear a sua implantação e garantir uma experiência adequada e padronizada ao cliente, com foco na jornada de compartilhamento de dados.

Direcionado às instituições participantes do Open Banking no Brasil, o guia de experiência apresenta princípios, diretrizes, referências, requisitos obrigatórios e recomendações para a criação da jornada de compartilhamento de dados. 

As recomendações podem ser seguidas para complementar a experiência, porém funcionalidades não previstas nesse documento serão aceitas, desde que atendam aos princípios e às diretrizes da regulamentação em vigor.

Cada caso de uso é acompanhado de telas ilustrativas para facilitar a compreensão do texto que não implicam em obrigatoriedade para o desenvolvimento das interfaces.

O guia pode ser baixado nesse link (OpenBanking - Guia de experiência de compartilhamento de dados).

Padrões

Estes padrões representam a versão 1.0.0, a qual fornece uma visão alto nível dos padrões. Consulte a seção versionamento para obter mais informações sobre como as versões são gerenciadas com o padrão.

Observe que, nesta proposta, as palavras-chave DEVEM, NÃO DEVEM, NECESSÁRIAS, RECOMENDADO, PODE e OPCIONAL, devem ser interpretadas conforme descrito na RFC2119.

Princípios

Os seguintes princípios técnicos não exaustivos constituem a base para o desenvolvimento e implementação das APIs para o Open Banking no Brasil.

Princípio 1: Segurança

A adoção de mecanismos de segurança no design e implementação das APIs do Open Banking no Brasil deverá considerar os padrões aplicáveis a cada uma de suas fases, visando a proteção e a disponibilidade do ecossistema como um todo, considerando clientes, participantes e os dados específicos compartilhados em cada fase.

Princípio 2: RESTful APIs

A API irá aderir aos conceitos de RESTful API sempre que for possível e sensato.

Princípio 3: Padrões existentes

Os padrões existentes serão adotados sempre que sua aplicação for relevante/apropriada e desde que não violem nenhum dos demais princípios, com foco na experiência do desenvolvedor e do usuário, e ainda, prevendo a extensibilidade, resiliência e a evolução do Open Banking no Brasil.

Princípio 4: ISO 20022

Os payloads das APIs serão desenvolvidos utilizando como base os elementos e componentes de mensagem ISO 20022, que poderão ser modificados, caso necessário, para deixar o payload mais simples e/ou atender às características locais, tal como implementado em diferentes jurisdições.

Princípio 5: Extensibilidade

Os fluxos das APIs serão estendidos para atender a casos de uso mais complexos em futuros releases, e, portanto, esse princípio será mantido em mente durante o design, e os procedimentos serão detalhados durante a implementação.

Princípio 6: Códigos de Status

A API usará dois códigos de status que atendem a dois propósitos diferentes: (i) o HTTP status code reflete o resultado da chamada da API e (ii) um campo status em alguns resource payloads reflete o status dos resources nos casos de acesso write (p.ex. iniciação de pagamento).

Princípio 7: Identificadores únicos

Um recurso REST deverá ter um identificador exclusivo que possa ser usado para identificar o recurso alvo da API. Este identificador será usado para criar URLs que permitam endereçar recursos específicos, obedecendo aos padrões definidos nesta documentação, no item Formação e estabilidade do ID.

Princípio 8: Categorização dos requisitos de implementação

Quando um requisito estiver sendo implementado por um transmissor e/ou um receptor, uma categorização diferente será aplicada. As funcionalidades, endpoints e campos em cada recurso serão categorizados como 'Obrigatório', 'Condicional' ou 'Opcional'.

Princípio 9: Agnósticas

As APIs serão agnósticas à implementação onde elas poderão ser consumidas independente das tecnologias adotadas no ecossistema, porém com aderência aos princípios contidos nesta documentação.

Princípio 10: Idempotência

As APIs serão definidas como idempotentes para não causar uma experiência ruim ao consumidor ou aumentar os indicadores de risco falso positivo. Trata-se de recurso necessário para garantir que não haja duplicidade em caso de perda de comunicação e não deve se limitar aos verbos HTTP, devendo ser aplicado ao design completo da API.

Versionamento

O controle de versão contemplará 4 tipos de lançamento (p.ex. major, minor, patch e release candidate) e terá prazos definidos para lançamento e implementação de novas versões major, bem como suporte de versões anteriores.

No link Anexo: Guia de Versionamento, integrante desta documentação, estão documentados os casos previstos em que uma nova versão de API poderá vir a quebrar o contrato estabelecido

O versionamento terá o seguinte formato contemplando 4 tipos de lançamentos de versões: 1.12.2.rc1 - significando versão major 1, versão minor 12 , aplicação de patchs versão 2 e release candidate 1

• Major: inclui novas características da implementação, mudanças, correções a serem incorporadas e que poderão vir a quebrar o contrato.
  • P.ex. v1.0.0, v2.0.0.
• Minor: pequenas mudanças nos elementos já existentes, com manutenção da compatibilidade e sem quebra de contrato.
  • P.ex. v1.1.0, v1.2.0
• Patch: esclarecimentos às especificações publicadas pelo diretório, não incluem alterações funcionais.
  • P.ex. v1.1.1, v1.1.2
• Release candidate: versões de pré-lançamento de qualquer patch futuro, minor ou major.
  • P.ex. v1.0.0-rc , v1.0.0-rc2

Será definido um cronograma de novas versões dos padrões para que os participantes consigam se planejar e desenvolver novas APIs, com cada um dos lançamentos tendo um prazo pré-estabelecido para ser implementado pelos participantes, mitigando, desta forma, o risco de múltiplas versões.

Não serão feitos mais do que um lançamento de versão major em um período de 6 meses. No entanto, serão previstas exceções para atender às alterações urgentes que não podem esperar até a próxima versão principal (major). Lançamentos de versões minor e patch podem ocorrer a qualquer momento.

Lançamentos minor não podem configurar em quebra de contrato, impactar significativamente endpoints e/ou exigir manutenção crítica.

Por fim, credenciais de acesso associadas às APIs deverão ser agnósticas à versão.

Estrutura da URI

A estrutura da URI para os endpoints deve ser implementada conforme abaixo:
<host> / open-banking / <api> / <versão> / <recurso>

Os componentes desta estrutura de URI estão descritos abaixo:

• Host: O host de API da entidade financeira implementadora é um endereço base definido pela entidade transmissora de dados.
• “open-banking”: Esta é uma string constante que representa a finalidade desta API.
• API: A API que será consumida (p.ex. channels).
• Versão: O número da versão da API. Na URI a versão deve ser precedida pela letra "v" seguida pelo número da versão a ser consumida (p.ex. v1, v2, v25).
• Recurso: O recurso a ser consumido dentro de uma API. Utilizando como exemplo a API channels, a mesma possui 5 recursos:
  • branches
  • banking-agents
  • electronic-channels
  • phone-channels
  • shared-automated-teller-machines

A versão minor será repassada apenas no header do payload de resposta, orientando a instituição receptora sobre quais serão os dados no retorno.

Como exemplo, para realizar o consumo do método electronic-channels da API channels na versão 1, a URI ficaria com a seguinte estrutura:

<host>/open-banking/channels/v1/electronic-channels

Cabeçalhos HTTP

Cabeçalhos HTTP suportados e suas funções.

Cabeçalho de requisição

Cabeçalho de resposta

Códigos de resposta HTTP

Os códigos de resposta HTTP devem ser utilizados conforme tabela mais abaixo. Observação: com a implementação do cadastro por endpoint no diretório de participantes e conforme orientação do regulador, as instituições participantes NÃO DEVEM cadastrar endpoints de produtos ou serviços que não ofertem. Neste caso específico - a consulta em um endpoint não cadastrado - o status code esperado na resposta é o 404 - NOT FOUND.

Códigos

Convenções de payload

Esta seção do padrão descreve as estruturas padrões de requisição e resposta para todos os endpoints das APIs, assim como as convenções de nomenclatura para os atributos.

Estrutura de requisição

Estrutura da requisição

{
  "data": {
    "..."
  }
}

Cada requisição deve ser um objeto JSON contendo um objeto data para armazenar os dados primários da requisição.

No mesmo nível do objeto data, poderá existir um objeto meta se assim for especificado pelo endpoint. O objeto meta é usado para fornecer informações adicionais ao endpoint, como parâmetros de paginação, contagens de paginação ou outros propósitos complementares ao funcionamento da API.

A definição do conteúdo para o objeto data será definida separadamente para cada endpoint.

Estrutura de resposta

Estrutura de resposta

{
  "data": {
    "..."
  },
  "links":{
    "..."
  },
  "meta": {
    "..."
  }
}

Cada endpoint retornará um objeto JSON contendo os atributos abaixo:

• Se a resposta for bem-sucedida (200 OK), o objeto JSON irá conter:
  • obrigatóriamente um objeto data
  • obrigatóriamente um objeto links
  • opcionalmente um objeto meta, se necessário pela definição do endpoint requisitado
• Se a resposta for malsucedida (não 200 OK), o objeto JSON poderá conter:
  • um objeto errors (conforme a definição específica do endpoint)

A definição do conteúdo para os objetos data e meta será definida separadamente para cada endpoint.

O objeto links irá conter hypermedia (referências para recursos relacionados) para outros recursos da API requisitada.

O objeto de links sempre irá conter o atributo self que irá apontar para a URI da solicitação atual.

Estrutura de resposta de erros

{
  "errors": [
    {
        "code": "...",
        "title": "...",
        "detail": "..."
    }
  ],
  "meta":{
    "..."
  }
}

• O objeto errors será um array de zero ou mais objetos. Os atributos deste objeto serão os descritos abaixo:
  • obrigatoriamente o atributo code contendo um código de erro específico do endpoint;
  • obrigatoriamente o atributo title contendo um título legível por humanos do erro deste erro específico;
  • obrigatoriamente o atributo detail contendo uma descrição legível por humanos deste erro específico;
  • opcionalmente o objeto meta contendo dados adicionais sobre o endpoint que seja relevante para o erro.

Convenções de nomenclatura de atributos

Caracteres válidos em nomes de atributos

Todos os nomes de objetos e atributos definidos nos objetos JSON de requisição e resposta devem ser nomeados seguindo o padrão camelCase, tendo seu nome composto apenas por letras (a-z, A-Z) e números (0-9).

Qualquer outro caractere não deve ser usado nos nomes dos objetos e atributos, com exceção do caractere - (hífen), que poderá ser utilizado apenas conforme descrito na seção Extensibilidade.

Estilo de nomeação de atributos

Os nomes dos objetos e atributos devem ser nomes significativos e em língua inglesa. Quando houver diferença entre inglês americano e inglês britânico no termo a ser utilizado, deverá ser utilizado o termo em inglês britânico. P.ex. Utilizar o termo Post Code (Reino Unido) ao invés de Zip Code (Estados Unidos).

Arrays devem ser nomeados no plural. Demais atributos deverão ser nomeados no singular.

Convenções de propriedade dos atributos

Tipos de dados dos atributos

Cada atributo deverá estar associado a um tipo de dado. A lista de tipos de dados válidos está definida na seção tipos de dados comuns. Se um tipo de dado personalizado é necessário para um atributo, o mesmo deverá ser classificado como uma string com uma descrição clara de como o valor da propriedade deve ser interpretado.

Atributos Obrigatórios / Opcionais

Segundo Instrução Normativa nº 34, BCB de 2020: ‘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’.

Os atributos obrigatórios devem estar presentes e ter um valor não nulo, seja em uma requisição ou resposta, para que payload seja considerado válido.

Os atributos condicionais podem ter uma restrição vinculada a eles, tornando-os obrigatórios conforme a situação descrita na coluna 'restrição' do dicionário de dados.

Atributos vazios / nulos

Um atributo omitido (ou seja, um atributo que não está presente no payload) será considerado equivalente a um atributo que esteja presente com o valor null.

Uma string vazia (“”) não será considerada equivalente a null.

O valor booleano false não será considerado equivalente a null. Os atributos booleanos opcionais, por definição, possuirão três valores possíveis: verdadeiro (true), falso (false) e indeterminado (null).

Na situação onde o campo a ser informado no payload seja obrigatório e a Instituição, seja consumidora no envio ou transmissora no retorno, não a possuir, deve-se implementar o valor padronizado: “NA” - Não se Aplica, com exceção dos campos declarados como ENUM que deverão ser sempre preenchidos com os valores válidos para o ENUM correspondente.

Convenções de nomenclatura

Todos os nomes devem ser autoexplicativos, sem redundância de termos e sem ambiguidade de entendimento, além de seguir o padrão Lower Camel Case (primeira letra de cada termo maiúscula, com exceção do primeiro termo, que fica todo em minúsculas e sem espaços ou pontuações entre os termos). Ex: “areaCode”.

Os nomes das estruturas (composição de atributos sobre um assunto) que podem ter mais de uma ocorrência devem sempre estar no plural.

Os nomes dos atributos devem:

• Sempre estar no singular

• Nos casos em que o nome não ficar claro, devem ser incluídos mais termos para esclarecer o entendimento

• Para garantir o entendimento e a padronização, nos casos de atributos que tratem dados específicos, sempre devem ser usados termos complementares no fim dos nomes. São esses:

  • nomes = Name (p.ex. ownerName)
  • datas = Date (p.ex. openingDate)
  • horários = Time (p.ex. openingTime)
  • quantidades = Quantity (p.ex. eventLimitQuantity)
  • textos explicativos = Info* (p.ex. additionalInfo)

  *Para textos explicativos de informações complementares, o nome completo do atributo é “additionalInfo”

• Em atributos que sejam indicadores binários (flags), o nome deve estar formatado como pergunta, com um verbo como primeiro termo. Ex: “hasRewardProgram”

Tipos de dados comuns

Propriedades

Paginação

Cada recurso de cada API pode possuir ou não paginação, caso a quantidade de registros retornados justifique a mesma. A paginação estará disponível e deverá funcionar independente se o recurso permite filtros por query ou POST. Isso é, filtros e paginação são aplicados de forma independente.

Parâmetros de Requisição

Exemplo de query com paginação

GET {uri}?page=1&page-size=25

Quando existir paginação para o recurso deverão ser utilizados os parâmetros de query abaixo para a navegação dos resultados:

Atributos de Resposta

Exemplo de paginação

{
  "data": {
    "..."
  },
  "links": {
    "self": "https://api.banco.com.br/open-banking/products-services/v1/personal-invoice-financing",
    "first": "https://api.banco.com.br/open-banking/products-services/v1/personal-invoice-financing",
    "prev": null,
    "next": null,
    "last": "https://api.banco.com.br/open-banking/products-services/v1/personal-invoice-financing"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1
  }
}

Além dos dados requisitados, as respostas paginadas também terão em sua estrutura dois objetos adicionais que incluirão parâmetros para facilitar a navegação das páginas:

Links

O objeto links passará por revisão subsequente de modo a atender as próximas Fases do Open Banking, em especial a partir da Fase 2. No objeto links, serão retornadas hypermedia (referências para os recursos relacionados) de paginação conforme parâmetros abaixo:

Meta

No objeto meta, serão retornadas informações sobre o total de registros disponíveis

Regras Adicionais

• Não é esperado que os provedores implementem paginação com isolamento de transação. Os dados que serão retornados podem mudar entre requisições subsequentes. Isto pode causar situações onde um mesmo registro pode ser retornado em mais de uma página.
• O tamanho máximo da página é 1000 registros para qualquer endpoint (a menos que na documentação desse esteja informando outros valores).
• Se for requisitado uma quantidade de registros maior que o suportado, o retorno será o código HTTP status code 422 Unprocessable Entity, indicando que o servidor entendeu a requisição, mas não é possível processá-la conforme foi solicitado.

Formação e Estabilidade do ID

Dentro desses padrões, a serem melhor especificados a partir da Fase 2 do Open Banking no Brasil, os IDs de recursos são necessários para atender ao seguinte:

• O ID de um recurso deve ser especificado no endpoint de uma API apenas para obter detalhes do recurso ou para realizar alterações no mesmo.
• Se o ID for especificado nos padrões do Open Banking, então ele é obrigatório e deverá ser fornecido pela entidade implementadora da API de acordo com o padrão definido.
• Se um ID for especificado, o mesmo deverá ser totalmente desconectado de significados com outras entidades. Por exemplo, um ID não deve ser uma combinação de outros campos ou uma string que possa ter conteúdo sensível que possa ser extraído.
• Os IDs devem ser únicos, e sua padronização será detalhada a partir da Fase 2 do Open Banking no Brasil, porém sua unicidade pode estar dentro de um contexto. Por exemplo, um ID de conta corrente deve ser único, porém apenas dentro do contexto de conta corrente.
• Nos payloads o nome de campo "id" nunca deverá ser utilizado. Cada campo ID deverá ter um nome significativo, dessa forma independentemente de onde o ID for utilizado entre múltiplos endpoints, ele sempre irá se referir ao seu objeto principal. Por exemplo, IDs para conta deverão ser representados no JSON como "accountId".

Princípios para a formação de IDs (identificadores) de recursos nas APIs

• O ID DEVE ser uma string com limitação de 100 caracteres - limite que poderá ser revisitado em caso de necessidade apresentada por quaisquer dos participantes do Open Banking Brasil e - aderente aos padrões apresentados na seção 2.1 da RFC 2141;
• Uma vez que será trafegado nas chamadas de interface, o ID NÃO DEVE conter dados classificados como PII - Personally identifiable information (Informação Pessoalmente Identificável) ou Informação de Identificação Pessoal;
• DEVE ser garantida a unicidade do ID dentro do contexto da API assim como a estabilidade do mesmo, sendo a estabilidade condicionada à manutenção das características de identificação natural do recurso em questão (por exemplo, as informações de banco, agência e conta na API de Contas). A alteração das características de identificação natural implica na geração de um novo identificador associado ao recurso;
• A utilização de meios técnicos razoáveis e disponíveis para a formação do ID é de livre implementação por parte da instituição transmissora dos dados, de forma que apenas a aderência aos princípios elencados nesta documentação é mandatória.

Extensibilidade

Os padrões de Open Banking podem não cobrir todas as possibilidades de objetos retornados ou APIs que os participantes desejam expor. Os participantes podem ter o desejo de realizar inovações sobre os padrões definidos oferecendo mais dados afim de atender demandas específicas de mercado. É nossa intenção que os padrões definidos não apenas permitam estas extensões como também sirvam como base para futuras alterações na própria definição dos padrões.

No entanto, é importante que um participante que esteja querendo estender as APIs não impeça um consumidor que foi projetado para consumir apenas o endpoint padrão funcione corretamente.

Para atender tanto as demandas de quem deseja estender as APIs (participantes) quanto as demandas de quem irá realizar o consumo (consumidor das APIs), foram definidos os critérios abaixo.

É possível estender os padrões nos seguintes aspectos:

• O participante pode oferecer uma API completamente nova que não está coberta nos padrões definidos
• O participante pode oferecer novos endpoints em uma API que já foi definida no padrão
• O participante pode oferecer campos de entrada e retorno opcionais para um endpoint que já foi definido no padrão

ID dos participantes

Cada participantes terá um ID que representa a sua instituição. Os participantes da atual versão estão listados abaixo:

• BBAS - Banco do Brasil
• BBCD - Bradesco
• BTGP - BTG Pactual
• CAIX - Caixa Econônica Federal
• ITAU - Itau
• STDR - Santander
• BRGS - Banrisul
• BNBR - Banco do Nordeste do Brasil
• BNDS - BNDES
• CITI - Citibank
• SAFR - Safra
• BABV - Votorantim

Participantes que desejam estender os padrões devem adicionar seu prefixo para identificar todas as extensões. Campos adicionais no retorno de endpoints existentes ou em novos endpoints devem usar o prefixo do participante. O prefixo deve ser no formato exposto ao lado (4 letras) e não devem haver prefixos duplicados entre os participantes.

Nesta documentação, quando tivermos que nos referir ao prefixo do participante, o termo <PID> será utilizado.

Novas APIs

Quando a extensão for a criação de uma nova API, o participante deve adicionar seu prefixo a URI antes do nome da nova API, conforme exemplo abaixo.

Por exemplo, uma API definida pelo padrão seguirá o seguinte formato: <host> / open-banking / <api> / <versão> / <recurso>

Uma API estendida por um participante deverá estar no formato abaixo: <host> / open-banking / <PID> / <api> / <versão> / <recurso>

Para os endpoints definidos dentro da estrutura acima, os atributos dos payloads não precisam conter o prefixo do participante, pois entende-se que todos os recursos da API estendida não conflitam de nenhum modo com as definidas pelo padrão.

Novos endpoints em APIs existentes

Quando o participante desejar adicionar um novo endpoint em uma API já especificada no padrão, o participante deve incluir seu <PID> como prefixo do recurso que será implementado.

Por exemplo, assumindo a existência do endpoint abaixo para consulta das transações de uma conta: <host>/open-banking/accounts/v1/accounts/{account ID}/transactions

Se o participante deseja adicionar um novo endpoint que resume as transações por um período, então este endpoint poderia ser definido como: <host>/open-banking/accounts/v1/accounts/{account ID}/<PID>-balance-movement

Campos de retorno adicionais em um endpoint existente

Quando o participante desejar adicionar um novo campo ao payload de resposta, o atributo deverá receber o prefixo do participante seguido por um hífen <PID>-.

Se um objeto estiver sendo adicionado ao payload de resposta, apenas o nome do objeto precisa receber o prefixo. Qualquer atributo dentro do novo objeto pode ser nomeado normalmente.

Parâmetros query adicionais

Quando for adicionado um novo parâmetro de query a um endpoint existente, o novo parâmetro deve ter o prefixo <PID>-, evitando assim colisões com parâmetros já existentes.

Filtro de Dados

Opcionalmente, a entidade transmissora de dados poderá realizar filtro de dados através de query de entrada, baseado em campos que julgue relevante para a melhor experiência do cliente.
A informação de quais possibilidades estarão disponíveis (query parameter) deverá constar em documentação adicional disponibilizada pela entidade transmissora.

Extensão do versionamento

Como descrito na seção versionamento, o versionamento existe apenas no nível das APIs e não no nível dos endpoints, no entanto caso seja necessário realizar versionamento de um endpoint customizado, o participante poderá utilizar o header x-<PID>-v para que o consumidor possa especificar qual versão do endpoint está requisitando.

Glossário

Glossário

Agência (Branch)

É a dependência destinada ao atendimento aos clientes, ao público em geral e aos associados de cooperativas de crédito, no exercício de atividades da instituição, não podendo ser móvel ou transitória

Adiantamento a Depositante (Unarranged Account Overdraft)

O valor que o banco libera na conta-corrente do cliente, em casos excepcionais, o valor necessário para cobrir algum saque, pagamento, débito automático ou cheque, quando o saldo disponível não é suficiente.

Bandeira (Credit Card Network)

São instituições que autorizam o uso de sua marca e de sua tecnologia por emissores e credenciadoras de estabelecimentos. Essas marcas aparecem nos cartões e nos estabelecimentos credenciados.

Cartão Múltiplo (Multiple CreditCard)

Trata-se de um único cartão que possui mais de uma função, ou seja, que pode ser utilizado como débito, crédito e para a movimentação da conta.

CBO (Cbo Code)

A Classificação Brasileira de Ocupações (CBO) é um documento que retrata a realidade das profissões do mercado de trabalho brasileiro. Foi instituída com base legal na Portaria nº 397, de 10.10.2002. Trata-se de um sistema de classificação responsável pela codificação dos títulos e conteúdos dos cargos e ocupações do mercado de trabalho brasileiro

Cheque Especial (Arranged Overdraft)

É uma operação de crédito, a exemplo do empréstimo, mas que é pré-aprovada e vinculada a uma conta de depósitos à vista. Tem o objetivo de cobrir movimentações financeiras quando não há mais saldo disponível na conta.

O banco disponibiliza ao cliente um limite de crédito rotativo que, embora apareça no extrato da conta, não é um recurso do cliente. Quando utilizado esse valor, o banco pode cobrar juros sobre o valor usado, ou seja, sobre o saldo devedor.

Fonte: link

CNAE (Cnae Code)

Trata-se de um código utilizado para identificar quais são as atividades econômicas exercidas por uma empresa. A Classificação Nacional de Atividades Econômicas - CNAE é oficialmente adotada pelo Sistema Estatístico Nacional e pelos órgãos federais gestores de registros administrativos

CNPJ (CNPJ Number)

Código gerido pela Secretaria da Receita Federal e utilizado para identificação das empresas no Cademp. O CNPJ corresponde ao número de inscrição no Cadastro de Pessoa Jurídica. Composto por: os oito primeiros números à esquerda (XX. XXX. XXX) formam a "raiz" ou base, que identifica a empresa de forma única. Os quatro seguintes números de ordem das filiais da empresa. Normalmente a empresa matriz tem este campo preenchido com '0001'. Os dois últimos números correspondem ao dígito verificador. composição do CNPJ pode ser assim representada, conforme ex. '50.685.362/0001-35'.

Código Compe (compeCode)

O Compe (Sistema de Compensação de Cheques e Outros Papéis) é um sistema que identifica e processa as compensações bancárias. Ele é representado por um código de três dígitos que serve como identificador de bancos, sendo assim, cada instituição bancária possui um número exclusivo.

Código Ocupação Receita Federal – Receita Federal Code

Código da atividade profissional relacionada com a principal fonte pagadora dos seus rendimentos, assim entendida a que pagou maior rendimento independentemente de escolaridade ou de formação acadêmica

Fonte: link

Conta Individual (Sole Account)

Tipo de conta que comporta apenas um titular.

Conta Conjunta Não-solidária (Joint Account And)

Tipo de conta que comporta mais de um titular, em que os titulares dependem da autorização de “pelo menos” um diferente titular para realização de movimentações em contas.

Conta Conjunta Solidária (Joint Account Or)

Tipo de conta que comporta mais de um titular, tendo todos os titulares livre movimentação sem que seja exigida a autorização de outros titulares.

Conta de Depósito à Vista (Current Account)

Conhecida popularmente pelo nome de conta corrente. É a maneira mais comum de manter dinheiro em uma instituição financeira. Funciona como um cofre, em que o cliente deposita seu dinheiro e pode ter acesso a serviços como pagamento de contas, saques, transferências, emissão de cheques e realização de compras com cartão de débito, entre outros. Para guardar o dinheiro e oferecer serviços como os citados, a instituição financeira pode cobrar tarifas, mas o cliente é quem escolhe se prefere pagar uma tarifa individualizada por serviço que utilizar ou uma tarifa única que dá direito a um pacote de serviços.

Conta de Pagamento Pós-paga (Credit Card)

Referente a cartão de crédito. Instrumento de pagamento que possibilita a aquisição de produtos e serviços com liquidação futura, de acordo com requisitos predeterminados, tais como limite de crédito e validade. O pagamento do valor correspondente ao produto ou ao serviço adquirido será efetuado ao emissor do cartão de crédito em data previamente acordada.

Conta de Pagamento Pré-paga (Prepaid Payment Account)

Destinada à execução de transações de pagamento em moeda eletrônica realizadas com base em fundos denominados em reais previamente aportados.

Conta de Poupança (Savings Account)

A conta de depósitos de poupança, popularmente conhecida como conta poupança, conta de poupança ou ainda caderneta de poupança, é um tipo de investimento criado com o objetivo de estimular a economia popular. Assim, para abrir e manter uma conta de poupança, o cliente não paga tarifas, não paga imposto de renda sobre o dinheiro aplicado e ainda pode depositar pequenos valores, que passam a gerar rendimentos mensalmente. Se um valor depositado na conta de poupança não for mantido aplicado por pelo menos um mês, isto é, se for resgatado antes, não ocorrerá remuneração desse dinheiro.

Correspondente Bancário (Banking Agent)

Empresas, integrantes ou não do Sistema Financeiro Nacional, contratadas por instituições financeiras e demais instituições autorizadas a funcionar pelo Banco Central do Brasil para a prestação de serviços de atendimento aos clientes e usuários dessas instituições. Os correspondentes mais conhecidos são as lotéricas e o banco postal.

CPF - Cadastro de Pessoa Física (CPF Number)

O CPF é o Cadastro de Pessoa Física. Ele é um documento emitido pela Receita Federal e serve para identificar os contribuintes. O CPF é uma numeração com 11 dígitos, que só mudam por decisão judicial

Crédito (Credit)

É um termo geral, utilizado para nomear as diferentes maneiras com que bancos, financeiras e outras instituições emprestam dinheiro a seus clientes. Ou seja, quando essas instituições emprestam dinheiro para alguém ou financiam alguma compra de uma pessoa, elas estão concedendo um crédito. Exemplo de uso: Em uma operação de crédito, quem empresta o dinheiro é chamado credor, e quem toma o dinheiro emprestado é chamado devedor.

Fonte: link

Crédito Rotativo (Overdraft)

É um tipo de empréstimo que os bancos concedem para os clientes terem a possibilidade de não pagar, na data do vencimento, o valor total da fatura do cartão de crédito. Isto é, por causa do crédito rotativo, é possível que o cliente pague, no dia do vencimento, qualquer valor entre o pagamento mínimo e o total da fatura. A diferença entre o valor total que deveria ter sido pago e o valor que o cliente efetivamente pagou na data do vencimento é financiada pelo banco e será incluída, acrescida de juros, na fatura do mês seguinte. Quando o cliente não paga o total da fatura, é como se ele estivesse automaticamente pegando emprestado o valor que ele deixou de pagar.

Custo Efetivo Total (CET)

Custo Efetivo Total. Corresponde a todos os encargos e despesas incidentes nas operações de crédito e de arrendamento mercantil financeiro, contratadas ou ofertadas a pessoas físicas, microempresas ou empresas de pequeno porte. Deve ser informado pelas instituições financeiras e pelas sociedades de arrendamento mercantil antes da contratação de operações de crédito e de arrendamento mercantil e também em qualquer outro momento, a pedido do cliente. Também deve constar dos informes publicitários das instituições quando forem veiculadas ofertas específicas (com divulgação da taxa de juros cobrada, do valor das prestações, etc).

Fonte: Resolução 3.517, de 6/12/2007. link

Débito (Debit)

De uma forma geral, significa dívida. Exemplo de uso: Estou em débito com o Fernando, devo R$50 a ele. Ver também: crédito, credor, devedor, dívida.

Débito (no extrato) Em um extrato bancário, os débitos, marcados com a letra “D” ao lado do valor registrado, informam as saídas de dinheiro na conta-corrente. Exemplo de uso: Fiz uma compra com a função débito do cartão e apareceu o valor da compra, com um “D”, no extrato da minha conta, diminuindo o saldo.

Fonte: link

Débito Automático (Direct Debit)

Débitos autorizados pelo titular de conta de depósitos ou de conta de pagamento mantidas nas instituições mencionadas

Direito Creditório Descontado (Invoice Financing)

É o direito de receber dinheiro ou títulos, sejam eles oriundos de operações financeiras, comerciais, imobiliárias ou mesmo de ativos financeiros e investimentos. Esta opção abrange tanto pessoas físicas quanto entidades. Normalmente, ele “existe” na forma de um título.

Dependência (Branch)

Dependência de instituições financeiras e demais instituições, autorizadas a funcionar pelo Banco Central do Brasil, destinada à prática das atividades para as quais a instituição esteja regularmente habilitada. (Agência é a dependência destinada ao atendimento aos clientes e ao público em geral no exercício de atividades da instituição, não podendo ser móvel ou transitória)

Empréstimo (Loan)

É o mecanismo utilizado para ter disponível, no presente, uma quantia que só se conseguiria alcançar no futuro, fazendo poupança. O valor emprestado, mais os juros e encargos cobrados pela instituição financeira, vira uma dívida, que deverá ser paga na forma e no prazo combinados (valor e quantidade de parcelas, por exemplo). No empréstimo, o valor emprestado não tem destinação específica, isto é, a pessoa pode utilizar o dinheiro que pegou emprestado onde e como quiser.

Empréstimo Cartão Consignado (Payroll Loan)

É um tipo de operação de crédito contratada no Cartão de Crédito, na qual o pagamento das compras do titular são descontadas diretamente em folha ou benefício do INSS

Encargo (Charge)

As instituições financeiras e as sociedades de arrendamento mercantil podem cobrar de seus clientes, no caso de atraso no pagamento ou na liquidação de obrigações, exclusivamente os seguintes encargos: I - juros remuneratórios, por dia de atraso, sobre a parcela vencida; II - multa, nos termos da legislação em vigor; e III - juros de mora, nos termos da legislação em vigor.

Fonte: link

Ente Consignante (CnpjConsignee)

É a empresa pública ou privada que mantém convênio com entidades Consignatárias afim de descontar no contracheque de seus funcionários os valores mensais referente as operações financeiras contratadas pelos mesmos obedecendo a regra da margem consignável.

Os entes consignantes podem ser :

• Privado - Destinado a funcionários de empresas do setor privado
• Público - (prefeituras, estados, órgãos) - Destinado a servidores públicos federais, estaduais ou municipais
• INSS - Destinado a beneficiários (aposentados e / ou pensionistas) do INSS.

Fatura (Bill)

Fatura é o documento através do qual o emissor realiza a prestação de contas ao portador titular. Nos meses em que ocorrer movimentação, o emissor do cartão de crédito enviará a Fatura discriminando as respectivas transações do período.

Financiamento (Financing)

Parcelamento. Compra parcelada. Compra a prazo. É um crédito que a pessoa obtém para comprar um bem, como uma casa, um carro, um eletrodoméstico. O pagamento do bem é feito de forma parcelada por meio de carnês, boletos de cobrança, débitos em conta corrente, cartão de crédito, cheques etc. O financiamento pode incluir custos como juros, tarifas, impostos, entre outros encargos.

Garantia (Warranty)

Ativo que é entregue pelo outorgante da garantia para assegurar uma obrigação à parte que toma a garantia. Os acordos de garantia podem tomar diversas formas legais; as garantias podem ser obtidas por transferência de títulos ou penhora.

Fonte: link

Identificação (Identification)

Agrupador das informações relativas a Identificação ou seja a ação e o efeito de identificar de forma única a pessoa através de seus dados cadastrais

Identificador Padronizado da Operação de Crédito – Ipoc Code

O identificador padronizado da operação de crédito é atribuído a todas as operações de crédito informadas ao SCR (Sistema de Informações de Crédito do Banco Central do Brasil – SCR é um instrumento de registro e consulta de informações sobre as operações de crédito, como empréstimos, financiamentos, avais ou fianças, realizadas entre as Instituições Financeiras e seus Clientes).

O IPOC será formado pela concatenação das informações contidas nos campos do SCR abaixo discriminados, respeitando-se a seguinte ordem:

1. CNPJ da instituição
2. Modalidade da operação
3. Tipo do cliente
4. Código do cliente
5. Código do contrato

Fonte: link

Indexador (Indexer)

É o termo utilizado para se referir aos índices usados como base para corrigir os valores monetários de um determinado ativo. Os índices mais utilizados são IPCA, INPC, IGP-M, CDI, Taxa Selic.

Instituição Financeira (Company)

Instituições que prestam serviços financeiros e são autorizadas a funcionar pelo Banco Central do Brasil.

Limite Flexível (Flexible Limit)

Geralmente esses cartões não possuem limite oculto inferior a R$ 50 mil, ou seja, é o mesmo que sem limite pré-estabelecido de despesas. Pois são voltados para consumidores de alto poder aquisitivo, sendo considerado um cartão de crédito diferenciado, pois permite ao portador comprar o que quiser.

Marca (Brand)

A marca é em essência uma promessa da empresa em fornecer uma série específica de atributos, benefícios e serviços uniformes aos clientes.

MCC (Merchant Category Code)

O MCC ou o código da categoria do estabelecimento comercial. Os MCCs são agrupados segundo suas similaridades. O MCC é usado para classificar o negócio pelo tipo fornecido de bens ou serviços. Os MCCs são atribuídos por tipo de comerciante (por exemplo, um para hotéis, um para lojas de materiais de escritório, etc.) ou por nome de comerciante (por exemplo, 3000 para a United Airlines).

Mês de Referência (Reference Month)

O mês de referência será tratado como “M-1”.

Nome Civil Completo (Civil Name)

Nome civil completo da pessoa natural é aquele atribuído à pessoa natural desde o registro de seu nascimento, com o qual será identificada por toda a sua vida, bem como após a sua morte. Trata-se de um Direito fundamental da pessoa natural

Nome Social (Social Name)

O nome social é definido como a adoção/ adequação do senso de identificação do sujeito referenciando o nome que o representa (Decreto Nº 51.180, de 14 de janeiro de 2010), evitando a exposição desnecessária do indivíduo, o constrangimento de ser tratado de uma forma que não condiz com sua condição humana, psicológica, moral, intelectual, emocional e que não o representa. Tem por objetivo o reconhecimento social e individual segundo o Art. 16 do Código Civil, toda pessoa tem direito ao nome, nele compreendidos o prenome e o sobrenome.

Pacote de Serviços (Service Bundles)

Cesta de serviços. É uma combinação de diferentes quantidades de serviços bancários (saques, extratos, transferências, cheques e outros) que o cliente pode usar por mês. Antes da contratação de um pacote de serviços, é importante verificar quais os serviços que são efetivamente usados ao longo do mês e se o custo desses serviços, cobrados isoladamente, não é menor que o do pacote de serviços.

Pagador (Payer)

É a pessoa ou a empresa que deve pagar o valor cobrado em um boleto bancário, normalmente por ter feito uma compra, um financiamento ou por estar pagando por um serviço, como uma mensalidade escolar, por exemplo. O banco recebe o pagamento feito pelo sacado e transfere o valor pago para a conta do beneficiário. No boleto, o campo “pagador” costuma trazer outras informações além do nome do pagador, como o seu endereço. Exemplo de uso: Ao receber um boleto para pagar, a pessoa deve sempre conferir se seus dados estão corretos no campo “pagador”. Se houver algum erro, ela deve procurar o banco que emitiu o boleto

Fonte: link

Pagamento Autorizado (Authorised Payment)

São transações a crédito ou débito que ainda não foram registradas no extrato, mas que a instituição possui autorização do cliente para realizar o débito.

Fonte: link

Posto de Atendimento Bancário - PAB (Branch)

São as dependências de bancos múltiplos com carteira comercial, instaladas em recinto interno de entidade da administração pública ou de empresa privada e destinadas a prestar todos os serviços para os quais a instituição esteja regularmente habilitada de exclusivo interesse do respectivo governo e de seus funcionários, quando instalados em entidade de administração pública, ou da respectiva empresa, de seus empregados e administradores, quando instalados em dependências de empresa privada.

Posto de Atendimento Eletrônico – PAE (Branch)

O Posto de Atendimento Bancário Eletrônico, Fixo ou Móvel (PAE), é uma extensão automatizada de dependências bancárias, que pode funcionar até 24 (vinte e quatro) horas por dia, ligada à central de controle e processamento.

Prestação Regular (Instalment)

Refere-se a comprar um produto ou serviço de forma parcelada e assim dividir o pagamento em partes, em prestações a serem pagas ao longo de um período de tempo em intervalos regulares, p.ex. parcelas mensais, onde o vencimento acontecerá regularmente todo dia 10 de cada mês

Procurador (Procurator)

Pessoa autorizada por procuração para dirigir os negócios de outrem ou agir como seu agente, representante, substituto ou advogado.

Qualificação (Qualification)

Considera-se qualificação as informações que permitam as instituições apreciar, avaliar, caracterizar e classificar o cliente com a finalidade de conhecer o seu perfil de risco e sua capacidade econômico-financeira

Razão Social (Company Name)

A razão social é o nome de registro de uma empresa junto aos órgãos do governo e cartório e é o que vai constar em contratos, escrituras, documentos legais, notas fiscais etc. Ela é criada junto com o CNPJ e também é chamada de Denominação social – exatamente por ser, na prática, o nome da pessoa jurídica

Recebedor (Payee)

Pessoa natural ou jurídica, destinatário final dos recursos de uma transação de pagamento

Fonte: link

Relacionamento (Financial Relation)

Considera-se relacionamento as informações que permitam conhecer desde quando a pessoa consultada é cliente da instituição, bem como um indicador dos produtos e serviços que ela consome atualmente e seus representantes

Representante Legal (Legal Representative)

Nome Civil completo da Pessoa Natural que represente uma entidade ou uma empresa e é nomeado em seu ato constitutivo, ou seja, no contrato social ou estatuto social

Saldo (Account Balance)

Quantia que representa o excedente do total de créditos e do total de débitos de uma conta.

Saldo Bloqueado (Cash Blocked)

É um valor que o banco informa estar separado na conta-corrente para o pagamento, ao fim do dia, de alguma obrigação que tem vencimento naquele dia.

Exemplo de uso:

• Se o saldo da minha conta é de R$1.000, mas eu vejo que tem um saldo provisionado de R$400, isso quer dizer que só posso movimentar R$600, se não quiser entrar no vermelho.
• Valor depositado na conta que se encontra bloqueado para utilização, como bloqueios judiciais.

Fonte: link

Saldo Devedor (Outstanding Balance)

Corresponde ao valor que falta ser pago de uma dívida. Ao longo do tempo, os juros fazem o saldo devedor crescer, enquanto as amortizações pagas pelo devedor fazem o saldo devedor diminuir. O saldo devedor pode vir tanto de um empréstimo ou financiamento quanto de um pagamento inferior ao valor total de uma fatura de cartão de crédito. Ou ainda, em conta-corrente, o que significa que o cliente está “no vermelho” ou “no negativo”, isto é, entrou no limite de crédito do cheque especial ou utilizou o adiantamento a depositantes.

Saldo Disponível (Cash Amount)

É o valor total à disposição do cliente em sua conta-corrente, que inclui tanto o dinheiro que ele tem depositado nela quanto o limite de cheque especial pré-aprovado pelo banco. 43 Exemplo de uso: Ao consultar o extrato bancário, para saber quanto dinheiro seu de fato tem depositado em conta, o cliente não pode considerar o saldo disponível.

Fonte: link

Sexo (Sex)

“Conjunto de características anatomofisiológicas que distinguem o homem e a mulher: Sexo masculino; sexo feminino”. No caso de não ser feminino nem masculino é classificado como outros.

Sistema de Amortização Constante (SAC)

É aquele em que o valor da amortização permanece igual até o final. Os juros cobrados sobre o parcelamento não entram nesta conta.

Sistema de Amortização Misto (SAM)

Cada prestação (pagamento) é a média aritmética das prestações respectivas no Sistemas Price e no Sistema de Amortização Constante (SAC)

Sistema Francês de Amortização (Price)

As parcelas são fixas do início ao fim do contrato. Ou seja, todas as parcelas terão o mesmo valor, desde a primeira até a última. Nos primeiros pagamentos, a maior parte do valor da prestação corresponde aos juros. Ao longo do tempo, a taxa de juros vai decrescendo. Como o valor da prestação é fixo, com o passar das parcelas, o valor de amortização vai aumentando.

Tarifa (Fee)

A Resolução 3.919, de 25/11/2010, classifica em quatro modalidades os tipos de serviços prestados às pessoas físicas:

1. serviços essenciais – não podem ser cobrados;
2. serviços prioritários – relacionados a contas de depósitos, transferências de recursos, operações de crédito e de arrendamento mercantil, cartão de crédito básico e cadastro, somente podendo ser cobrados os serviços constantes da Lista de Serviços da Tabela I anexa à (Resolução CMN 3.919, de 2010, devendo ainda ser observados a padronização, as siglas e os fatos geradores da cobrança, também estabelecidos por meio da citada Tabela I;
3. serviços especiais – legislação e regulamentação específicas definem as tarifas e as condições em que são aplicáveis, a exemplo dos serviços referentes ao crédito rural, ao Sistema Financeiro da Habitação (SFH), ao Fundo de Garantia do Tempo de Serviço (FGTS), ao Fundo PIS/PASEP, às chamadas contas-salário, e às operações de microcrédito de que trata a Resolução 4.000, de 2011;
4. serviços diferenciados – podem ser cobrados desde que explicitadas ao cliente ou ao usuário as condições de utilização e de pagamento

Fonte: link

Taxa Efetiva (EffectiveTax)

É a taxa de juros em que a unidade referencial coincide com a unidade de tempo da capitalização. Como as unidades de medida de tempo da taxa de juros e dos períodos de capitalização são iguais, usa-se exemplos simples como 1% ao mês, 60% ao ano.

Taxa nominal (NominalTax)

É uma taxa de juros em que a unidade referencial não coincide com a unidade de tempo da capitalização. Ela é sempre fornecida em termos anuais, e seus períodos de capitalização podem ser diários, mensais, trimestrais ou semestrais.

Taxa Referencial – TR (Referential Rate)

É a taxa de juros de referência. É uma taxa calculada pelo Banco Central do Brasil e utilizada para determinar o rendimento de investimentos, como a caderneta de poupança e a correção de financiamentos imobiliários.

Terminais de Autoatendimento Compartilhados (Shared Automatic Teller Machine)

É o compartilhamento dos terminais de autoatendimento (ATM - dispositivo eletromecânico que permite aos usuários, geralmente usando cartões de plástico legíveis em máquina, a realização de um ou mais tipos de operações, tais como saques, depósitos, emissão de extratos e saldos, realização de pagamentos de contas e títulos, transferência de fundos e outro) para aumentar a eficiência do sistema de pagamento de varejo.

Transação Agendada (Scheduled Payment)

O usuário poderá agendar uma transação de DOC, TED, PIX ou boleto bancário para uma determinada data futura

Fontes: link 1 e link 2

Transações Realizadas (Completed Transaction)

Operações segmentadas efetuadas por tipo de acesso físico (agências e postos tradicionais, caixas de autoatendimento e correspondentes bancários) ou remoto (home e office banking, call centers, smartphones e PDAs) e por tipo de transações( Bloqueto de cobrança e convênios, depósitos, ordem de transferência de crédito, empréstimos e financiamentos, saques, outras transações financeiras, consultas a extratos e saldos e outras transações não financeiras)

Fontes: link 1 e link 2

Unidade Administrativa Desmembrada (UAD) - (Branch)

É a dependência destinada à execução de atividades administrativas da instituição, tal como atividades contábeis e administrativas de natureza interna, desde que tal unidade esteja instalada no mesmo Município da sede do grupo financeiro, ou de uma agência da instituição e é vedado o atendimento ao público.

Segurança

Introdução - Segurança

Esta seção tem como finalidade auxiliar na auto avaliação aos cumprimentos dos requisitos de segurança da informação relacionados a autorização e autenticação de APIs e End-Users, emissão de certificados digitais e requisitos para o onboarding no Diretório de participantes para as Instituições participantes do Open Banking.

As instituições participantes do Open Banking possuem a obrigação de acompanhar a edição e a revogação de eventuais normas com impacto no tema de forma a estar permanentemente em dia com as determinações legais. Compõem, de forma não exaustiva, o rol de atos normativos cuja observância é essencial pelas instituições participantes do Open Banking:

Estas especificações baseiam-se, referenciam, e complementam, quando aplicável, os seguintes documentos:

Além desse guia, foi elaborado um checklist para auxiliar os participantes do Open Banking a alcançar um nível adequado de Segurança da Informação, esse checklist pode ser baixado em formato Word ou Excel a seguir.

Download Autoavaliação dos requisitos de SI - 1.0.docx
Download Autoavaliação dos requisitos de SI - 1.0.xlsx

Visão geral

As APIs de Open Banking estão dividas em dois escopos:

• open-data
• customer-data

Segue, a continuação, um overview das camadas de segurança básicas para atender os contextos Open-data:

Dynamic Client Registration

O Dynamic Client Registration é mandatório para os participantes do Open Banking.

Os detalhes das especificações devem ser consultadas no endereço https://openbanking-brasil.github.io/specs-seguranca/open-banking-brasil-dynamic-client-registration-1_ID1.html (em inglês).

FAPI Security Profile 1.0

Financial-grade API, o FAPI, é uma especificação técnica desenvolvida pelo Grupo de Trabalho Financial-grade API da OpenID Foundation.

Ele utiliza OAuth 2.0 e OpenID Connect (OIDC) como sua base e define requisitos técnicos adicionais para o setor financeiro e outros setores que exigem maior segurança.

Os detalhes das especificações devem ser consultadas no endereço https://openbanking-brasil.github.io/specs-seguranca/open-banking-brasil-financial-api-1_ID1.html (em inglês).

[Em Revisão] Perfil de Segurança

Sobre os padrões de perfil de segurança de API.

É necessário que os participantes do Open Banking adotem padrões de autenticação e autorização para as APIs e End-Users, utilizando frameworks e mecanismos aprovados pelo mercado, garantindo assim, a integridade, a confidencialidade e a disponibilidade dos dados.

Conjunto de referências normativas adotadas pelo Open Banking:

Para melhor entendimento do FAPI-Read and Write API Profile e do CIBA-Financial-grade API: Client Initiated Backchannel Authentication Profile, é preciso ter conhecimento sobre OAuth2 e OpenID Connect.

OAuth 2.0

OAuth 2.0 é um framework de autorização que habilita um aplicativo a obter acesso limitado para um serviço de terceiro, introduzindo uma camada de autorização e segmentando as funções do client. Ao invés de utilizar credenciais fornecidas pelo proprietário do recurso, o client recebe um Access Token, contendo o escopo do acesso, tempo de vida, entre outros atributos. Os Access Tokens são emitidos para clients terceiros por um servidor de autorização com a aprovação do proprietário do recurso.

O OAuth 2.0, define 4 papéis.

• End-User: Uma entidade capaz de conceder acesso a recursos protegidos. Quando o proprietário do recurso é um usuário, ele provê o nível de acesso, limitando o escopo de autorização (leitura ou escrita).
  
• Resource Server: Servidor que hospeda os recursos protegidos, capaz de aceitar e responder a solicitações de recursos protegidos utilizando tokens de acesso.
• Client: Um aplicativo que faz solicitações a recursos protegidos em nome do proprietário do recurso, com a sua autorização.
• Authorization Server: É o servidor que emite tokens de acesso ao client, após autenticar com sucesso e obter autorização do End-User.

Tokens

O OAuth 2.0 faz o uso de diversos tokens, entre eles, o access token, refresh token e Authorization "code".

• Access token: Um token de acesso é utilizado por um client para acessar um recurso, geralmente possuem ciclo de vida curto (minutos ou horas), sendo consumidos durante uma sessão. O Access token indica que o client está autorizado a consumir um recurso protegido, respeitando os scopes para qual o token foi emitido. O token pode ser renovado através de um refresh token. O tipo de Access Token será o "Bearer" OAuth Access Token, referenciado em [RFC 6750].
• Refresh token: Representa uma autorização de longa duração de um client. Esses tokens são trocados entre o client e o Authorization Server e são utilizados para obter (“atualizar”) novos tokens de acesso.
• Authorization code: É um código de autorização que representa o resultado do processo de autorização bem sucedido do usuário final e é utilizado pelo client para obter acesso e atualizar status dos tokens.

É necessário a implementação de um endpoint adicional no Authorization Server que possibilita a revogação do Access Token e do Refresh Token. Um request de revogação invalidará um ou mais Tokens (se aplicável), baseados na mesma concessão de acesso, conforme [RFC 7009].
Também será adotado o OAuth Token Introspection que define um método para um recurso protegido consultar um Authorization Server sobre o estado e os metadados de um Token, conforme [RFC 7662].
Devido a ampla aplicação do uso do OAuth 2.0, as melhores práticas de segurança do OAuth 2.0 estão em constate atualização e podem ser consultadas neste endereço https://tools.ietf.org/html/draft-ietf-oauth-security-topics-16.

Início do fluxo de uma API com a obtenção de um Access Token.

Diagrama – Obtendo um Access Token.

1. Estabelece conexão TLS 1.2 entre o usuário e o client.
2. Estabelece conexão mTLS 1.2 entre o client e o Authorization Server.
3. Efetua um POST com as credenciais de autenticação do client e o escopo da solicitação.
4. Valida a autenticação de credenciais do client, o escopo e o certificado SSL.
5. Devolve o Access Token com a mensagem HTTP 200 (OK).
6. Estabelece conexão mTLS 1.2 entre o Client e o Resource Server.
7. Efetua um POST com o Access Token e o escopo.
8. Valida o Access Token, o escopo e o certificado.
9. Resposta com a mensagem HTTP 201 com o ID da transação.
10. Início do Hybrid Flow.

[Em Revisão] OpenID Connect (OIDC)

O OpenID Connect é uma camada de identidade sobre o protocolo OAuth 2.0, que permite a identificação de um usuário final com base na autenticação realizada por um Authorization Server. OpenID Connect permite uma grande variedade de tipos de clients, sendo, clients Web, clients móveis e JavaScript, oferecendo suporte a recursos opcionais, como criptografia de dados de identidade, descoberta de provedores de OpenID e gerenciamento de sessão.
Existem três papéis envolvendo uma solução de OIDC:

• End-User: É o sujeito a ser autenticado.
  
• OpenID Provider - OP: O provedor OpenID é um servidor de autorização OAuth 2.0 que implementa OIDC e pode autenticar um usuário e retornar claims sobre o usuário autenticado e o evento de autenticação para uma parte confiável, geralmente um aplicativo.
• Relying Party – RP: Um client OAuth 2.0 que delega a autenticação de usuários para um provedor de OpenID e solicita claims sobre o usuário do provedor OpenID, geralmente denominado, client.

ID Token

O OIDC utiliza o authorization code, access token e refresh token descrito na seção anterior sobre OAuth e define um outro tipo de Token, o ID Token.

• ID Token: Um token utilizado para transmitir claims sobre um evento de autenticação e um usuário autenticado (End-user) para um client. Tokens de identificação são codificados em JSON Web Token (JWT) e deve estar em conformidade com a LGPD.

{"iss": "http://YOUR_DOMAIN/",
"sub": "xpto|123456",
"aud": "YOUR_CLIENT_ID",
"exp": "1311281970",
"iat": "1311280970",
"id": "1234567"}

UserInfo Endpoint: Retorna claims sobre um usuário autenticado. Chamar o endpoint requer um Access Token e as claims retornadas são regidos pelo Access Token.
Exemplo de resposta bem-sucedida contendo um ID Token assinado:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{"access_token": "SlAV32hkKG",
"token_type": "Bearer",
"refresh_token": "8xLOxBtZp8",
"expires_in": "3600",
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc
yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5
NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ
fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz
AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q
Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ
NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd
QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS
K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4
XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg"}

[Em Revisão] JWT

O formato JWT (JSON Web Token) é projetado para transmitir claims entre duas partes. O JWT consiste em um Header, um payload e uma assinatura. O cabeçalho do ID Token contém informações sobre o tipo de objeto (JWT) e o algoritmo de assinatura utilizado para proteger a integridade dos claims do payload. O algoritmo de assinatura exigido é o PS256 (RSASSA-PSS utilizando SHA-256 e MGF1 com SHA-256). A seção do payload contém as claims sobre um usuário e o evento de autenticação. A seção de assinatura contém uma assinatura digital com base no payload do ID Token e uma chave secreta conhecida pelo provedor OpenID.

O JWT é formado por três seções: Header, Payload e Signature.
O Header contém somente a informação tipo e algoritmo:

{"typ": "JWT",
"alg": " PS256"}

Payload

O Payload é um objeto JSON com as Claims da entidade tratada, normalmente o usuário autenticado.
Claims são informações afirmadas sobre um sujeito, por exemplo um ID Token, pode conter uma claim chamada name que afirma que o usuário autenticado é quem diz ser. Em um JWT uma claim aparece como um par nome/valor em que o nome é sempre uma string e o valor pode conter qualquer conteúdo JSON. Essas claims podem ser de 3 tipos:

Reserved claims: São claims definidas pela especificação do JWT e contém atributos não obrigatórios (mais recomendados) que são usados na validação do token pelos protocolos de segurança das APIs. É possível verificar a lista completa de Reserved Claims em [IANA JSON Web Token Claims Registry].

{"sub": "Subject, entidade à quem o token pertence, normalmente o ID do usuário",
"iss": "Issuer, emissor do token",
"exp": "Expiration, timestamp de quando o token irá expirar",
"iat": "Issued at, timestamp de quando o token foi criado",
"aud": "Audience, destinatário do token, representa a aplicação que irá usá-lo"}

Public claims: atributos utilizados nas aplicações. Normalmente armazenamos as informações do usuário autenticado na aplicação.

{"name": "Joe",
"roles": "Administrator",
"permissions": "Full"}

Private claims: são claims personalizadas e contém atributos definidos para compartilhar informações entre aplicações.

{"sub": "1234567890",
"name": "Jose Doe"
"admin": "true"}

Conjunto de claims para um ID Token do Open Banking:

{"iss": "Emissor do token",
"sub": "Identificador único do subject",
"openbanking_intent_id": "Intent ID da solicitação",
"aud": "Público alvo para o qual o ID Token é destinado (deve incluir o Client ID)",
"exp": "Data/hora de expiração do token",
"iat": "Data/hora de emissão do token",
"auth_time": "Data/hora de autenticação do End-user",
"nonce": "Valor string que associa uma sessão do cliente com um ID Token usado para ajudar na mitigação de ataques de replay",
"acr": "Authentication Context Class Reference",
"amr": "Authentication Methods References",
"azp": "Authorized party",
"s_hash": "State hash value",
"at_hash": "Access Token hash value",
"c_hash": "Code hash value"}

Assinatura

A assinatura é o header e o payload criptografados com um secret.

PS256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
secret)

Para obter o token JWT, as três seções header (vermelho), payload (roxo) e signature (azul) são codificadas com Base64-URL e unidas por pontos.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJz
dWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4g
RG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSM
eKKF2QT4fwpMeJf36POk6yJV_adQssw5c

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9. -> Header
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ. -> Payload
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c -> Signature

Este token JWT deve ser enviado no cabeçalho Authentication HTTP usando o esquema Bearer. O conteúdo do cabeçalho deve seguir este formato:

Authorization: Bearer

[Em Revisão] Fluxo OpenID Connect (OIDC)

O OpenID Connect define os seguintes fluxos:

• Authorization Code Flow: Para autenticar um usuário, o client redireciona o usuário para um provedor de OpenID. O provedor OpenID autentica o usuário e redireciona o usuário de volta para o client com um código de autorização. O aplicativo usa o código de autorização para obter um ID Token, Access Token e, opcionalmente, um Refresh Token do endpoint do provedor OpenID.
• Implicit flow: Todos os tokens são retornados pelo endpoint de autorização, o Endpoint de Token não é utilizado, esse tipo de fluxo é usado principalmente por Clients implementados em um navegador utilizando uma linguagem de script. O Access Token e o ID Token são devolvidos diretamente ao Client, que pode expô-los ao usuário final e aos aplicativos que têm acesso
• Hybrid flow: O Hybrid Flow, combina elementos do Authorization Code Flow e Implicit Flow, esse modelo permite retornar um ID Token e um Authorization Code como uma resposta ao front-end do client, deixando o backend obter um Access Token e opcionalmente um Refresh Token do endpoint de token utilizando o Authorization Code. Esse padrão de autenticação foi escolhido como mandatório pelo Open Banking e pode ser observado no diagrama a seguir.

Diagrama - Fluxo Hybrid Flow

1. Usuário acessa o aplicativo e faz requisições ao Client.
2. Client redireciona a requisição de autenticação ao Authorization Server.
3. O Authorization Server interage com o usuário com a requisição de autenticação e o consentimento sobre o escopo.
4. Usuário efetua a autenticação e provê o consentimento, o Authorization Server cria ou atualiza uma sessão para o usuário.
5. Authorization Server direciona o End-User de volta ao client com um código de autorização e, dependendo do tipo da resposta, com parâmetros adicionais.
6. O Client solicita uma resposta ao Authorization Server com o código de autorização para obter os demais tokens.
7. O Authorization Server responde com o ID Token e um Access Token.
8. O Client valida o ID Token e busca o Subject Identifier do End-User. O Authorization Server deve suportar request objects conforme especificado na seção 6.1 (Request Object) do OIDC.

   [Em Revisão] Financial-Grade API (FAPI)

   Financial-grade API, o FAPI, é uma especificação técnica desenvolvida pelo Grupo de Trabalho Financial-grade API da OpenID Foundation. Ele utiliza OAuth 2.0 e OpenID Connect (OIDC) como sua base e define requisitos técnicos adicionais para o setor financeiro e outros setores que exigem maior segurança.

FAPI: Read and Write API Security Profile

É obrigatório o uso do perfil de segurança FAPI-Financial-grade API: Read and Write API Security Profile, referenciado no endereço: https://openid.net/specs/openid-financial-api-part-2-wd-06.html.

FAPI: CIBA-Client Initiated Backchannel Authentication Profile

A autenticação pelo CIBA fornece um fluxo desacoplado, possibilitando autorizar um pagamento por exemplo em um terminal de ponto de venda ou em um posto de combustível. O perfil de segurança CIBA: Client Initiated Backchannel Authentication Profle será opcional pelos participantes do Open Banking, referenciado no endereço: https://openid.net/specs/openid-financial-api-ciba.html.

[Em Revisão] Fluxos de Autenticação e Autorização

Um Autorizador deve usar o protocolo OpenID Connect (OIDC) e o OAuth 2.0 Authorization Framework para autenticar usuários e obter sua autorização para acessar recursos protegidos.
A autenticação e a autorização representam funções fundamentalmente diferentes, conforme comparativo abaixo:

Camada de transporte

A comunicação entre os aplicativos terceiros e os recursos protegidos, devem ser sempre protegidas utilizando uma conexão TLS versão 1.2 ou superior. A conexão TLS deve ser estabelecida sempre utilizando o certificado qualificado para a autenticação do site e o certificado deve ser emitido seguindo as normas definidas para o Open Banking.

Fluxo client credentials

Com aplicativos machine-to-machine (M2M), como serviços em execução no back-end, o sistema autentica e autoriza o Client em vez de um usuário. Para este cenário, esquemas de autenticação típicos como nome de usuário + senha ou logins sociais não fazem sentido.

Em vez disso, as aplicações M2M usam o fluxo Client Credentials utilizando mTLS (definido em OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound RFC 8705) e infraestrutura de chave pública (PKI). No qual o Client, o Authorization Server e o Servidor API são autenticados usando certificados X.509. O Access Token também é vinculado ao Client e validado utilizando certificados X.509.

Este método acrescenta uma restrição com chave de confirmação (ou prova de posse) ao Client que deseja utilizar um token emitido, com isso ele mitiga a possibilidade de uso abusivo dos Access Tokens Oauth tradicionais em caso de vazamento.

Diagrama – Fluxo de credenciais do client.

1. O client e o servidor de autenticação estabelecem uma conexão mTLS, e o Client solicita um Access Token.
2. O Servidor de Autenticação gera uma impressão digital SHA-256 do certificado do Client e a incorpora em um Access Token JWT. Isto limita o Access Token ao Client.
3. O servidor de autenticação emite o Access Token como uma resposta ao Client.
4. Os Clients fazem uma solicitação de recursos ao Servidor API usando o Access Token.
5. O Servidor de API solicita ao Authorization Server que valide o Access Token.
6. O Servidor API usa a impressão digital embutida para validar o Access Token.
7. O Servidor de Autenticação retorna o resultado da validação do token.
8. O Servidor API responde com o recurso solicitado.

Conforme definido na Seção 6.1 do RFC8705, os endpoints utilizados para emissão e validação de tokens que requerem uma conexão mTLS são endpoints convencionais separados por hostname ou porta diferente.

Fluxo do Authorization Code

No Fluxo do Authorization Code, o Client pode recuperar um Access Token e, opcionalmente, um Refresh Token. É considerada a escolha mais segura, pois o Access Token é passado diretamente para o servidor que hospeda o Client, sem passar pelo navegador do usuário e correr o risco de exposição.

Como os Clients são aplicativos do lado do servidor em que o código-fonte não é exposto publicamente, eles podem usar o fluxo do Authorization Code (definido no OAuth 2.0 [RFC 6749], seção 4.1 ), que troca um Authorization Code por um token. Seu Client deve estar no lado do servidor, porque durante essa troca, você também deve passar adiante o client secret do seu Client, que deve ser mantido sempre seguro, e deve armazená-lo em seu client.

Diagrama - Fluxo do código de autorização.

1. O usuário clica em Login no Client.
2. O client redireciona o usuário para o Authorization Server.
3. O Authorization Server redireciona o usuário para o prompt de login e autorização.
4. O usuário se autentica usando uma das opções de login configuradas e verá uma página de consentimento listando as permissões que o Autorizador dará ao Client.
5. O Authorization Server redireciona o usuário de volta ao client com um Authorization Code, que é válido para um uso.
6. O client envia esse código para o Authorization Server junto com o Client ID e o client secret do Client.
7. O Authorization Server verifica o código, o Client ID e o client secret do client.
8. O Authorization Server responde com um ID Token e um Access Token (e, opcionalmente, um Refresh Token).
9. O Client usa o Access Token para chamar uma API para acessar informações sobre o usuário.
10. A API responde com os dados solicitados.

[Em Revisão] Fluxo de Consentimento

[EM REVISÃO/ALTERAÇÃO - ABRIL DE 2021]

O fluxo de consentimento consiste no processo em que o usuário permite que a aplicação da instituição receptora tenha acesso aos dados por ele definidos. Esse consentimento deve ser requisitado ao usuário, juntamente a instituição transmissora de dados, a fim de compartilhar apenas as informações requeridas pelo usuário. Para isso, foi definido que o Open Banking Brasil utilizaria-se do padrão de Lodging Intent. Após o fluxo de consentimento completo, a aplicação da instituição receptora pode ainda não ter acesso aos dados, por regras de negócio das instituições transmissoras. As próximas seções se dedicam a explicar este fluxo por completo.

Padrão Lodging Intent

Essa seção descreve o padrão Lodging Intent, utilizado para parametrizar solicitações de autorização OAuth complexas de maneira confiável e segura. O OAuth por si, suporta apenas autorizar ações simples de leitura, o parâmetro scope é definido por uma lista delimitada por espaços contendo strings simples, quando se trata de autorizações mais complexas, como o início de um pagamento, o suporte integrado do OAuth não é suficiente. O padrão Lodging Intent pode ser utilizado para passar informações de forma confiável para o processo de autorização, independente das restrições de comprimento de URL, enquanto as informações também são protegidas contra modificação sem a necessidade de assiná-las digitalmente, reduzindo os custos de implementação. Executar um processo de autorização utilizando o padrão Lodging Intent e o Code Flow, funciona da seguinte maneira:

• O client cria um recurso contendo todos os dados necessários para informar o processo de autorização no Authorization Server, a criação do Lodging Intent pode exigir uma autorização própria, nesse caso, o client precisa obter antecipadamente um Access Token com o escopo adequado, normalmente usando a concessão do Client Credentials com o* Authorization Server*.
• O serviço de Lodging Intent responde ao client com um id e/ou link para o recurso criado.
• O client então envia a referência do recurso com o pedido de autorização para o Authorization Server. O Authorization Server obtém os dados da transação do recurso de hospedagem e depois de autenticar o usuário, utiliza-os para apresentar uma interface de consentimento. Por exemplo, no caso de um pagamento, o Authorization Server mostra ao devedor, o valor e informações adicionais sobre a transação de pagamento ao usuário e pede o seu consentimento.
• Se o usuário consentir com a autorização solicitada, o Authorization Server associa os dados de autorização à concessão criada (ou atualizada) e os respectivos Access Tokens emitidos com base nessa concessão. Por último, o Authorization Server precisa fornecer os dados de autorização ao respectivo Resource Server, para que seja incorporado no Access Token ou na resposta de Introspection do Token.

Mais detalhes sobre o funcionamento do padrão Lodging Intent pode ser consultado em https://bitbucket.org/openid/fapi/src/master/Financial_API_Lodging_Intent.md .

Exemplo de fluxo de consentimento

1: Pedido de Token para o Consentimento

POST /token HTTP/1.1
Host: as.banco.exemplo
Content-Type: application/x-www-form-urlencoded

"..."
client_id=3630BF72-E979-477A-A8FF-8A338F07C852&
grant_type=client_credentials&
scope=consents
"..."

eyJraWQiOiJOQnlW...

2: Requisição para criar um consentimento

POST /consents/v1/consents HTTP/1.1
Host: api.banco.exemplo
Content-Type:  application/json
Authorization: Bearer eyJraWQiOiJOQnlW...

{
    "data": {
        "..."
        "permissions": [
            "ACCOUNTS_READ",
            "ACCOUNTS_BALANCES_READ",
            "ACCOUNTS_TRANSACTIONS_READ"
        ],
        "..."
    }
}

3: Retorno da criação do consentimento

HTTP/1.1 201 Created
Location: /consents/v1/consents/urn:bancoex:C1DD33123 HTTP/1.1
Content-Type: application/json

{
    "data": {
        "..."
        "consentId": "urn:bancoex:C1DD33123",
        "..."
}

4: Requisição com token JTW para o Acess Token

GET /authorise?request=objectjwtpookdsfpmcieq-p0ok... HTTP/1.1
Host: as.banco.exemplo
...

// conteudo de exemplo do JWT enviado
{
    "..."
    "scope": "openid resources accounts consent:urn:bancoex:C1DD33123",
    "..."
}

O consentimento dado pelo usuário define quais informações a aplicação da instituição receptora terá acesso, mas não possui a granularidade de quais unidades de produto estão disponíveis para acesso. Essa informação cabe exclusivamente a instituição transmissora de dados. O seguinte exemplo demonstra o escopo de informações que o consentimento garante (Exemplos de codigo ao lado):

1. O usuário deseja compartilhar as informações de suas contas pré-pagas. Após o fluxo do front-end, a aplicação do receptor deve pedir um token ao Authorisation Server com o scope "consents".

2. Com o token, deve-se fazer uma requisição para a API de Consents, utilizando este token no header.

3. Ao receber esta requisição, a API deve retornar o identificador do pedido de consentimento.

4. Com o ID do consentimento, agora deve-se requisitar o Access Token que irá permitir com que a aplicação da instituição receptora consiga acessar os dados das APIs, enviando a requisição para o Authorisation Server com um objeto JWT contendo este ID como um escopo dinâmico.

5. Ao receber esta ultima requisição, a instituição transmissora envia uma URL de redirecionamento, onde o usuário irá escolher, dentro do ambiente da própria instituição, quais unidades de recurso ele irá compartilhar, dado este Access token gerado pelo pedido de consentimento. Exemplo: Neste caso apresentado após o fluxo de consentimento, o usuário escolhe dentro do ambiente da instituição transmissora quais contas ele irá compartilhar. Assim a instituição transmissora poderia ter um controle deste tipo:

Assim que o usuário inserir quais itens ele irá compartilhar (neste exemplo, quais contas pré-pagas), o fluxo OAuth segue normalmente (redirecionamento do auth_code para a URL de callback e novo pedido de token ao Authorisation Server).

A tabela de scopes e permissions pode ser vista aqui.

Vale ressaltar que o consentimento, após dado do lado do app da instituição receptora, deve ser confirmado na instituição transmissora em até 60 minutos. Após este periodo, o pedido de consentimento expira.

Acesso aos dados após o consentimento

Ao colher o consentimento do usuário e obter o token, a aplicação da instituição receptora pode ainda não estar apta para acessar as informações contidas dentro do escopo das permissões enviadas no pedido de consentimento. Existem diversas questões que, por regra de negócio da instituição transmissora, podem fazer com que a aplicação da receptora não tenha acesso aos dados, como por exemplo uma autenticação de dupla alçada. Para isso, a aplicação receptora deve consultar a API de Resources.

O fluxo a seguir demonstra como deve ser uma consulta à API de Accounts, partindo do principio de que o App já tenha realizado todo o fluxo de Authorization Code, como descrito anteriormente, e portanto, já esteja de posse de um token de acesso válido. Vale lembrar que a API de Accounts é apenas um exemplo. Qualquer outra API de Data sharing segue o mesmo conceito.

1. App, em posse de um token válido, requisita a API de Resources a informação de quais recursos o token enviado tem acesso;
2. API de Resources devolve essa informação, juntamente com o status de cada recurso (Se está disponível, esperando autorização da outra alçada, etc);
3. Recebendo a resposta da API de Resources de que o recurso de Accounts está disponível, o App acessa a API de Accounts diretamente, utilizando o mesmo token;
4. Com os recursos disponíveis, a API de Accounts retorna os dados requeridos corretamente.

Alguns pontos devem ser destacados: * Caso a API de Resources mostre recursos indisponíveis por qualquer motivo, as APIs de Data sharing não vão retornar nenhum item em suas consultas; * O App da instituição receptora pode acessar diretamente as APIs de Data sharing, sem qualquer quebra do fluxo de acesso ao dado. Porém, recomenda-se o acesso à API de Resources para que se garanta uma conexão mais efetiva e assertiva; * Caso a API de Resources traga status de bloqueio temporário de recurso, o App da instituição receptora pode acabar realizando um pooling para verificar quando o recurso estará disponível, respeitando sempre os limites de tráfego dispostos na seção específica deste portal.

Revogação do Consentimento

Pedidos de revogação de consentimentos feitos pelo usuário final por meio de API´s da instituição receptora devem obrigatoriamente implicar na revogação dos tokens de acesso e de consentimento relacionados por meio de chamadas executadas no servidor de autorização da instituição transmissora responsável pelo consentimento e/ou em API de consentimento mantida pelo transmissor. A instituição transmissora deve disponibilizar, por meio de API específica para o controle de consentimentos, interface que permita à instituição receptora detentora de consentimentos a verificação do seu estado. O acesso à API de consentimento deve ser precedido de autenticação e a consulta deve ser restrita ao consentimento a que a instituição receptora teve autorização prévia para acesso, com vistas a garantir que apenas a instituição receptora que registrou o pedido de consentimento possa realizar a consulta sobre o seu estado. A instituição receptora de dados detentora de consentimentos e de tokens de autorização deve revogá-los, por meio de chamadas específicas às API´s das instituições transmissoras publicadas para esse fim, quando perceber violações à confidencialidade dos tokens ou no fim da prestação dos serviços ao usuário final.

De acordo com a Resolução Conjunta Nº 1, tanto a instituição receptora quanto a transmissora devem possuir interfaces onde um consentimento pode ser imediatamente revogado pelo usuário (Art. 15). A partir do momento em que o consentimento for revogado, seu token perde validade. Assim, ao tentar acessar qualquer recurso, a API consultada deve retornar o HTTP Status 401.

Atualização do Consentimento

Deve-se levar em conta, como definido no Manual do Usuário, que ao se atualizar um consentimento, se realiza a deleção do consentimento anterior, e cria-se um novo consentimento, que contemple as alterações feitas pelo usuário.

Casos de Erro

A convenção do Open Banking Brasil mapeou alguns erros esperados durante o fluxo do usuário no ecossistema. Existem orientações especificas já tratadas no Manual do Usuário. Aqui, trataremos a visão mais técnica do que pode ser feito em caso de erro.

• Durante o redirecionamento do Consentimento, não se encontrou o browser no dispositivo do usuário: Além da orientação ao usuário, deve-se perceber que o fluxo de Consentimento continua pendente. Como a intenção de consentimento segue válida por 60 minutos, deve-se tentar utilizar o mesmo consentimento para tentar novamente a autorização do usuário.
• Durante o redirecionamento do Consentimento, houve um problema inesperado no servidor do Transmissor (HTTP Code 4xx ou 5xx): Além da orientação ao usuário, deve-se perceber que o fluxo de Consentimento continua pendente. Como a intenção de consentimento segue válida por 60 minutos, deve-se tentar utilizar o mesmo consentimento para tentar novamente a autorização do usuário.
• Durante o redirecionamento do Consentimento, houve um problema inesperado no servidor do Transmissor (Timeout, queda de Internet, etc): Além da orientação do usuário, deve-se perceber que o fluxo de Consentimento continua pendente. Como a intenção de consentimento segue válida por 60 minutos, deve-se tentar utilizar o mesmo consentimento para tentar novamente a autorização do usuário.
• Durante o redirecionamento do Consentimento, houve um problema com o Login do usuário (erro de credenciais): Além da orientação ao usuário, deve-se perceber que o fluxo de Consentimento continua pendente. Como a intenção de consentimento segue válida por 60 minutos, deve-se tentar utilizar o mesmo consentimento para tentar novamente a autorização do usuário.
• Após o consentimento do lado do Receptor, o usuário não confirma o compartilhamento: Além da orientação ao usuário, deve-se perceber que o fluxo de Consentimento continua pendente. Como a intenção de consentimento segue válida por 60 minutos, deve-se tentar utilizar o mesmo consentimento para tentar novamente a autorização do usuário.
• Após o consentimento completo, o app do Receptor não consegue acessar os dados por indisponibilidade: Deve-se tentar novamente. Access Token ainda é válido, portanto deve-se tentar novamente sem maiores prejuízos técnicos.
• Após o consentimento completo, o app do Receptor não consegue acessar os dados por pendência de autorização de um terceiro (ex.: Dupla alçada): Deve-se consultar a API de Resources para verificar as pêndencias e saber como proceder.

Redirecionamento App-to-app

O redirecionamento 'App-to-App' permite que a Instituição Receptora redirecione um usuário do seu aplicativo (em um navegador ou app) para o App da Instituição Transmissora, instalado no dispositivo do usuário. Nesse caso, a receptora é capaz de transmitir detalhes de sua solicitação junto com as preferências do usuário (por exemplo, tipo de produto, one-step authentication, etc) e ligar diretamente o seu usuário à tela ou função de login do aplicativo da transmissora, através de um deep-link. O usuário é então autenticado no aplicativo usando as mesmas credenciais/métodos normalmente usados quando ele acessa diretamente sua conta. Isso não deve envolver nenhuma etapa adicional (como, por exemplo, ser redirecionado primeiro para uma página da web para selecionar qual aplicativo da instituição transmissora usar) e não deve exigir que o usuário forneça qualquer identificador ou outras credenciais diferentes das já exigidas pela Instituição Transmissora em seu App. Quando o usuário não tem o App da transmissora, eles devem experimentar um fluxo de redirecionamento que também não deve envolver etapas adicionais do que seria o caso quando ele autentica diretamente na transmissora (por exemplo, ser redirecionado para o site mobile da transmissora).

Como funciona o fluxo de redirecionamento

Ao usar um serviço baseado no padrão de APIs Open Banking Brasil para redirecionamento, o usuário será redirecionado duas vezes:

1. Da interface instituição receptora para a interface da transmissora (para autenticar e autorizar). O URI do servidor de autorização é especificado por cada transmissora em seu endpoint conhecido.

2. Na volta da interface da transmissora para a interface da receptora (para completar qualquer operação com a receptora). Este redirecionamento é especificado pela receptora como parte do primeiro redirecionamento.

Implementação de deep links

Uma jornada perfeita para o usuário, que ignora o navegador integrado (por exemplo, Safari) em seu dispositivo mobile, pode ser implementada para qualquer URL, ou seja, ambos: a) para o redirecionamento inicial para o qual a transmissora envia o usuário para os servidores da transmissora, E b) a URL de redirecionamento para o qual a transmissora envia o usuário de volta para a receptora após a autenticação/autorização.

Tanto transmissoras quanto receptoras devem seguir as orientações da Apple e do Google abaixo:

• iOS: https://developer.apple.com/ios/universal-links/ (cobre mais de 99% de todos os usuários iOS, que estão no iOS 9 ou superior).

• Android: https://developer.android.com/training/app-links/index.html (cobre 65% de todos os usuários do Android, que estão no Android 6.0 ou posterior).

No caso de um usuário não ter o aplicativo instalado em seu dispositivo, ou se ele tiver um sistema operacional mais antigo ou sem suporte (por exemplo, Windows Mobile), esses métodos permitirão que o usuário seja redirecionado para uma página web mobile.

[Em Revisão] Assinatura de Mensagens

A assinatura de mensagens deve ser aplicada a APIs específicas, de acordo com a definição na documentação do Endpoint.
Para a assinatura de mensagens, deve ser suportado o uso de um JWT assinado (JWS). JWS representa o conteúdo protegido com assinaturas digitais ou com Message Authentication Codes (MACs) utilizando estruturas de dados JSON, referenciado em [RFC 7515].

Estrutura de um token com JWS.

[Em Revisão] Certificados

Dois tipos de certificados serão emitidos pelo ICP-Brasil para serem utilizados no Open Banking com as funções de transporte e assinatura. Atributos comuns a ambos os certificados:

Transporte

Certificado de transporte para a proteção e autenticação do canal (mTLS) e será utilizado para criptografar requisições e respostas entre Third Parties e bancos. Atributos específicos do certificado de transporte:

Assinatura

O certificado de assinatura de mensagens é utilizado para criar o JWS para assinar o payload JWT durante o processo de onboarding e authorization. Atributos específicos do certificado de assinatura:

Algoritmo de criptorgrafia

Tipos de certificados

Requisitos adicionais

• Protocolo HTTP versão 1.1.
• Criptografia TLS versão 1.2 suportando somente as seguintes cifras:
  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
• Autenticação mútua.
• Algoritmo ECDSA.
• Algoritmo de troca de chaves de curva elíptica ECDHE.
• Criptografia simétrica AES com chave de 128 bits
• MAC com SHA de chaves de 256 bits.

Definições

A ICP-Brasil (Infraestrutura de Chaves Públicas Brasileira) consiste em uma cadeia hierárquica composta por uma autoridade gestora de políticas e autoridades certificadoras que utilizam um conjunto de tecnologias, práticas, técnicas e procedimentos para realizar a transação de documentos eletrônicos com segurança. O objetivo da ICP é fazer com que a utilização de criptografia de chaves públicas se torne mais fácil, tendo como principais componentes as autoridades certificadoras, autoridades de registro e o repositório. Sua hierarquia se dá da seguinte forma:

• 1º. Comitê Gestor (CG);
• 2º. Autoridade Certificadora (AC Raiz);
• 3º. Autoridades Certificadoras de 1º e 2º nível (ACs);
• 4º. Autoridades de Registros (ARs);
• 5º. usuário final.

A validação requer um par de chaves, sendo que uma delas é de conhecimento geral, ou seja, de acesso ao público, e a outra de conhecimento apenas do proprietário. Por isso, seus dados precisam estar contidos em um certificado digital para que seja possível fazer a tramitação do documento.

Além disso, é preciso que a entidade certificadora seja integrante da infraestrutura do governo e receba uma classificação quanto ao seu nível de segurança. Desse modo, é possível garantir a validade jurídica dos documentos eletrônicos, bem como sua autenticidade e integridade.

As Autoridades Certificadoras (ACs) são responsáveis por gerenciar o ciclo de vida dos certificados digitais, controlando os processos de solicitação, emissão e revogação dos mesmos.

A Autoridade de Registro (AR) e o Repositório de Certificados Digitais também recebem tarefas delegadas da AC Raiz. À AR cabe a tarefa de verificar o conteúdo de requisições de certificados, enquanto o Repositório de Certificados Digitais tem como objetivo publicar os certificados digitais e as listas de certificados revogados emitidos por uma ou mais ACs. No Brasil, a hierarquia da Certificação Digital obedece ao ICP-Brasil, que deve ser:

• 1º nível – Autoridades Certificadoras Raiz (AC Raiz): Instituto Nacional de Tecnologia da Informação.
• 2º Nível – Autoridades Certificadoras de primeiro nível: Responsável pela emissão, revogação e gerenciamento dos Certificados Digitais de AC.
• 3º nível – Autoridades Certificadoras de segundo nível: Responsável pela emissão, revogação e gerenciamento dos Certificados Digitais.
• 4º nível – Autoridades de Registro: Responsável por identificar o usuário e solicitar e emitir os certificados.

Após o prazo de encerramento do Certificado Digital, ele é automaticamente expirado e, qualquer documento assinado após a data de vencimento não possui qualquer validade legal. Já os documentos que forem assinados dentro do período de validade do certificado, tem sua validade assegurada por tempo indeterminado.

A Certificação Digital é a tecnologia que permite que as transações eletrônicas sejam realizadas com segurança, por meio de algoritmos matemáticos capazes de garantir que as informações sejam manipuladas com autenticidade, integridade e confiabilidade.

A Assinatura Digital nada mais é que um processo eletrônico que faz uso de chaves criptografadas. De maneira geral, documentos que são assinados digitalmente passam por um processo de codificação das informações eletrônicas, de forma que somente receptor e emissor possam acessar os documentos compartilhados.

O uso do Certificado Digital é utilizado entre outras atividades para validar as transações bancárias on-line. Ou seja, para comprovar a autenticidade do serviço, o banco utiliza um certificado que assegura ao usuário que ele realmente está acessando o servidor do banco. Assim, ao acessar a sua conta bancária, por exemplo, o usuário pode utilizar seu certificado para autenticar-se diante do banco.

Guia das Etapas de Solicitação

Diagrama - Solicitação de um certificado digital.

A obtenção de um Certificado Digital compreende 4 etapas:

1. Solicitação: O interessado (pessoa física ou jurídica) deve acessar uma das Autoridades Certificadoras, escolher o tipo e a validade do Certificado Digital e encaminhar para o processo de compra.
2. Identificação Presencial: Após feita a solicitação, o interessado deve providenciar os documentos necessários para a emissão do certificado escolhido e agendar uma visita presencial em uma das Autoridades de Registro para realizar a identificação.
3. Validação e Verificação dos documentos: Depois de apresentar os documentos obrigatórios, o interessado deve aguardar a liberação da validação e verificação realizadas pela Autoridade de Registro. Caso esteja em conformidade com as exigências, é possível seguir para o processo de emissão.
4. Emissão: Na emissão, é gerado um par de chaves RSA com tamanho de 2048 bits e algoritmo de assinatura SHA 256 na mídia criptográfica do usuário.

Contudo, antes de requerer um Certificado Digital, o interessado deve analisar qual a finalidade de uso, a forma de armazenamento e o período de validade no qual deve obter seu documento para, então, solicitar o tipo de certificado adequado. É imprescindível que o interessado conheça as características de cada certificado antes de comprá-lo pelo site em uma das Autoridades Certificadoras habilitadas.

Emissão de certificados pelo Diretório de Participantes

O Diretório de Participantes foi escolhido como uma alternativa para a emissão de certificados, tornando-se uma Autoridade Certificadora para emissão de certificados para Clients (aplicativos).

Diagrama - Emitindo um certificado pelo Diretório

A obtenção de um Certificado Digital pelo Diretório, compreende 3 etapas:

1. Solicitação: O solicitante deve assinar a solicitação (CSR) utilizando o e-CNPJ e efetuar o upload no Diretório de Participantes.
2. Verificação: O Diretório realiza a verificação, estando em conformidade, prossegue para o processo de emissão.
3. Emissão: O Diretório emite um certificado e retorna para o solicitante.

[Em Revisão] CSR

Esse bloco consiste em um exemplo de como gerar o Certificate Signing Requests (CSR) para o PKI do Open Banking.
Existem vários utilitários para gerar CSRs para serem enviados a uma autoridade certificadora, neste exemplo vamos utilizar OpenSSL para demonstrar como um CSR válido é gerado para enviar ao Open Banking para emitir um certificado x509 de transporte ou assinatura.
OpenSSL é compatível com Windows ou Linux, podendo ser emitido no sistema operacional preferido:

Gerando CSR de transporte
$ openssl req -new -config transporte.cnf -out transporte.csr -keyout transporte.key

Gerando CSR de assinatura
$ openssl req -new -config assinatura.cnf -out assinatura.csr -keyout assinatura.key

Exemplo:

$ openssl req -new -config /share/ob/transporte.cnf -out transporte.csr -keyout transporte.key
Generating a RSA private key
........................................+++++
............+++++
writing new private key to 'assinatura.key'
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
BR []:BR

O CSR resultante deve ser carregado para o Open Banking PKI para emitir um certificado público de transporte ou assinatura associado à sua chave privada. Os arquivos resultantes devem ser protegidos pelas políticas de segurança da instituição.

Perfil de solicitação de assinatura de certificado X509 de transporte

Este bloco demonstra como gerar um CSR válido por um client que requer um Certificado de transporte X.509 utilizando um arquivo .cnf como base.
O seguinte arquivo de configuração é utilizado para gerar um CSR para um certificado de transporte usando OpenSSL.

Arquivo CNF OPENSSL Transporte apenas de exemplo, as configurações podem variar de acordo com a Autoridade Certificadora e para quem será emitido o certificado, alterar os campos como CNPJ e NOME da instituição:

# OPENSSL CSR REQUEST CONFIGURATION FILE
# ======================================
otherName = 2.16.76.1.3.3
otherName = 2.16.76.1.3.8
#otherName = 2.16.76.1.3.X #OID a ser confirmado com a informação dos endpoints
subjectAltName=@san
#CNPJ
otherName.1=2.16.76.1.3.3;UTF8:64721803000118
#Nome conforme consta no CNPJ
otherName.2=2.16.76.1.3.8;UTF8:Nome da instituicao
#Endpoints
#otherName.3=2.16.76.1.3.X;UTF8:Endpoints
# OpenSSL may not recognize this OID so need to add.
[ req ]
default_bits = 2048
#ou
#default_bits = 4096
# RSA key size
encrypt_key = yes
# Protect private key: yes or no. yes recommended
default_md = sha256
# MD to use. sha256 recommended
utf8 = yes
# Input is UTF-8.
string_mask = utf8only
# Emit UTF-8 strings
distinguished_name = client_dn
req_extensions = client_reqext
[ client_dn ]
countryName = "BR"
[ client_reqext ]
keyUsage = critical,digitalSignature
subjectKeyIdentifier = hash
extendedKeyUsage = clientAuth, serverAuth

Perfil de solicitação de assinatura de certificado X509 de assinatura

Este bloco demonstra como gerar um CSR válido por um client que requer um Certificado de assinatura X.509 utilizando um arquivo .cnf como base.
O seguinte arquivo de configuração é utilizado para gerar um CSR para um certificado de assinatura usando OpenSSL.

Arquivo CNF OPENSSL de Assinatura apenas de exemplo, as configurações podem variar de acordo com a Autoridade Certificadora e para quem será emitido o certificado, alterar os campos como CNPJ e NOME da instituição:

# OPENSSL CSR REQUEST CONFIGURATION FILE
# ======================================
otherName = 2.16.76.1.3.3
otherName = 2.16.76.1.3.8
subjectAltName=@san
#CNPJ
otherName.1=2.16.76.1.3.3;UTF8:64721803000118
#Nome conforme consta no CNPJ
otherName.2=2.16.76.1.3.8;UTF8:Nome da instituicao
# OpenSSL may not recognize this OID so need to add.
[ req ]
default_bits = 2048
#ou
#default_bits = 4096
# RSA key size
encrypt_key = yes
# Protect private key: yes or no. yes recommended
default_md = sha256
# MD to use. sha256 recommended
utf8 = yes
# Input is UTF-8.
string_mask = utf8only
# Emit UTF-8 strings
distinguished_name = client_dn
req_extensions = client_reqext
[ client_dn ]
countryName = "BR"
[ client_reqext ]
keyUsage = critical,digitalSignature,nonRepudiation
subjectKeyIdentifier = hash

O arquivo CSR OPENSSL resultante pode ser analisado com o seguinte comando:

$ openssl req -new -config assinatura.cnf -out assinatura.csr -keyout assinatura.key

[Em Revisão] Diretório de Participantes

Introdução

O Diretório de Participantes do Open Banking é o principal componente de arquitetura que permite que instituições provedoras se registrem e iniciem interações por meio de APIs com instituições transmissoras, também fornece um ambiente de testes.
O Diretório é um serviço de gerenciamento de identidade e acesso que fornece informações de identidade que dão suporte aos participantes do Ecossistema do Open Banking.
O Diretório de Participantes disponibiliza os recursos funcionais necessários para que as instituições provedoras possam se autenticar no Open Banking e também recursos para identificar as instituições transmissoras.
O Registro dos Provedores é obrigatório para usar as APIs fornecidas pelas instituições transmissoras.
As instituições transmissoras devem utilizar as informações técnicas contidas no Diretório para realizar o gerenciamento da identidade e da autorização das aplicações das instituições Participantes, que abrange a identificação, a autorização e a revogação de certificados utilizados no compartilhamento de dados e serviços do escopo do Open Banking.

Recursos funcionais do Diretório de Participantes:

• Gerenciar identidades e acesso: a capacidade de emitir e gerenciar registros de identidade para organizações e pessoas físicas que interagem com o Diretório.
• Gerenciar certificados e chaves: A capacidade de fazer upload, gerenciar e remover certificados, chaves de assinatura e chaves de criptografia. A capacidade de emitir, gerenciar e revogar certificados digitais do Open Banking.
• Gerenciar informações do Diretório: a capacidade de atualizar e localizar informações mantidas no diretório - por meio de APIs e/ou uma interface de usuário (IU).

Padrões

• Adoção de padrões abertos
  • O design do Diretório de Participantes do Open Banking será baseado em padrões abertos e amplamente adotados, como API Restful, OpenID Connect e OAuth2.
• Participantes devem estar registrados
  • Os participantes devem ser autorizados e registrados na autoridade competente.
• Uso de certificados
  • Os participantes que possuem um certificado válido podem se registrar no diretório mais rapidamente e sem a necessidade de realizar etapas manuais.

Registro de uma Instituição Provedora

O Diretório deverá realizar validações para o Registro de uma instituição receptora, depois destas validações, solicitações e respostas de API e/ou dados de contas podem ser compartilhadas com segurança entre as duas partes. O diretório deve validar, se:

• A instituição receptora está utilizando um certificado digital.
• O certificado se encontra em conformidade com os padrões do Open Banking Brasil.
• O certificado não está expirado.
• O certificado foi emitido por uma Entidade Emissora válida.
• O certificado não foi revogado.

Depois que todas as verificações forem realizadas, será estabelecido uma conexão TLS segura, mutuamente autenticada entre o Diretório e a instituição receptora.

Funções Operacionais dos Participantes

Fluxos para instituições receptoras

Fluxos para instituições transmissoras

Registro no diretório de participantes

Para poder consumir APIs disponibilizadas por uma instituição transmissora, uma instituição receptora deverá realizar um registro junto a instituição transmissora, esse processo de autenticação do participante deve ser feita de forma centralizada no Diretório de Participantes, sendo necessário a federação do seu portal ao Diretório. A instituição transmissora deve implementar um processo de integração da instituição receptora ao seu sistema, esse processo deve:

• Validar se a instituição receptora é autorizada por uma autoridade competente.
• Validar as informações da instituição receptora.

Após a instituição receptora realizar o registro no Diretório de Participantes, o mesmo poderá realizar o registro de clients (aplicações) na instituição transmissora. Para a realização do registro de clients no Open Banking, é mandatório a disponibilização do processo de registro de Client dinâmico, conforme [RFC 7591].

[Em Revisão] Registro de Client Dinâmico

O registro de Client dinâmico é mandatório para os participantes do Open Banking. Com uma API de registro de client dinâmico do Open Banking, utilizando o padrão de segurança OpenID Connect, as instituições receptoras podem se registrar junto a instituição transmissora.

• Para usar o Registro dinâmico de client, uma instituição receptora deve se registrar no Diretório de Participantes e obter um SSA e demais certificados digitais.
• O Client envia o SSA a uma instituição transmissora para registro dinâmico na instituição transmissora.

O diagrama abaixo mostra o fluxo do registro dinâmico de uma instituição receptora.

Diagrama - Fluxo de registro dinâmico.

As instituições receptoras precisam obter o SSA do Diretório de Participantes do Open Banking.
Uma API de Registro dinâmico consiste em endpoints, que realizam a concessão de credencias do client e a autenticação mútua de TLS para autenticar a instituição receptora. A API deve permitir que as seguintes operações sejam realizadas:

• Registro de um Client.
• Recuperar um Client.
• Atualizar um Client.
• Excluir um Client.

[Em Revisão] CORS

Contexto Open-Data

O Cross-Origin Resource Sharing (CORS) para todas as origens (valor " * ") será permitido nos seguintes endpoints:

• Open Data APIS
  • Canais de Atendimento
  • Produtos e Serviços

[Em Revisão] Endpoints

Contexto Open-data

Não haverá endpoints específicos para Autorização e Autenticação com o intuito de maximizar o uso do Open-data.

Será opcional a disponibilização de um endpoint para validação WKS:

api.banco.com.br/openbanking/security/v1/.well-known/jwks.json

Glossário de Segurança

Referências normativas

Referências informativas

Testes e Homologação

Diretrizes Gerais

A Estrutura de Governança do Open Banking irá disponibilizar uma estrutura, doravante denominada Sandbox, que permita aos participantes, no mínimo:

I – submeter, ainda em tempo de desenvolvimento, suas implementações das APIs do Open Banking a testes automatizados funcionais e não funcionais (“Motor de Testes”); e

II - acessar implementações de exemplo das APIs do Open Banking, inclusive ao menos uma que simule uma Instituição Participante de Referência, com implementação completa de cada API (“Implementação de Referência”).

A fase de teste e homologação tem como finalidade garantir que os participantes que desejam operar no Ecossistema do Open Banking, possam fazer isso de forma assertiva e segura. Isso incluí o suporte para as instituições com a capacidade de testar seus produtos e serviços desde o lançamento, quanto nas atualizações, fornecendo uma série de ferramentas e infraestrutura para garantir que seus produtos tenham sido testados tempestivamente antes de entrar em produção.

O escopo mínimo dos testes irá abranger aspectos funcionais e não funcionais; os primeiros visarão a avaliar se as implementações estão aderentes às especificações das APIs; os últimos objetivarão avaliar se os requisitos não funcionais das APIs, em particular, segurança, estão sendo atendidos por suas implementações.

A execução dos testes de conformidade será realizada em ambiente disponibilizado pela Estrutura de Governança. Uma implementação de versão de API do Open Banking só poderá ser registrada no ambiente produtivo do Diretório caso tenha sido certificada nos testes de conformidade.

Instituições Transmissoras

Instituições transmissoras devem obrigatoriamente realizar testes de conformidade através do motor de conformidade disponibilizado no Portal do Open Banking, gerando um certificado que as suas implementações de segurança, autenticação, registro dinâmico de clientes (DCR) e funcionalidades estão aderentes às especificações do Open Banking Brasil. Mais detalhes e instruções sobre o processo certificação de instituições transmissoras serão fornecidas assim que a implementação do motor de testes for finalizado

Após a certificação o resultado e o descritivo dos testes serão disponibilizados em área pública do Portal do Open Banking no Brasil.

Instituições Receptoras

Instituições receptoras deverão utilizar o serviço de Sandbox fornecido pela estrutura do Open Banking Brasil para validar sua implementação em um banco de referência. Este recurso reflete ao máximo o ambiente de produção e permite aos desenvolvedores testarem os seguintes aspectos:

• Funcionalidade: todas as funcionalidades das APIs relacionadas aos casos de uso. Deve funcionar de maneira equivalente ou representativa para a interface de produção, incluindo casos de uso negativos e códigos de erro.
• Segurança: Deve utilizar o mesmo perfil de segurança das APIs em produção.
• On-boarding: Deve replicar o processo de on-boarding das instalações de produção da instituição transmissora, incluindo o on-boarding e a troca de certificados para identificação e assinatura de mensagem.
• Certificados: Deve permitir o uso de certificados de teste (que têm o mesmo formato/estrutura dos certificados de produção) de modo que as instituições receptoras possam replicar a funcionalidade relacionados à troca de certificados para identificação e assinatura de mensagens.
• Dados de teste: Não deve incluir quaisquer dados reais de usuários finais. O volume e a variação dos dados devem ser suficientes para dar suporte a todos os testes técnicos e funcionais, incluindo paginação (onde for compatível com a interface dedicada).
• Contas de teste: Deve fornecer para as instituições receptoras um número de contas de teste que habilitem a funcionalidade e o acesso aos dados que os usuários reais experimentarão na produção.
• Autenticação: Deve fornecer recurso que permita que as instituições receptoras testem os procedimentos de autenticação, inclusive em produção, utilizando suas próprias contas e/ou contas de teste.
• Disponibilidade e desempenho: Não deve lidar com volumes de produção (ou seja, não deve ser usada por instituição transmissora ou instituição receptora para teste de estresse), no entanto, deve ter disponibilidade, capacidade, desempenho e outras características suficientes para facilitar a conexão eficaz e realista a testes funcionais da instituição receptora.
• Suporte: A instalação deve ter um nível apropriado de suporte para permitir a comunicação de problemas ou questões por instituições receptoras
• Documentação: Será publicado externamente um resumo das especificações da instalação de teste em seu site, incluindo detalhes de acesso e cobertura de teste.

Como utilizar a ferramenta da OpenID Foundation para testes FAPI R/W - Plain FAPI

Para a segunda fase do Open Banking Brasil, as instituições financeiras dos segmentos S1 e S2 e as que se voluntariaram para participar como “instituição transmissora e receptora de dados”, abreviada por DADOS no diretório de participantes, deverão realizar o teste e certificação dos seus Authorization Servers, conforme resolução do Banco Central (BC), antes de iniciarem o envio dos dados de usuários.

Como o perfil FAPI R/W – Brasil está previsto para ser publicado em versão beta no meio de junho, uma alternativa para as instituições financeiras que desejarem já iniciar o teste da sua implementação é utilizar o teste FAPI R/W – Plain FAPI.

O Perfil FAPI R/W – Plain FAPI já está configurado na plataforma de conformidade da OpenID Foundation (OIDF) e permite que qualquer instituição financeira teste sua implementação sem nenhum custo. Além disso, o perfil é muito semelhante ao que será utilizado no Brasil, tendo como principais diferenças:

• FAPI R/W - Brasil suporta signed e encrypted request objects ou push authorization request - Plain FAPI define os campos como opcionais
• FAPI R/W - Brasil demanda dynamic scopes - Plain FAPI não demanda
• FAPI R/W - Brasil demanda dynamic client registration/management - Plain FAPI não demanda
• FAPI R/W - Brasil demanda validação e processamento de specific indentity claims - Plain FAPI não demanda

Essa proximidade entre os perfis faz com que uma instituição que consiga passar em todos os testes hoje do Plain FAPI tenha poucas dificuldades em se certificar no FAPI Brasil quando este for disponibilizado.

É importante ressaltar que não será necessária a certificação FAPI R/W - Plain FAPI para o Open Banking Brasil, apenas a certificação FAPI R/W - Brasil. Neste caso, essa instrução tem como único objetivo ajudar a instituição a testar seu deployment antes do lançamento do perfil brasileiro e se ambientar no uso da ferramenta da OIDF.

Processo para utilização da ferramenta de certificação:

1. Criação de certificado no diretório de participantes: Antes da inicialização do teste, a instituição financeira deverá realizar a publicação de dois Software Statements no Sandbox do diretório de participantes e realizar a emissão de dois certificados de transporte que serão utilizados para acessar o Authorization Server a ser testado. O guia para realizar a emissão desse certificado pode ser consultado em: https://openbanking-brasil.github.io/areadesenvolvedor/#guia-operacional-do-diretorio-central. A instituição também pode optar por utilizar outro conjunto de certificados além destes emitidos pelo Sandbox do diretório de participantes.

2. Criação do plano de testes: Após a configuração do certificado, o desenvolvedor, em posse dos atributos do seu Authorization Server, poderá se conectar no motor de testes da OIDF e realizar a criação de um plano de testes em “Create a new test plan”. O preenchimento do plano de testes FAPI R/W - Plain FAPI pode ser conferido através do pdf: Guia OIDF.

3. Execução do plano de testes: Após a criação do plano de testes, a instituição poderá realizar todos os testes existentes na sua implementação. Para maior detalhamento dos testes, é possível consultar os dois workshops realizados pelo Open Banking Brasil e a OIDF sobre o perfil de segurança FAPI e o conjunto de testes de conformidade e certificação: https://openbanking-brasil.github.io/areadesenvolvedor/#workshops-com-openid-foundation

A OIDF também disponibiliza uma extensa documentação em relação ao motor de testes e aos perfis FAPI que pode ser acessada através dos links abaixo:

FAPI Especificações
Financial-grade API Security Profile 1.0 — Part 1: Baseline
Financial-grade API Security Profile 1.0 — Part 2: Advanced
Differences between ID2 and Final

FAPI Motor de testes e certificação
How to run conformance tests for FAPI-RW OPs
How to request certification after successfully completing conformance testing for FAPI-RW and FAPI-CIBA OPs
Financial-grade API (FAPI), Explained by an Implementer – Updated

Diretrizes técnicas do diretório

Guia Operacional do Diretório Central

Este guia serve para orientar participantes que desejam integrar seu software com o Diretório Central. Destina-se a administradores, contatos técnicos primários e secundários.

Aqui estão descritas as etapas técnicas para criar e manter declarações de software, tokens de acesso e servidores de autorização no ambiente de sandbox e produção do Diretório Central.

O documento está estruturado nas seguintes seções:

1. Introdução
2. Registrando um usuário no Diretório
3. Acessando uma Organisation
4. Cadastrando um Authorisation Server
5. Cadastrando Recursos de uma API
6. Criando um Software Statements
7. Criando uma solicitação de Assinatura de Certificado (CSR) em Sandbox
8. Carregando certificados assinados no Diretório em Produção
9. Obtendo um Software Statements Assertion
10. Configurando eventos de notificação no Diretório
11. Obtendo um token de acesso para as APIs do Diretório
12. Listando as organizações cadastradas no Diretório via API
13. Listando os servidores de autorização de uma organização via API
14. Obtendo um Software Statement via API
15. Obtendo um Software Statement Assertion via API
16. Suporte

O guia pode ser baixado nesse link (OpenBanking - Guia de operação do diretório central).

Especificações de APIs do Diretório e do Service Desk

APIs Diretório

O Diretório Central do Open Banking Brasil pode ser acessado tanto via interface gráfica quanto por meio de integração por APIs.

Para acessar as APIs do Diretório, verifique o item 10 do guia operacional do Diretório Central - “Obtendo um token de acesso para acessar as APIs do Diretório”. O guia está disponível na sessão “Diretrizes técnicas do Diretório”.

Para entender como usar cada API, leia a especificação do Swagger da API do Diretório disponível nesse link (https://github.com/OpenBanking-Brasil/specs-directory/blob/main/openapi.yaml).

As funcionalidades previamente liberadas para acesso são:

• Organisations
• References - Authority
• References - Authorisation Domain
• References - Authorisation Domain Role
• References - Authority Authorisation Domain
• Organisation Authority Domain Claims
• Organisation Authority Claims
• Organisation Authority Claims Authorisations
• Contacts
• Authorisation Servers
• Authorisation Servers - API Resources
• Authorisation Servers - API Discovery Endpoints
• Software Statements
• Software Statement Authority Claims
• Software Statement Certificates
• Software Statement Assertions

APIs Service Desk

O Service Desk do Open Banking Brasil pode ser acessado tanto via interface gráfica quanto por meio sistêmico através de APIs.

Para acessar a documentação das APIs do Service Desk é necessário logar na ferramenta via interface gráfica, acessar a sessão de FAQ e selecionar o menu "API SysAid".

As funcionalidades previamente liberadas para acesso são:

• (Status) Encaminhado N2 atendimento
• (Status) Em Análise N2
• (Status) Em Atendimento N2
• (Status) Encaminhado N1 Encerramento
• Interação com chamado através da API do SysAid

Como documento adicional, é possível fazer o download de um PDF nesse link (Especificação APIs Service Desk) contendo todas as informações listadas no repositório acima.

Problemas conhecidos da especificação

Atualmente não há problemas conhecidos

Guias de implementação

Acesse neste link uma implementação de referência da fase 1.

Esta implementação de exemplo permite ao desenvolvedor realizar testes referentes à fase 1 (open-data) do Open Banking Brasil.

Fase 1 - APIs do Open Banking Brasil v1.0.0

Para visualizar as especificações das API's do projeto Open Banking Brasil Fase 1, favor acessar o link abaixo:

API's Open Banking Fase 1

Divulgação dos valores de tarifas e taxas de juros remuneratórias

Conforme disposto na Circular nº 4.015, art. 3º, para fins de compartilhamento dos valores de tarifas e taxas de juros remuneratórias dos produtos e serviços ofertados, as instituições devem compartilhar uma distribuição de frequência relativa dos valores cobrados e dos clientes.

Segundo o Art. 6º da Instrução Normativa nº 32 BCB, de 2020: “O compartilhamento da distribuição de frequência relativa dos valores de tarifas e taxas de juros cobrados dos clientes, de que trata o § 2º do art. 3º da Circular nº 4.015, de 2020, deve dar-se com base em quatro faixas de igual tamanho, com explicitação dos valores sobre a mediana e o percentual de clientes em cada uma dessas faixas, além dos valores máximos e mínimos do universo, segmentados em pessoas naturais e jurídicas, bem como por tipo de serviço ou modalidade de operação e por indexador ou referencial, no caso de operações pós-fixadas.

§ 1º Admite-se que as instituições compartilhem dados relacionados à distribuição de frequência de que trata o caput em base atualizada em periodicidade mensal, divulgada no décimo dia útil de cada mês, a partir de janeiro de 2021, referente a valores cobrados de seus clientes no mês anterior.

§ 2º A distribuição de frequência relativa a taxas de juros divulgada conforme o § 1º deve corresponder às operações de crédito concedidas no mês anterior”’.

Desta forma, cada instituição deve, no momento de compartilhamento, ordenar sua base em ordem crescente de valores cobrados por tarifas e taxas de juros remuneratórias dos produtos e serviços ofertados durante o mês de apuração, segmentá-la em quatro faixas de mesmo valor e divulgar 10 valores:

• Valores: máximo e mínimo do universo de clientes (i.e. 2 valores)
• Mediana de cada faixa (i.e. 4 valores)
• Percentual de clientes em cada faixa (i.e. 4 valores)

Devem ser utilizados no cálculo os valores devidos de tarifas e os valores cobrados de taxas de juros remuneratórias disponíveis nas bases de cliente no mês anterior.

Caso haja mais de 1 evento por cliente referente ao mesmo produto e/ou serviço, deverá ser considerado apenas 1 valor, calculado como a média aritmética dos valores das ocorrências daquele cliente.

Para taxas de juros remuneratórias, os valores compartilhados/divulgados serão os que correspondem às concessões no mês da apuração, segmentados em pessoas naturais e jurídicas, bem como por modalidade de operação e por indexador ou referencial, no caso de operações pós-fixadas.

Para tarifas, a segmentação é por pessoas naturais e jurídicas e por tipo de serviço referente a tarifa avulsa (fora do Pacote de Serviço) cobradas no mês de apuração, devendo-se considerar inclusive as de valor zero (ou isentas).

Tarifas – Apuração Frequência e valores correspondentes

Serviço: tarifas avulsas cobradas no mês de apuração. (Cada tarifa será informada separadamente, devendo ser informadas tantas tarifas quanto as que satisfizerem os critérios de apuração) As tarifas de valor zero (ou isentas) fora de pacotes de serviços, caso tenham ocorrido no mês de referência, devem ser consideradas na distribuição de frequência relativa dos valores.

Tipo Pessoa: PN ou PJ

Período: Mês fechado, identificado como M-1

Base Clientes: clientes segregados por tipo de pessoa que tiveram cobrança da mesma tarifa avulsa (não inclusa no Pacote de serviços) no mês de apuração. Caso haja mais de 1 evento por cliente, referente ao mesmo produto e/ou serviço, deverá ser considerado apenas 1 valor, calculado como a média aritmética dos valores das ocorrências daquele cliente

Processo de Apuração para cada tipo de tarifa que satisfizer critérios de apuração:

1. Identificar clientes com mais de uma ocorrência de evento e calcular a média aritmética sobre valores cobrados;
2. Enfileirar os valores em ordem crescente de grandeza;
3. Definir menor (MenorVL) e maior valor (MaiorVL) relativos às tarifas enfileiradas em ordem crescente
4. Definir: ( MaiorVL – MenorVL ) / 4 = Intervalo para definição faixas de valores (e se MenorVL = MaiorVL, então (MaiorVL – 0) / 4
5. Calcular mediana dos valores em cada faixa
6. Calcular o percentual de clientes por faixa ( soma dos valores apurados = 100% )

Exemplo de Uso:

• Tarifas – Apuração Frequência e valores correspondentes

Download do exemplo

• Tarifas – Distribuição de Frequência

Download do exemplo

Apuração Frequência Taxas Juros remuneratórios

Modalidade: relativa às operações de crédito concedidas (contratadas) no mês da apuração (M-1 – mês anterior)

Tipo Pessoa: PN ou PJ

Taxa ou Indexador: referente ao custo da operação contratada e percentual de incidência (conforme Anexo 5: Taxa referencial ou Indexador (Indx), do Documento 3040, BCB) – Dado informativo

Período: mês fechado, identificado como M-1

Base Clientes: clientes segregados por tipo de pessoa (contrato) que tomou crédito de mesma Modalidade no mês de apuração. Com mesmo tipo de taxa ou Indexador e mesmo percentual aplicado. Caso haja mais de 1 evento por cliente referente a mesma Modalidade e Indexador deverá ser considerado apenas 1 valor, calculado como a média aritmética dos valores das ocorrências daquele cliente

Processo de Apuração para cada tipo de Indexador/taxa – percentual aplicado para cada Modalidade que satisfizer os critérios de apuração

Para cada Indexador/Taxa e seu percentual, da Modalidade apurada:

1. Identificar clientes com mais de uma ocorrência de evento e calcular a média aritmética sobre valores cobrados;
2. Enfileirar os valores em ordem crescente de grandeza;
3. Definir menor (MenorVL) e maior valor (MaiorVL) relativos aos valores enfileirados em ordem crescente
4. Calcular: ( MaiorVL – MenorVL ) / 4 = Intervalo para definição faixas de valores (e se MenorVL = MaiorVL, então 1. (MaiorVL – 0) / 4
5. Calcular mediana dos valores em cada faixa
6. Calcular o percentual de clientes por faixa ( soma dos valores apurados = 100% )

Exemplos de Uso:

• Taxas Remuneratórias – Apuração Frequência e valores correspondentes 1

Download do exemplo

• Taxas Remuneratórias – Apuração Frequência e valores correspondentes 2

Download do exemplo

• Distribuição de Frequência

Download do exemplo

• Distribuição de Frequência Convenções

Download do exemplo

• Taxas Remuneratórias – Distribuição de Frequência

Download do exemplo

Fase 2 - APIs do Open Banking Brasil v1.0.0-rc6.3

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Clientes poderão solicitar o compartilhamento entre instituições participantes de seus dados cadastrais, de informações sobre transações em suas contas, cartão de crédito e produtos de crédito contratados.

O compartilhamento ocorre apenas se a pessoa autorizar através da API de Consentimento, sempre para finalidades determinadas e por um prazo específico. E será possível para o cliente cancelar essa autorização a qualquer momento em qualquer uma das instituições envolvidas no compartilhamento.

API - Consentimento

Visão Geral

A API tem como objetivo garantir que o usuário esteja ciente e concordando com a disponibilização e compartilhamento de determinados dados entre bancos e instituições financeiras e acessível também à estabelecimentos comerciais participantes do Open Banking Brasil.

É possível realizar a criação (não possuindo restrição de uso entre pessoa física e pessoa jurídica), consulta e revogação de um consentimento mediante a integração entre as instituições autorizadas.

Especificação em OAS 3.0

Download da Especificação (OAS 3.0)

Criar novo pedido de consentimento.

Exemplo de código

const data = JSON.stringify({
  "data": {
    "loggedUser": {
      "document": {
        "identification": "11111111111",
        "rel": "CPF"
      }
    },
    "businessEntity": {
      "document": {
        "identification": "11111111111111",
        "rel": "CNPJ"
      }
    },
    "permissions": [
      "ACCOUNTS_READ",
      "ACCOUNTS_OVERDRAFT_LIMITS_READ",
      "RESOURCES_READ"
    ],
    "expirationDateTime": "2021-05-21T08:30:00Z",
    "transactionFromDateTime": "2021-01-01T00:00:00Z",
    "transactionToDateTime": "2021-02-01T23:59:59Z"
  }
});

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://example.com/consents/v1/consents");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Accept", "application/json");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-fapi-auth-date", "stringstringstringstringstrin");
xhr.setRequestHeader("x-fapi-customer-ip-address", "string");
xhr.setRequestHeader("x-fapi-interaction-id", "string");
xhr.setRequestHeader("x-customer-user-agent", "string");

xhr.send(data);

import http.client

conn = http.client.HTTPSConnection("example.com")

payload = "{\"data\":{\"loggedUser\":{\"document\":{\"identification\":\"11111111111\",\"rel\":\"CPF\"}},\"businessEntity\":{\"document\":{\"identification\":\"11111111111111\",\"rel\":\"CNPJ\"}},\"permissions\":[\"ACCOUNTS_READ\",\"ACCOUNTS_OVERDRAFT_LIMITS_READ\",\"RESOURCES_READ\"],\"expirationDateTime\":\"2021-05-21T08:30:00Z\",\"transactionFromDateTime\":\"2021-01-01T00:00:00Z\",\"transactionToDateTime\":\"2021-02-01T23:59:59Z\"}}"

headers = {
    'Content-Type': "application/json",
    'Accept': "application/json",
    'Authorization': "string",
    'x-fapi-auth-date': "stringstringstringstringstrin",
    'x-fapi-customer-ip-address': "string",
    'x-fapi-interaction-id': "string",
    'x-customer-user-agent': "string"
    }

conn.request("POST", "/consents/v1/consents", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.post("https://example.com/consents/v1/consents")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("Authorization", "string")
  .header("x-fapi-auth-date", "stringstringstringstringstrin")
  .header("x-fapi-customer-ip-address", "string")
  .header("x-fapi-interaction-id", "string")
  .header("x-customer-user-agent", "string")
  .body("{\"data\":{\"loggedUser\":{\"document\":{\"identification\":\"11111111111\",\"rel\":\"CPF\"}},\"businessEntity\":{\"document\":{\"identification\":\"11111111111111\",\"rel\":\"CNPJ\"}},\"permissions\":[\"ACCOUNTS_READ\",\"ACCOUNTS_OVERDRAFT_LIMITS_READ\",\"RESOURCES_READ\"],\"expirationDateTime\":\"2021-05-21T08:30:00Z\",\"transactionFromDateTime\":\"2021-01-01T00:00:00Z\",\"transactionToDateTime\":\"2021-02-01T23:59:59Z\"}}")
  .asString();

POST /consents/v1/consents

Método para a criação de um novo consentimento.

Dicionário de dados

Fazer download do dicionário de dados

Especificação em OAS 3.0

Download da Especificação (OAS 3.0)

Body parameter

{
  "data": {
    "loggedUser": {
      "document": {
        "identification": "11111111111",
        "rel": "CPF"
      }
    },
    "businessEntity": {
      "document": {
        "identification": "11111111111111",
        "rel": "CNPJ"
      }
    },
    "permissions": [
      "ACCOUNTS_READ",
      "ACCOUNTS_OVERDRAFT_LIMITS_READ",
      "RESOURCES_READ"
    ],
    "expirationDateTime": "2021-05-21T08:30:00Z",
    "transactionFromDateTime": "2021-01-01T00:00:00Z",
    "transactionToDateTime": "2021-02-01T23:59:59Z"
  }
}

Parâmetros

O comando acima retorna uma estrutura json como essa:

201 Response

{
  "data": {
    "consentId": "urn:bancoex:C1DD33123",
    "creationDateTime": "2021-05-21T08:30:00Z",
    "status": "AWAITING_AUTHORISATION",
    "statusUpdateDateTime": "2021-05-21T08:30:00Z",
    "permissions": [
      "ACCOUNTS_READ",
      "ACCOUNTS_OVERDRAFT_LIMITS_READ",
      "RESOURCES_READ"
    ],
    "expirationDateTime": "2021-05-21T08:30:00Z",
    "transactionFromDateTime": "2021-01-01T00:00:00Z",
    "transactionToDateTime": "2021-02-01T23:59:59Z"
  },
  "links": {
    "self": "https://api.banco.com.br/open-banking/api/v1/resource",
    "first": "https://api.banco.com.br/open-banking/api/v1/resource",
    "prev": "https://api.banco.com.br/open-banking/api/v1/resource",
    "next": "https://api.banco.com.br/open-banking/api/v1/resource",
    "last": "https://api.banco.com.br/open-banking/api/v1/resource"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

Resposta

Response Headers

Obter detalhes do consentimento identificado por consentId.

Exemplo de código

const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://example.com/consents/v1/consents/string");
xhr.setRequestHeader("Accept", "application/json");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-fapi-auth-date", "stringstringstringstringstrin");
xhr.setRequestHeader("x-fapi-customer-ip-address", "string");
xhr.setRequestHeader("x-fapi-interaction-id", "string");
xhr.setRequestHeader("x-customer-user-agent", "string");

xhr.send(data);

import http.client

conn = http.client.HTTPSConnection("example.com")

headers = {
    'Accept': "application/json",
    'Authorization': "string",
    'x-fapi-auth-date': "stringstringstringstringstrin",
    'x-fapi-customer-ip-address': "string",
    'x-fapi-interaction-id': "string",
    'x-customer-user-agent': "string"
    }

conn.request("GET", "/consents/v1/consents/string", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://example.com/consents/v1/consents/string")
  .header("Accept", "application/json")
  .header("Authorization", "string")
  .header("x-fapi-auth-date", "stringstringstringstringstrin")
  .header("x-fapi-customer-ip-address", "string")
  .header("x-fapi-interaction-id", "string")
  .header("x-customer-user-agent", "string")
  .asString();

GET /consents/v1/consents/{consentId}

Método para obter detalhes do consentimento identificado por consentId.

Dicionário de dados

Fazer download do dicionário de dados

Especificação em OAS 3.0

Download da Especificação (OAS 3.0)

Parâmetros

O comando acima retorna uma estrutura json como essa:

200 Response

{
  "data": {
    "consentId": "urn:bancoex:C1DD33123",
    "creationDateTime": "2021-05-21T08:30:00Z",
    "status": "AWAITING_AUTHORISATION",
    "statusUpdateDateTime": "2021-05-21T08:30:00Z",
    "permissions": [
      "ACCOUNTS_READ",
      "ACCOUNTS_OVERDRAFT_LIMITS_READ",
      "RESOURCES_READ"
    ],
    "expirationDateTime": "2021-05-21T08:30:00Z",
    "transactionFromDateTime": "2021-01-01T00:00:00Z",
    "transactionToDateTime": "2021-02-01T23:59:59Z"
  },
  "links": {
    "self": "https://api.banco.com.br/open-banking/api/v1/resource",
    "first": "https://api.banco.com.br/open-banking/api/v1/resource",
    "prev": "https://api.banco.com.br/open-banking/api/v1/resource",
    "next": "https://api.banco.com.br/open-banking/api/v1/resource",
    "last": "https://api.banco.com.br/open-banking/api/v1/resource"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

Resposta

Response Headers

Deletar/revogar o consentimento identificado por consentId.

Exemplo de código

const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://example.com/consents/v1/consents/string");
xhr.setRequestHeader("Accept", "application/json; charset=utf-8");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-fapi-auth-date", "stringstringstringstringstrin");
xhr.setRequestHeader("x-fapi-customer-ip-address", "string");
xhr.setRequestHeader("x-fapi-interaction-id", "string");
xhr.setRequestHeader("x-customer-user-agent", "string");

xhr.send(data);

import http.client

conn = http.client.HTTPSConnection("example.com")

headers = {
    'Accept': "application/json; charset=utf-8",
    'Authorization': "string",
    'x-fapi-auth-date': "stringstringstringstringstrin",
    'x-fapi-customer-ip-address': "string",
    'x-fapi-interaction-id': "string",
    'x-customer-user-agent': "string"
    }

conn.request("DELETE", "/consents/v1/consents/string", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.delete("https://example.com/consents/v1/consents/string")
  .header("Accept", "application/json; charset=utf-8")
  .header("Authorization", "string")
  .header("x-fapi-auth-date", "stringstringstringstringstrin")
  .header("x-fapi-customer-ip-address", "string")
  .header("x-fapi-interaction-id", "string")
  .header("x-customer-user-agent", "string")
  .asString();

DELETE /consents/v1/consents/{consentId}

Método para deletar/revogar o consentimento identificado por consentId.

Especificação em OAS 3.0

Download da Especificação (OAS 3.0)

Parâmetros

O comando acima retorna uma estrutura json como essa:

400 Response

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string"
    }
  ],
  "meta": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

Resposta

Response Headers

API - Resources

Obtém a lista de recursos consentidos pelo cliente.

Exemplo de código

const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://example.com/resources/v1/resources");
xhr.setRequestHeader("Accept", "application/json");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-fapi-auth-date", "stringstringstringstringstrin");
xhr.setRequestHeader("x-fapi-customer-ip-address", "string");
xhr.setRequestHeader("x-fapi-interaction-id", "string");
xhr.setRequestHeader("x-customer-user-agent", "string");

xhr.send(data);

import http.client

conn = http.client.HTTPSConnection("example.com")

headers = {
    'Accept': "application/json",
    'Authorization': "string",
    'x-fapi-auth-date': "stringstringstringstringstrin",
    'x-fapi-customer-ip-address': "string",
    'x-fapi-interaction-id': "string",
    'x-customer-user-agent': "string"
    }

conn.request("GET", "/resources/v1/resources", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://example.com/resources/v1/resources")
  .header("Accept", "application/json")
  .header("Authorization", "string")
  .header("x-fapi-auth-date", "stringstringstringstringstrin")
  .header("x-fapi-customer-ip-address", "string")
  .header("x-fapi-interaction-id", "string")
  .header("x-customer-user-agent", "string")
  .asString();

GET /resources/v1/resources

Método para obter a lista de recursos mantidos pelo cliente na instituição transmissora e para as quais ele tenha fornecido consentimento.

Dicionário de dados

Fazer download do dicionário de dados

Especificação em OAS 3.0

Download da Especificação (OAS 3.0)

Parâmetros

O comando acima retorna uma estrutura json como essa:

200 Response

{
  "data": [
    {
      "resourceId": "25cac914-d8ae-6789-b215-650a6215820d",
      "type": "ACCOUNT",
      "status": "AVAILABLE"
    }
  ],
  "links": {
    "self": "https://api.banco.com.br/open-banking/api/v1/resource",
    "first": "https://api.banco.com.br/open-banking/api/v1/resource",
    "prev": "https://api.banco.com.br/open-banking/api/v1/resource",
    "next": "https://api.banco.com.br/open-banking/api/v1/resource",
    "last": "https://api.banco.com.br/open-banking/api/v1/resource"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

Resposta

Response Headers

API - Dados Cadastrais

Identificação Pessoa Natural

Exemplo de código

const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://example.com/customers/v1/personal/identifications");
xhr.setRequestHeader("Accept", "application/json");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-fapi-auth-date", "stringstringstringstringstrin");
xhr.setRequestHeader("x-fapi-customer-ip-address", "string");
xhr.setRequestHeader("x-fapi-interaction-id", "string");
xhr.setRequestHeader("x-customer-user-agent", "string");

xhr.send(data);

import http.client

conn = http.client.HTTPSConnection("example.com")

headers = {
    'Accept': "application/json",
    'Authorization': "string",
    'x-fapi-auth-date': "stringstringstringstringstrin",
    'x-fapi-customer-ip-address': "string",
    'x-fapi-interaction-id': "string",
    'x-customer-user-agent': "string"
    }

conn.request("GET", "/customers/v1/personal/identifications", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://example.com/customers/v1/personal/identifications")
  .header("Accept", "application/json")
  .header("Authorization", "string")
  .header("x-fapi-auth-date", "stringstringstringstringstrin")
  .header("x-fapi-customer-ip-address", "string")
  .header("x-fapi-interaction-id", "string")
  .header("x-customer-user-agent", "string")
  .asString();

GET /customers/v1/personal/identifications

Visão Geral

Obtém os registros de identificação da pessoa natural

Esta especificação inclui todos os itens relevantes que permitam a ação e o efeito de identificar de forma única a pessoa natural através de seus dados cadastrais.

Tags: CBO (Cbo Code), CNPJ (CNPJ Number), CPF - Cadastro de Pessoa Física (Cpf Number), Identificação (Identification), Instituição Financeira (Company), Marca (Brand), Nome Civil Completo (Civil Name), Nome Social (Social Name) e Sexo (Sex).

Visão de alto de nível das estruturas de dados

DER - Diagramas de Entidade e Relacionamento

• DER Conceitual

Fazer download do DER Conceitual

• DER Lógico

Fazer download do DER Lógico

Dicionário de dados

Fazer download do dicionário de dados

Fazer download dos exemplos

Especificação em OAS 3.0

Download da Especificação (OAS 3.0)

Parâmetros

O comando acima retorna uma estrutura json como essa:

200 Response

{
  "data": [
    {
      "updateDateTime": "2021-05-21T08:30:00Z",
      "personalId": "578-psd-71md6971kjh-2d414",
      "brandName": "Organização A",
      "civilName": "Juan Kaique Cláudio Fernandes",
      "socialName": "string",
      "birthDate": "2021-05-21",
      "maritalStatusCode": "SOLTEIRO",
      "maritalStatusAdditionalInfo": "",
      "sex": "FEMININO",
      "companyCnpj": [
        "01773247000103",
        "01773247000563"
      ],
      "documents": {
        "cpfNumber": "25872252137",
        "passportNumber": "75253468744594820620",
        "passportCountry": "CAN",
        "passportExpirationDate": "2021-05-21",
        "passportIssueDate": "2021-05-21"
      },
      "otherDocuments": [
        {
          "type": "CNH",
          "typeAdditionalInfo": "NA",
          "number": "15291908",
          "checkDigit": "P",
          "additionalInfo": "SSP/SP",
          "expirationDate": "2021-05-21"
        }
      ],
      "hasBrazilianNationality": false,
      "nationality": [
        {
          "otherNationalitiesInfo": "CAN",
          "documents": [
            {
              "type": "SOCIAL SEC",
              "number": "423929299",
              "expirationDate": "2021-05-21",
              "issueDate": "2021-05-21",
              "country": "Brasil",
              "typeAdditionalInfo": "Informações adicionais."
            }
          ]
        }
      ],
      "filiation": [
        {
          "type": "PAI",
          "civilName": "Marcelo Cláudio Fernandes",
          "socialName": "NA"
        }
      ],
      "contacts": {
        "postalAddresses": [
          {
            "isMain": true,
            "address": "Av Naburo Ykesaki, 1270",
            "additionalInfo": "Fundos",
            "districtName": "Centro",
            "townName": "Marília",
            "ibgeTownCode": "3550308",
            "countrySubDivision": "SP",
            "postCode": "17500001",
            "country": "Brasil",
            "countryCode": "BRA",
            "geographicCoordinates": {
              "latitude": "-90.8365180",
              "longitude": "-180.836519"
            }
          }
        ],
        "phones": [
          {
            "isMain": true,
            "type": "FIXO",
            "additionalInfo": "Informações adicionais.",
            "countryCallingCode": "55",
            "areaCode": "19",
            "number": "29875132",
            "phoneExtension": "932"
          }
        ],
        "emails": [
          {
            "isMain": true,
            "email": "karinafernandes-81@br.inter.net"
          }
        ]
      }
    }
  ],
  "links": {
    "self": "https://api.banco.com.br/open-banking/api/v1/resource",
    "first": "https://api.banco.com.br/open-banking/api/v1/resource",
    "prev": "https://api.banco.com.br/open-banking/api/v1/resource",
    "next": "https://api.banco.com.br/open-banking/api/v1/resource",
    "last": "https://api.banco.com.br/open-banking/api/v1/resource"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

Resposta

Identificação Pessoa Jurídica

Exemplo de código

const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://example.com/customers/v1/business/identifications");
xhr.setRequestHeader("Accept", "application/json");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-fapi-auth-date", "stringstringstringstringstrin");
xhr.setRequestHeader("x-fapi-customer-ip-address", "string");
xhr.setRequestHeader("x-fapi-interaction-id", "string");
xhr.setRequestHeader("x-customer-user-agent", "string");

xhr.send(data);

import http.client

conn = http.client.HTTPSConnection("example.com")

headers = {
    'Accept': "application/json",
    'Authorization': "string",
    'x-fapi-auth-date': "stringstringstringstringstrin",
    'x-fapi-customer-ip-address': "string",
    'x-fapi-interaction-id': "string",
    'x-customer-user-agent': "string"
    }

conn.request("GET", "/customers/v1/business/identifications", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://example.com/customers/v1/business/identifications")
  .header("Accept", "application/json")
  .header("Authorization", "string")
  .header("x-fapi-auth-date", "stringstringstringstringstrin")
  .header("x-fapi-customer-ip-address", "string")
  .header("x-fapi-interaction-id", "string")
  .header("x-customer-user-agent", "string")
  .asString();

GET /customers/v1/business/identifications

Visão Geral

Obtém os registros de identificação da pessoa jurídica

Esta especificação inclui todos os itens relevantes que permitam a ação e o efeito de identificar de forma única a pessoa jurídica através de seus dados cadastrais.

Tags: CNPJ (CNPJ Number), CPF - Cadastro de Pessoa Física (CPF Number), Identificação (Identification), Instituição Financeira (Company), Marca (Brand), Nome Civil Completo (Civil Name), Nome Social (Social Name) e Razão Social (Company Name).

Visão de alto de nível das estruturas de dados

DER - Diagramas de Entidade e Relacionamento

• DER Conceitual

Fazer download do DER Conceitual

• DER Lógico

Fazer download do DER Lógico

Dicionário de dados

Fazer download do dicionário de dados

Fazer download dos exemplos

Especificação em OAS 3.0

Download da Especificação (OAS 3.0)

Parâmetros

O comando acima retorna uma estrutura json como essa:

200 Response

{
  "data": [
    {
      "updateDateTime": "2021-05-21T08:30:00Z",
      "businessId": "578-psd-71md6971kjh-2d414",
      "brandName": "Organização A",
      "companyName": "Luiza e Benjamin Assessoria Jurídica Ltda",
      "tradeName": "Mundo da Eletronica",
      "incorporationDate": "2021-05-21T08:30:00Z",
      "cnpjNumber": "50685362006773",
      "companyCnpjNumber": [
        "50685362000135",
        "50685362006555"
      ],
      "otherDocuments": [
        {
          "type": "EIN",
          "number": "128328453",
          "country": "CAN",
          "expirationDate": "2021-05-21"
        }
      ],
      "parties": [
        {
          "personType": "PESSOA_NATURAL",
          "type": "SOCIO",
          "civilName": "Juan Kaique Cláudio Fernandes",
          "socialName": "Karina",
          "companyName": "Luiza e Benjamin Assessoria Jurídica Ltda",
          "tradeName": "Mundo da Eletronica",
          "startDate": "2021-05-21T08:30:00Z",
          "shareholding": "0.51",
          "documentType": "CPF",
          "documentNumber": "73677831148",
          "documentAdditionalInfo": "CNH",
          "documentCountry": "CAN",
          "documentExpirationDate": "2021-05-21",
          "documentIssueDate": "2021-05-21"
        }
      ],
      "contacts": {
        "postalAddresses": [
          {
            "isMain": true,
            "address": "Av Naburo Ykesaki, 1270",
            "additionalInfo": "Fundos",
            "districtName": "Centro",
            "townName": "Marília",
            "ibgeTownCode": "3550308",
            "countrySubDivision": "SP",
            "postCode": "17500001",
            "country": "Brasil",
            "countryCode": "BRA",
            "geographicCoordinates": {
              "latitude": "-90.8365180",
              "longitude": "-180.836519"
            }
          }
        ],
        "phones": [
          {
            "isMain": true,
            "type": "FIXO",
            "additionalInfo": "Informações adicionais.",
            "countryCallingCode": "55",
            "areaCode": "19",
            "number": "29875132",
            "phoneExtension": "932"
          }
        ],
        "emails": [
          {
            "isMain": true,
            "email": "karinafernandes-81@br.inter.net"
          }
        ]
      }
    }
  ],
  "links": {
    "self": "https://api.banco.com.br/open-banking/api/v1/resource",
    "first": "https://api.banco.com.br/open-banking/api/v1/resource",
    "prev": "https://api.banco.com.br/open-banking/api/v1/resource",
    "next": "https://api.banco.com.br/open-banking/api/v1/resource",
    "last": "https://api.banco.com.br/open-banking/api/v1/resource"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}