> For the complete documentation index, see [llms.txt](https://docs.scorepositivo.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scorepositivo.com.br/relatorios/requisicao-de-relatorio.md).

# Requisição de Relatório

Os relatórios são consultas individuais e possuem unicamente os dados relativo ao documento pesquisado. Deve-se usar a mesma endpoint utilizando o código do relatório desejado.

O código de cada relatório está descrito nas sessões a seguir, nos detalhamentos de cada relatório.

## Requisição Base

Todos os relatórios são consultados por meio de um único end-point:

{% hint style="info" %} <mark style="color:orange;">**POST**</mark>         /api/report
{% endhint %}

## Parâmetros da requisição

Os parâmetros base da requisição devem ser enviados via **Data Raw JSON** no body da requisição.

<table><thead><tr><th width="262">Campo</th><th>Descrição</th></tr></thead><tbody><tr><td><strong>report_id</strong></td><td><p><mark style="color:red;">Obrigatório.</mark></p><p>Código do relatório a ser consultado.</p></td></tr><tr><td><strong>document</strong></td><td><p><mark style="color:red;">Obrigatório.</mark></p><p>Numeração do documento a ser consultado.</p></td></tr><tr><td><strong>external_id</strong></td><td><p><mark style="color:blue;">Opcional.</mark></p><p>Id de identificação da transação no seu sistema. (Char 36)</p></td></tr><tr><td><mark style="color:orange;"><strong>trial</strong></mark></td><td><p><mark style="color:blue;">Opcional.</mark></p><p><mark style="color:orange;">Enviar este parâmetro com o valor <strong>true</strong> durante o período de testes/integração.</mark><br></p><p><mark style="color:red;"><strong>Para as consultas de produção, NÃO DEVE ser enviado.</strong></mark></p></td></tr></tbody></table>

{% hint style="warning" %} <mark style="color:orange;">**INFO**</mark>

Alguns relatórios possuem parâmetros adicionais, alguns obrigatórios e ainda alguns relatórios possuem parâmetros diferentes dos parâmetros básicos padrão.

Consulte sempre a documentação do relatório específico para ver todos detalhes.
{% endhint %}

## Ambiente de Homologação e Testes

Devido da dinâmica de diversas combinações de resultados possíveis entre todos os relatórios, não possuímos um ambiente exclusivo para homologação.\
Deve-se utilizar para este fim, a requisição direto em ambiente de produção com uma flag de nome "**trial**" onde estas requisições não serão cobradas.\
O número de chamadas em **trail** é limitado, em caso de atingir o limite, acione seu gerente de contas.

## Exemplo de requisição para <mark style="color:orange;">Testes / Integração</mark>

```json
curl
--location 
--request POST 'https://core.scorepositivo.com.br/api/report' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI'
--data '{
    "report_id":"cpf-register",
    "document":"00000000000",
    "trial":true
}'
```

## Exemplo de requisição em <mark style="color:blue;">Produção</mark>

```json
curl
--location 
--request POST 'https://core.scorepositivo.com.br/api/report' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI'
--data '{
    "report_id":"cpf-register",
    "document":"00000000000"
}'
```

## Retornos

As requisições de relatórios retornam em uma estrutura principal, contendo o cabeçalho da consulta e o elemento <mark style="color:blue;">**report**</mark> com o conteúdo de cada relatório individualizado.

Você encontrará os detalhes de retorno de cada relatório individual nas sessões de relatórios disponíveis para consulta.

## Parâmetros de resposta

<table><thead><tr><th width="258">Campo</th><th>Descrição</th></tr></thead><tbody><tr><td>id</td><td>Identificador único da transação (UUID).</td></tr><tr><td>created_at</td><td>Data hora da requisição. (em GTM -03:00)</td></tr><tr><td>report_id</td><td>Código do relatório solicitado</td></tr><tr><td>document</td><td>Documento da consulta</td></tr><tr><td>status</td><td><p>Lista de status:</p><p></p><p><strong>PROCESS</strong> </p><p><strong>SUCCESS</strong> </p><p><strong>UNAVAILABLE</strong> </p><p><strong>EXCEPTION</strong> </p><p><strong>ERROR</strong><br><br>Ver detalhamento dos Status mais abaixo</p></td></tr><tr><td>code</td><td>Código para descrição complementar do status. Confira a <a href="/tabela-de-mensagens.md">Tabela de Mensagens</a> para mais detalhes.</td></tr><tr><td>report</td><td>Elemento JSON com o resultado do relatório solicitado.</td></tr></tbody></table>

```json
{    
    "id": "1876d480-5d69-4d7f-8f03-b83ba02fc605",
    "created_at": "2024-07-23T18:57:52-03:00",
    "report_id":"cpf-register",
    "document":"00000000000",
    "status": "SUCCESS",
    "code": 0,
    "report": {
        //CONTEUDO DO RELATÓRIO
    } 
}
```

{% hint style="warning" %} <mark style="color:orange;">**INFO**</mark>

**PROCESS**\
O status **PROCESS** é retornado para os relatórios de processamentos assíncronos.\
Neste caso, o resultado deve ser consultado através do endpoint de resultado de relatórios. O status **PROCESS** é o único status **mutável**, pois até o SLA limite do relatório, ele se tornará em algum dos status a seguir.

\ <mark style="color:blue;">**SUCCESS**</mark>\
O status <mark style="color:blue;">**SUCCESS**</mark> é retornado para relatórios executado com sucesso.\
Nem sempre isso implica em retorno de dados, alguns relatórios consultam justamente a falta de apontamentos no documento consultado.\
As transações com status <mark style="color:blue;">**SUCCESS**</mark> são as únicas que geram cobranças.

\ <mark style="color:orange;">**UNAVAILABLE**</mark> e <mark style="color:orange;">**ERROR**</mark>\
Os status <mark style="color:orange;">**UNAVAILABLE**</mark> e <mark style="color:orange;">**ERROR**</mark> representam alguma indisponibilidade momentânea no documento e/ou fonte de dados ou ainda erros sistêmicos.\
Neste caso, a consulta pode ser requisitada novamente após alguns minutos ou após algum momento maior, conforme descrição da mensagem de retorno.

\ <mark style="color:red;">**EXCEPTION**</mark> \
O status <mark style="color:red;">**EXCEPTION**</mark> representa alguma limitação de negócio ou jurídica para a entrega dos dados.\
Neste caso, os dados não serão retornados para o documento solicitado, até que o documento deixe de ter a restrição aplicada.<br>
{% endhint %}