Reporte

O Reporte é o dado que as instituições participantes enviam para a Plataforma de Coleta de Métricas para catalogar a interação entre elas.

Fluxo

Considerando:

• Uma interação entre "Instituição A" e "Instituição B" onde a Instituição A vai solicitar a lista de contas de um determinado responsável pelo objeto de negócio para a Instituição B;

• A parte que realiza a chamada já tem o consentimento do responsável pelo objeto de negócio para recuperar os dados;

O esquema abaixo mostra a interação entre as duas instituições.

Open

1. Instituição A faz uma chamada para /accounts/v1/accounts na Instituição B. Essa chamada contém o header x-fapi-interaction-id, conforme documentação do endpoint[^1];

2. Instituição B registra essa chamada e processa o pedido e retorna resposta à instituição A;

3. Instituição B envia o reporte para Plataforma Coleta de Métricas ;

4. Instituição A recebe a resposta da instituição B e envia o reporte para Plataforma Coleta de Métricas.

Modelos dos reportes

As APIs da PCM são divididas em duas categorias:

Reportes private: representam os reportes sobre transações feitas entre duas instituições participantes do Open Finance. Se tratam de transações protegidas pelos mecanismos de segurança vigentes no OFB, e portanto são considerados reportes de APIs privadas.

Reportes opendata: se referem aos reportes feitos em APIs da fase 1 específicas para dados abertos. Como se referem à endpoints que são disponíveis a público em geral, são considerados reportes abertos.

Modelos para reportes Private

O reporte contém dados que se referem à uma transação em específico entre dois participantes, e é a informação que cada papel (server ou client) tem que enviar para a Plataforma de Coleta de Métricas.
Uma instituição é identificada pelo seu organisationId (com "s").

No contexto de uma chamada, os dados enviados para a Plataforma de Coleta de Métricas pelo client e pelo server são diferentes, uma vez que essa diferença reflete os contextos de execução da transação de cada um dos lados.

Os campos abaixo são comuns tanto para o client quanto para o server:

Modelo do Client

Além dos campos padrão do reporte, o client necessita enviar os campos abaixo. Note que todos eles são obrigatórios:

Além dos campos padrão do reporte, o server necessita enviar os seguintes campos:

Para informações detalhadas, bem como exemplos de utilização, consulte a documentação da API.

Reportes OpenData

Quando o envio for para um reporte de chamadas em endpoints da fase 1 (dados abertos), o modelo a ser enviado segue o padrão de dados a seguir. Como as APIs da fase 1 não se referem à transações entre duas instituições participantes, não existe processo de conciliação.

Para detalhes sobre o campo additionalInfo, consulte o tópico específico abaixo.

Campos especiais

fapiInteractionId

O fapiInteractionId é um dado que precisa ser conhecido pelas duas partes. Ele trafega no header x-fapi-interaction-id e identifica uma chamada e resposta em específico. Quando o client enviar essa informação para o server, ambos enviam o dado que foi gerado pelo client. Caso essa informação não seja enviada pelo client, ela deve ser gerada e devolvida pelo server, e nesse caso, ambos enviam o dado gerado pelo server.

Essa informação é obrigatória para a Plataforma de Coleta de Métricas, uma vez que é o principal dado utilizado na conciliação das chamadas mas, de acordo com a documentação dos headers do Open Finance[1], não é obrigatória no momento da solicitação.

endpoint

O campo endpoint registra o identificador do endpoint envolvido na transação. O dado faz parte do conjunto (ENUM) previamente listado na Documentação da API e reproduzido abaixo, a qual refletirá os endpoints previstos na documentação do Open Finance. Por se tratar da identificação do endpoint, o valor do path efetivamente trafegado na transação será considerado inválido pela plataforma, caso ele seja diferente das entradas do ENUM.

O envio do campo endpoint difere para reportes privados e para reportes de dados abertos. A lista de endpoints para cada tipo de envio pode ser encontrada aqui.

Existem dois casos especiais que são os endpoints /token e /register. Esses endpoints não possuem padrão pré definido, uma vez que cada participante decide suas próprias URLs e informam dentro dos seus respectivos catálogos. Portanto, para o preenchimento do reporte no papel de client, é necessário que cada participante identifique o endpoint através das URL’s de .well-known e inclua esse valor no campo endpointUriPrefix. Sob a perspectiva do server, o report deverá ser feito como /token e /register de acordo com o endereço que foi chamado.

Esse procedimento é obrigatório para participantes que estejam enviando reportes no papel de client. Em versões futuras, esse processo também deverá ser feito para os participantes que reportarem no papel de server. A lista de endpoints válidos será atualizada quinzenalmente dentro da PCM.

additionalInfo

O campo additionalInfo tem por objetivo concentrar informações adicionais dentro de um determinado contexto da transação. Ele tem uma ligação estrita com o campo endpoint, ou seja, as informações que deverão ser repassadas no additionalInfo dependem do valor informado no campo endpoint.

A planilha em anexo (download aqui) contém o detalhamento das regras de envio de cada informação no campo additionalInfo conforme o contexto.

Clique aqui para acessar a tabela contextualizada para Jornada Sem Redirecionamento

Exemplos de uso e detalhamento dos campos e das operações podem ser encontradas na Documentação da API.

Formas de Envio

Os reportes deverão ser enviados através de seus respectivos endpoints seguindo sua natureza (reportes ou opendata). Todos os reportes devem ser enviados em lotes, ainda que sejam poucos reportes por lote. É permitido enviar reportes de client e server no mesmo lote.

O limite operacional estabelecido para o envio é de no máximo 5.000 reportes por requisição.

Em todos os casos, o processamento dos dados é feito de forma assíncrona.

Recepção e retorno

Quando um reporte chega nos endpoints da API, ele recebe um atributo reportId, que o identifica unicamente na plataforma. A partir daí é feita a validação de campos obrigatórios. Caso o formato do reporte esteja inválido, aquele reportId em particular será marcado com o status DISCARDED, acrescido de uma descrição. Caso não haja erro no formato, o report ganha o status ACCEPTED. Depois dessa validação, são retornados os campos reportId, status e correlationId (quando aplicável) para o chamador. Todos os reportes são então inseridos em uma fila de processamento, feito sempre de maneira assíncrona, e portanto se utiliza da premissa da consistência posterior[2].

O detalhamento dos status e o ciclo de vida do reporte são detalhados no tópico sobre processamento.

[1]: A documentação das APIs do Open Finance Brasil define os cabeçalhos padrão para uma chamada. O detalhamento de cada cabeçalho pode ser encontrado em Cabeçalhos HTTP

[2]: Definição de Consistência Tardia ou Posterior - Inglês/Português

Próximo: Processamento