Comparação de Páginas

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:

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:

O endpoint de recuperação de token é: 

...

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

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: 

Exemplo

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

...

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. 

...

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkFiT 

Exemplo

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

...

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. 

...

{
  “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. 

...

{
  “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. 

...

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. 

...

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" 
}

...

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