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étricas
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 |
|---|---|---|---|
Sandbox | API | Indeterminada | |
Autenticação | |||
Piloto | API | Disponível até 31/01/2023 | |
Autenticação | |||
Produção | API | Disponível a partir de 01/02/2023 | |
Autenticação |
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 |
|---|---|---|
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 |
|
grant_type | Fixo: |
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
200 Ok
Content-Type: application/json
{
"reportId": "9737cc7f-9854-4f57-aec6-7f1778c642d4",
"status": "ACCEPTED"
}
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:
{
“role”: “CLIENT”,
"timestamp": "2022-08-31T17:43:13.622Z",
"fapiInteractionId": "cd9a2e6b-0c33-403b-a8dd-544e95c63cd8",
"endpoint": "/open-banking/unarranged-accounts-overdraft/v1/contracts/{contractId}/scheduled-instalments",
“additionalInfo”: {
“consentId”: “uri:bv:6096c7f6-53a0-4c53-bc95-9c8d48b9a6cf“,
“personType”: “PF“
}
"statusCode": 200,
"httpMethod": "GET",
"clientOrgId": "062c5edb-4e83-5002-9981-e2a96c5ad41e",
"serverOrgId": "c160a6f5-e5df-5067-9e97-ec6fba62fd87",
"processTimespan": 120,
"clientSSId": "clientSSId",
"endpointUriPrefix": "https://openbanking.instituicao.com.br/namespace"
}
Caixa:
{
“role”: “SERVER”,
"timestamp": "2022-08-31T17:44:42.812Z",
"fapiInteractionId": "cd9a2e6b-0c33-403b-a8dd-544e95c63cd8",
"endpoint": "/open-banking/unarranged-accounts-overdraft/v1/contracts/{contractId}/scheduled-instalments",
"statusCode": 200,
"httpMethod": "GET",
"clientOrgId": "062c5edb-4e83-5002-9981-e2a96c5ad41e",
"serverOrgId": "c160a6f5-e5df-5067-9e97-ec6fba62fd87",
"processTimespan": 90
}
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:
{
“role”: “CLIENT”,
"timestamp": "2022-08-31T17:43:13.622Z",
"fapiInteractionId": "cd9a2e6b-0c33-403b-a8dd-544e95c63cd8",
"endpoint": "/open-banking/unarranged-accounts-overdraft/v1/contracts/{contractId}/scheduled-instalments",
“additionalInfo”: {
“consentId”: “uri:caixa:6096c7f6-53a0-4c53-bc95-9c8d48b9a6cf“
}
"statusCode": 200,
"httpMethod": "GET",
"clientOrgId": "c160a6f5-e5df-5067-9e97-ec6fba62fd87",
"serverOrgId": "2a01e202-e8f0-5f5a-9651-ebc257371e6e",
"processTimespan": 120,
"clientSSId": "clientSSId",
"endpointUriPrefix": "https://openbanking.instituicao.com.br/namespace"
}
Banrisul:
{
“role”: “SERVER”,
"timestamp": "2022-08-31T17:44:42.812Z",
"fapiInteractionId": "cd9a2e6b-0c33-403b-a8dd-544e95c63cd8",
"endpoint": "/open-banking/unarranged-accounts-overdraft/v1/contracts/{contractId}/scheduled-instalments",
"statusCode": 201,
"httpMethod": "GET",
"clientOrgId": "c160a6f5-e5df-5067-9e97-ec6fba62fd87",
"serverOrgId": "2a01e202-e8f0-5f5a-9651-ebc257371e6e",
"processTimespan": 90
}
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.
{
“role”: “CLIENT”,
"timestamp": "2022-08-31T17:43:13.622Z",
"fapiInteractionId": "cd9a2e6b-0c33-403b-a8dd-544e95c63cd8",
"endpoint": "/open-banking/unarranged-accounts-overdraft/v1/contracts/{contractId}/scheduled-instalments",
“additionalInfo”: {
“consentId”: “uri:banrisul:6096c7f6-53a0-4c53-bc95-9c8d48b9a6cf“,
“personType”: “PF“
}
"statusCode": 408,
"httpMethod": "GET",
"clientOrgId": "2a01e202-e8f0-5f5a-9651-ebc257371e6e",
"serverOrgId": "062c5edb-4e83-5002-9981-e2a96c5ad41e",
"processTimespan": 120,
"clientSSId": "clientSSId",
"endpointUriPrefix": "https://openbanking.instituicao.com.br/namespace"
}
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.
{
“role”: “CLIENT”,
"timestamp": "2022-08-31T17:43:13.622Z",
"fapiInteractionId": "cd9a2e6b-0c33-403b-a8dd-544e95c63cd8",
"endpoint": "/open-banking/unarranged-accounts-overdraft/v1/contracts/{contractId}/scheduled-instalments",
“additionalInfo”: {
“consentId”: “uri:gerencianet:6096c7f6-53a0-4c53-bc95-9c8d48b9a6cf“,
“personType”: “PF“
}
"statusCode": 200,
"httpMethod": "GET",
"clientOrgId": "b43131be-6a7f-5bfb-b436-c3ac5c5c2dac",
"serverOrgId": "062c5edb-4e83-5002-9981-e2a96c5ad41e",
"processTimespan": 120,
"clientSSId": "clientSSId",
"endpointUriPrefix": "https://openbanking.instituicao.com.br/namespace"
}
Resposta
400 BadRequest
Content-Type: application/json
{
"reportId": "9737cc7f-9854-4f57-aec6-7f1778c642d4",
"status": "DISCARDED",
"message": "Missing fields: httpMethod
}
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.
{
“role”: “CLIENT”,
"timestamp": "2022-08-31T17:43:13.622Z",
"fapiInteractionId": "cd9a2e6b-0c33-403b-a8dd-544e95c63cd8",
"endpoint": "/invalid_endpoint",
“additionalInfo”: {
“consentId”: “uri:caixa:6096c7f6-53a0-4c53-bc95-9c8d48b9a6cf“,
“personType”: “PF“
}
"statusCode": 200,
"httpMethod": "GET",
"clientOrgId": "c160a6f5-e5df-5067-9e97-ec6fba62fd87",
"serverOrgId": "062c5edb-4e83-5002-9981-e2a96c5ad41e",
"processTimespan": 120,
"clientSSId": "clientSSId",
"endpointUriPrefix": "https://openbanking.instituicao.com.br/namespace"
}
Resposta
400 BadRequest
Content-Type: application/json
{
"reportId": "9737cc7f-9854-4f57-aec6-7f1778c642d4",
"status": "DISCARDED",
"message": "Unlisted endpoint: /invalid_enpoint
}
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.
{
“role”: “CLIENT”,
"timestamp": "2022-08-31T17:43:13.622Z",
"fapiInteractionId": "cd9a2e6b-0c33-403b-a8dd-544e95c63cd8",
"endpoint": "/invalid_endpoint",
“additionalInfo”: {
“consentId”: “uri:banrisul:6096c7f6-53a0-4c53-bc95-9c8d48b9a6cf“,
“personType”: “PF“
}
"statusCode": 200,
"httpMethod": "GET",
"processTimespan": 120,
"clientSSId": "clientSSId",
"endpointUriPrefix": "https://openbanking.instituicao.com.br/namespace"
}