API Guide

Introdução

Nesta seção, serão encontradas as informações sobre as APIs (Application Programming Interface) disponíveis para a iniciativa de Open Banking, do Banco Central. Para cada API, disponibilizaremos sua documentação contento orientações de uso, padrões, requisitos de segurança e os ambientes disponíveis.

O objetivo desta documentação é orientar o desenvolvedor sobre como integrar com as APIs de Open Banking, descrevendo as funcionalidades, os métodos a serem utilizados, listando informações a serem enviadas e recebidas, e provendo exemplos.

Glossário

HTTP:: termo em inglês Hypertext Transfer Protocol que significa em tradução para o português Protocolo de Transferência de Hipertexto.

API:: termo em inglês Application Programming Interface que significa em tradução para o português Interface de Programação de Aplicativos.

URI:: termo em inglês Uniform Resource Identifier que significa em tradução para o português Identificador de Recursos Universal.

REST:: termo em inglês Representational State Transfer que significa em tradução para o português Transferência de Estado Representacional.

RESTful:: conjunto de boas práticas que usa o protocolo HTTP (verbos, accept headers, status codes, Content-Type) de forma explícita e representativa para se comunicar através da web.

JSON:: termo em inglês JavaScript Object Notation que significa em tradução para o português Notação de Objetos Javascript.

Padrões

API RESTful

Por padrão, nossas APIs seguem o conjunto de boas práticas para comunicação web utilizando o protocolo HTTP, isto significa que os recursos disponíveis serão consumidos utilizando os verbos HTTP GET, POST, DELETE, PUT e PATCH, observando a definição de cada endpoint como descrito na seção API Browser;

Estrutura das URIs

As URIs para os endpoints estão disponíveis conforme o padrão: https://manager-openbanking.sensedia.com/<ambiente>/open-banking/<api>/<versão>/<recurso>

  • <ambiente>: Informa o ambiente desejado. Os ambientes disponíveis para utilização são sandbox (/sandbox) e produção (/);
  • <api>: Informa o nome da API como descrito na seção API Browser;
  • <versão>: Informa a versão da API como descrito na seção API Browser;
  • <recurso>: Informa o recurso utilizado como descrito na seção API Browser;

Estrutura da requisição

Cada requisição, quando definida no endpoint pelo verbo HTTP, deve ser um objeto JSON contendo um objeto data para armazenar os dados primários da requisição. Ex.:
{
 "data": {
  "..."
 }
}

Estrutura da resposta

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;
  • opicionalmente 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)

Exemplo de estrutura de resposta:

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

Exemplo de estrutura de resposta de erros:

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

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.

A paginação vai obedecer o padrão de resposta, ou seja, quando o conteúdo do objeto data for representado por um array de outros objetos. Quando existir paginação para o recurso, deverão ser utilizados os parâmetros de query abaixo para a navegação dos resultados:

page: Número da página que está sendo requisitada (o valor da primeira página é 1).

page-size: Quantidade total de registros por páginas.

Autenticação

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

open-data: Este contexto contempla a disponibilização de dados abertos referentes a canais de atendimento, produtos e serviços. Não haverá endpoints específicos para Autorização e Autenticação com o intuito de maximizar o uso do Open-data.

customer-data: Este contexto contempla a disponibilização de dados privados ainda não implementado.

A autenticação das APIs, quando especificada no seu devido contexto, é realizada com a informação de um par de tokens no cabeçalho (header) das requisições. O seguinte par de tokens é esperado em cada requisição:

client_id: Identificação da APP. Sua geração ocorre no momento da criação da APP pelo painel do desenvolvedor. Seu valor pode ser visualizado na coluna Token da lista de APPs e poderá ser utilizado tanto em Sandbox quanto em Produção após a aplicação passar pelo processo de homologação.

access_token: Identificação do token de acesso, que armazena as regras de acesso permitidas à APP. Sua geração ocorre em dois momentos no processo de integração com as APIs.

Status Codes

Código Erro Descrição
200

OK

Sucesso.

400

Bad Request

A requisição possui parametro(s) inválido(s).

401

Unauthorized

O token de acesso não foi informado ou não possui acesso as APIs.

404

Not Found

O recurso informado no request não foi encontrado.

413

Request is to Large

A requisição está ultrapassando o limite permitido para o perfil do seu token de acesso.

422

Unprocessable Entity

A requisição possui erros de negócio.

429

Too Many Requests

O consumidor estourou o limite de requisições por tempo.

500

Internal Server Error

Erro não esperado, algo está quebrado na API.

Undefined