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 em Documentação da API - PCMPreview

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

Open

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 é: 

<endereço de autenticação conforme ambiente>/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:

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: 

Resposta: 

Alternativamente, é possível utilizar o fluxo fresh, ficando a cargo das instituições o comportamento mais adequado a cada situação.

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

O fluxo fresh sempre gera um token novo, ignorando qualquer token em cache para leitura. Após a leitura, salva esse token em cache.

O comportamento desse endpoint é:

• Ao chamar o endpoint fresh, o sistema não reutiliza token de cache existente.

• O sistema chama o provedor de autenticação e obtém um token novo.

• Em seguida, esse token novo também é gravado no cache.

• Depois disso, uma chamada ao endpoint /token pode retornar esse token recém-gerado, desde que ele ainda esteja válido.

Em resumo: fresh ignora cache na entrada, mas alimenta cache na saída.

Para a maioria das requisições, o uso de token em cache continua sendo o comportamento padrão, trazendo:

• menor latência

• menos chamadas externas

• melhor escalabilidade do sistema

Isso mantém o sistema rápido e eficiente para uso cotidiano.

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: 

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: 

Exemplo

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

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 - PCMPreview 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