...Manual de Integração

O presente documento demonstra o uso das APIs da Plataforma de Coleta de Métricas.

Referências

Documentação da API

A documentação oficial da API se encontra no repositório de especificações no Github em https://github.com/OpenBanking-Brasil/specs-pcm/ - o link direto para o fonte da documentação da api é:

https://raw.githubusercontent.com/OpenBanking-Brasil/specs-pcm/main/openapi/openapi.yaml

Documentação funcional

A documentação funcional pode ser encontrada em ...Plataforma de Coleta de MétricasUNDEFINED

Procedimento de integração

Visão geral

O diagrama abaixo ilustra os principais componentes da plataforma

Para que reportes sejam enviados para a PCM é necessário que o participante obtenha um token de acesso, o que é feito através de um endpoint de autenticação que é acessível através de uma conexão mTLS. De posse do token, o participante pode efetuar os envios para os endpoints da API descritas na documentação. É necessário o uso de certificados válidos para a recuperação do token, em contrapartida os envios de reportes são feitos sem a necessidade de uma conexão mTLS.

Endereços base

Os endereços base em cada ambiente, bem como suas respectivas datas de validade são os abaixo:

Ambiente	Endereço	Tipo	Validade

Ambiente	Endereço	Tipo	Validade
Sandbox	https://api.pcm.sandbox.openfinancebrasil.org.br	API	Indeterminada
Sandbox	https://auth.pcm.sandbox.openfinancebrasil.org.br	Autenticação	Indeterminada
Piloto	https://api.pcm.piloto.openfinancebrasil.org.br	API	Disponível até 31/01/2023
Piloto	https://auth.pcm.piloto.openfinancebrasil.org.br	Autenticação	Disponível até 31/01/2023
Produção	https://api.pcm.openfinancebrasil.org.br	API	Disponível a partir de 01/02/2023
Produção	https://auth.pcm.openfinancebrasil.org.br	Autenticação	Disponível a partir de 01/02/2023

Autenticação

O procedimento segue o fluxo de client_credentials da especificação oauth2, sendo que o acesso ao endpoint precisa ser feito usando uma conexão mTLS. As credenciais, bem como os certificados aceitos em cada um dos ambientes estão descritos abaixo:

Ambiente	Credenciais	Certificados

Ambiente	Credenciais	Certificados
Sandbox/Piloto	client_id do Software Statement do diretório de sandbox	Certificado emitido pelo diretório central de sandbox
Produção	client_id do Software Statement do diretório de produção	Certificado emitido por autoridade certificadora aceita pelo ecossistema^[1]

O endpoint de recuperação de token é:

<endereço de autenticação conforme ambiente>/token/

Importante: manter a última barra ("/") depois de token.

Para se recuperar um token, é necessário estabelecer uma comunicação mTLS entre o cliente que está fazendo a chamada e o authorization server, utilizando um certificado de cliente. Os passos para configuração de certificados cliente no Postman podem ser encontrados em https://learning.postman.com/docs/sending-requests/certificates/.

Os tokens gerados estão configurados com duração de 21600 segundos (6 horas). Não há limitação para a quantidade de tokens gerados muito embora seja importante que eles sejam reaproveitados no período de validade. É possível fazer a introspecção do token para se determinar até quando ele é válido, uma vez que ele não é criptografado.

Para recuperar um token é necessário fazer uma chamada POST usando um payload com os seguintes campos:

client_id	`client_id` do software statement ligado ao certificado usado no acesso
grant_type	Fixo: `client_credentials`

Não há a necessidade do envio do client_secret, uma vez que a camada de transporte via certificado cliente já assegura a autenticidade do chamador.

Os campos relevantes devolvidos por esse endpoint são:

access_token	Token no padrão jwt para acesso às APIs
expires_in	Número de segundos em que o token é válido
token_type	O tipo do token fornecido (nesse caso, Bearer)

Exemplo

Envio de um request para o endereço de autenticação em sandbox:

POST https://auth.pcm.sandbox.openfinancebrasil.org.br/token/
Content-Type: application/json 

{ 
  "client_id": "1234",
  "grant_type": "client_credentials" 
}

Resposta:

200 Ok 

{ 
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkFiT", 
  "expires_in": 21600, 
  "token_type": "Bearer" 
}

Interação com a API

Para realizar chamadas localmente, realize a importação da documentação OpenAPI no seu cliente HTTP (Postman: https://learning.postman.com/docs/integrations/available-integrations/working-with-openAPI/ , Insomnia: https://docs.insomnia.rest/insomnia/import-export-data#import-data ). Esse procedimento irá criar as collections nos formatos descritos pela documentação.

O token gerado deverá ser enviado nas chamadas da API do PCM dentro do header Authorization, identificando o tipo do token conforme abaixo:

Authorization: <token type> <token>

Onde <token type> pode ser Bearer, Basic, etc (no caso das APIs da PCM, será aceito apenas tokens do tipo Bearer), e o token recuperado no processo de autenticação.

Usando o exemplo da chamada da sessão anterior, o header deverá ser mandado com o seguinte conteúdo:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkFiT

Exemplo

Para o envio de um reporte como server, o request tem que ser como o exemplo abaixo:

POST https://api.pcm.sandbox.openfinancebrasil.org.br/report-api/v1/private/report 
Content-Type: application/json 
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkFiT 

[
  {
  "timestamp": "2022-08-31T17:43:13.622Z", 
  "fapiInteractionId": "e67824fa-6b4d-448c-8101-304407259552", 
  "endpoint": "/open-banking/customers/v2/personal/financial-relations", 
  "statusCode": 200, 
  "httpMethod": "GET", 
  "processTimespan": 120, 
  "clientOrgId": "c160a6f5-e5df-5067-9e97-ec6fba62fd87", 
  "serverOrgId": "2a01e202-e8f0-5f5a-9651-ebc257371e6e", 
  }
]

Resposta

Exemplos de chamadas

Os exemplos abaixo utilizam as instituições que participaram do Piloto da PCM. São elas (em ordem alfabética): Banrisul, BV, Caixa e Gerencianet.

Os cenários de teste foram montados a fim de demonstrar o uso da API. A escolha de qual instituição faz qual chamada foi aleatória, e tem o único objetivo de exemplificar os tipos de chamadas em seus cenários.

Cenário 1: PAIRED

BV faz chamada para Caixa, ambos enviam reportes sem erros. O status esperado para os dois reportes finais é PAIRED.

BV:

Caixa:

Cenário 2: PAIRED_INCONSISTENT

Caixa reporta transação feita com Banrisul, mas os dados de consistência não estão iguais. O status esperado para os dois reportes finais é PAIRED_INCONSISTENT.

Caixa:

Banrisul:

Cenário 3: SINGLE

Banrisul reporta timeout em uma transação com BV, sendo que a geração do fapiInteractionId seria feita pelo server. O status desse reporte será SINGLE.

Cenário 4: DISCARDED

Gerencianet envia um reporte sem o campo httpMethod, que é um campo obrigatório. O status do reporte será registrado como DISCARDED, e o status retorno da chamada será 400.

Resposta

Cenário 5: DISCARDED

Caixa envia reporte com dado inconsistente no campo endpoint (veja lista dos endpoints válidos na documentação da API e na documentação funcional). Status do reporte tem que ser DISCARDED com a devida justificativa, e o status da resposta 400.

Resposta

Cenário 6: DISCARDED

Banrisul envia reporte sem os identificadores de receptor e transmissor. Status do reporte deverá ser DISCARDED com a devida justificativa e o status de retorno, 400. No entanto, apenas o Banrisul poderá consultar esse reporte.

^[1] Padrão de certificação do Open Finance Brasil v2.1