> ## Documentation Index
> Fetch the complete documentation index at: https://docs.databox360.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Integração

> Informações técnicas para integração com a API do Perfil Financeiro.

A integração com o **Perfil Financeiro** utiliza o mesmo padrão de autenticação das demais APIs da DataBox360.

Caso sua aplicação já esteja integrada à consulta SCR, não será necessário implementar um novo fluxo de autenticação. A mesma chave de API pode ser utilizada para acessar o Perfil Financeiro.

## Autenticação

Após realizar a autenticação, envie o token no cabeçalho `Authorization` de cada requisição:

```http theme={null}
Authorization: Bearer YOUR_JWT_TOKEN
```

<Note>
  O token deve ser enviado no formato `Bearer`. Consulte a página de [Autenticação API](/api-reference/autenticacao) para verificar o fluxo completo de geração do token.
</Note>

## Ambientes e Endpoints

A API do Perfil Financeiro está disponível nos ambientes Sandbox e Produção.

| Ambiente | Endpoint                                                      |
| -------- | ------------------------------------------------------------- |
| Sandbox  | `https://sandbox-api.databox360.com.br/api/perfil-financeiro` |
| Produção | `https://api.databox360.com.br/api/perfil-financeiro`         |

<Warning>
  Utilize o endpoint correspondente ao ambiente configurado para sua integração.
</Warning>

## Método HTTP

A consulta é realizada por meio do método `POST`:

```http theme={null}
POST /perfil-financeiro
```

## Cabeçalhos

Envie os seguintes cabeçalhos na requisição:

```http theme={null}
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json
```

## Data-Base da Consulta

A data-base determina o mês de referência das informações utilizadas na geração do Perfil Financeiro.

Como as informações são atualizadas mensalmente, a DataBox360 aplica uma regra para definir a data-base mais recente disponível com segurança:

| Dia da requisição | Data-base considerada   |
| ----------------- | ----------------------- |
| Dia **1 a 25**    | Mês retrasado (**M-2**) |
| Dia **26 a 31**   | Mês anterior (**M-1**)  |

### Exemplo

| Data da requisição | Data-base considerada |
| ------------------ | --------------------- |
| `05/08/2026`       | `06/2026` (M-2)       |
| `26/08/2026`       | `07/2026` (M-1)       |

<Note>
  Os campos `mes` e `ano` devem respeitar a data-base disponível no momento da requisição.
</Note>

Na resposta, o período efetivamente consultado é informado no campo `consulta.databaseConsultada`, no formato `AAAA-MM`:

```json theme={null}
{
  "consulta": {
    "databaseConsultada": "2026-07"
  }
}
```

## Corpo da Requisição

A requisição utiliza os mesmos campos da consulta SCR:

```json theme={null}
{
  "documento": "00.000.000/0001-00",
  "mes": "06",
  "ano": "2026"
}
```

<ParamField body="documento" type="string" required>
  CPF ou CNPJ da pessoa consultada. Exemplo de CNPJ: `00.000.000/0001-00`.
</ParamField>

<ParamField body="mes" type="string" required>
  Mês de referência da consulta, informado com dois dígitos. Exemplo: `06`.
</ParamField>

<ParamField body="ano" type="string" required>
  Ano de referência da consulta, informado com quatro dígitos. Exemplo: `2026`.
</ParamField>

## Exemplo Simplificado

```bash theme={null}
curl -X POST https://sandbox-api.databox360.com.br/api/perfil-financeiro \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documento": "00.000.000/0001-00",
    "mes": "06",
    "ano": "2026"
  }'
```

## Retorno da Consulta

Quando a consulta for concluída com sucesso, a API retornará:

* o identificador da consulta no campo `id`;
* os indicadores estruturados no objeto `consulta`;
* o status da operação;
* uma `url` exclusiva para visualização do Perfil Financeiro;
* a versão da API.

<Info>
  O campo `url` permanece na raiz da resposta e direciona para a visualização exclusiva da consulta realizada.
</Info>

<Card title="Consultar Referência da API" icon="arrow-right" href="/perfil-financeiro/consulta">
  Consulte os exemplos completos de requisição, resposta e documentação dos campos.
</Card>