> ## 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.

# Consulta

> Consulta o Perfil Financeiro de pessoas físicas ou jurídicas por CPF/CNPJ e período de referência.

Realiza a consulta do **Perfil Financeiro**, retornando indicadores consolidados sobre composição da carteira, vencimentos, modalidades e insights financeiros.

<div class="relative flex-1 flex gap-2 min-w-0 rounded-xl items-center cursor-pointer p-1.5 border-standard">
  <div class="method-pill rounded-lg font-bold px-1.5 py-0.5 text-sm leading-5 bg-blue-400/20 dark:bg-blue-400/20 text-blue-700 dark:text-blue-400">
    POST
  </div>

  [https://sandbox-api.databox360.com.br/api/perfil-financeiro](https://sandbox-api.databox360.com.br/api/perfil-financeiro)
</div>

## Endpoints

<ParamField body="Sandbox" type="string">
  `https://sandbox-api.databox360.com.br/api/perfil-financeiro`
</ParamField>

<ParamField body="Produção" type="string">
  `https://api.databox360.com.br/api/perfil-financeiro`
</ParamField>

<Info>
  A operação utiliza autenticação Bearer Token, seguindo o mesmo padrão das demais APIs da DataBox360.
</Info>

<RequestExample>
  ```bash cURL 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"
        }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://sandbox-api.databox360.com.br/api/perfil-financeiro",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_JWT_TOKEN",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        documento: "00.000.000/0001-00",
        mes: "06",
        ano: "2026",
      }),
    }
  );

  const perfilFinanceiroData = await response.json();
  console.log(perfilFinanceiroData);
  ```

  ```python Python theme={null}
  import requests

  url = "https://sandbox-api.databox360.com.br/api/perfil-financeiro"
  headers = {
      "Authorization": "Bearer YOUR_JWT_TOKEN",
      "Content-Type": "application/json"
  }
  payload = {
      "documento": "00.000.000/0001-00",
      "mes": "06",
      "ano": "2026"
  }

  response = requests.post(url, json=payload, headers=headers)
  perfil_financeiro_data = response.json()
  ```

  ```php PHP theme={null}
  <?php
  $url = 'https://sandbox-api.databox360.com.br/api/perfil-financeiro';
  $data = [
      'documento' => '00.000.000/0001-00',
      'mes' => '06',
      'ano' => '2026'
  ];

  $options = [
      'http' => [
          'header' => [
              "Authorization: Bearer YOUR_JWT_TOKEN",
              "Content-type: application/json"
          ],
          'method' => 'POST',
          'content' => json_encode($data)
      ]
  ];

  $context = stream_context_create($options);
  $result = file_get_contents($url, false, $context);
  $perfil_financeiro_data = json_decode($result, true);
  ?>
  ```
</RequestExample>

<ResponseExample>
  ```json Success (200) theme={null}
  {
    "id": "75cb4884-4165-4a91-9c6d-dbdb402cf2be",
    "data": "28/08/2026 22:29:47",
    "consulta": {
      "tipoDoCliente": "PF",
      "documentoTipo": "CPF",
      "documento": "00000000191",
      "dataRelacionamento": "2005-08",
      "databaseConsultada": "2026-07",
      "consultadoEm": "2026-08-28T22:29:46.825Z",
      "valorContratadoIntervalo": {
        "minimo": 3164343.63,
        "maximo": 11221552.64
      },
      "resumo": {
        "principalCategoria": "Financiamentos",
        "principalCategoriaPercentual": 59.6,
        "relacionamentoAnos": 21,
        "operacoesQuantidade": 36,
        "instituicoesQuantidade": 10
      },
      "carteiraComposicao": [
        {
          "categoria": "Empréstimos",
          "percentual": 33.07
        },
        {
          "categoria": "Financiamentos",
          "percentual": 59.6
        },
        {
          "categoria": "Adiantamentos",
          "percentual": 0.14
        },
        {
          "categoria": "Arrendamento",
          "percentual": 0
        },
        {
          "categoria": "Garantias",
          "percentual": 0
        },
        {
          "categoria": "Outros Créditos",
          "percentual": 7.19
        }
      ],
      "vencimentoDistribuicao": [
        {
          "descricao": "Até 90 dias",
          "percentual": 29.94
        },
        {
          "descricao": "De 91 a 180 dias",
          "percentual": 34.41
        },
        {
          "descricao": "De 181 a 360 dias",
          "percentual": 8.13
        },
        {
          "descricao": "De 1 a 3 anos",
          "percentual": 26.59
        },
        {
          "descricao": "De 3 a 5 anos",
          "percentual": 0.93
        },
        {
          "descricao": "De 5 a 15 anos",
          "percentual": 0
        },
        {
          "descricao": "Acima de 15 anos",
          "percentual": 0
        },
        {
          "descricao": "Prazo indeterminado",
          "percentual": 0
        }
      ],
      "carteiraAVencerPorModalidade": [
        {
          "categoria": "Empréstimos",
          "percentual": 45.67
        },
        {
          "categoria": "Financiamentos",
          "percentual": 0.73
        },
        {
          "categoria": "Adiantamentos",
          "percentual": 0
        },
        {
          "categoria": "Arrendamento",
          "percentual": 0
        },
        {
          "categoria": "Garantias",
          "percentual": 0
        },
        {
          "categoria": "Outros Créditos",
          "percentual": 53.6
        }
      ],
      "carteiraVencidaPorModalidade": [
        {
          "categoria": "Empréstimos",
          "percentual": 41.64
        },
        {
          "categoria": "Financiamentos",
          "percentual": 58.36
        },
        {
          "categoria": "Adiantamentos",
          "percentual": 0
        },
        {
          "categoria": "Arrendamento",
          "percentual": 0
        },
        {
          "categoria": "Garantias",
          "percentual": 0
        },
        {
          "categoria": "Outros Créditos",
          "percentual": 0
        }
      ],
      "carteiraPrejuizoPorModalidade": [
        {
          "categoria": "Empréstimos",
          "percentual": 28.06
        },
        {
          "categoria": "Financiamentos",
          "percentual": 71.73
        },
        {
          "categoria": "Adiantamentos",
          "percentual": 0.21
        },
        {
          "categoria": "Arrendamento",
          "percentual": 0
        },
        {
          "categoria": "Garantias",
          "percentual": 0
        },
        {
          "categoria": "Outros Créditos",
          "percentual": 0
        }
      ],
      "insights": {
        "carteiraComposicao": "A carteira está concentrada principalmente em financiamentos (59,60%) e empréstimos (33,07%), que juntos somam quase toda a exposição.",
        "vencimentoDistribuicao": "34,41% da carteira vence de 91 a 180 dias, caracterizando um perfil de médio prazo.\nA exposição de curtíssimo prazo é moderada (29,94% em até 90 dias).",
        "carteiraAVencerPorModalidade": "Outros Créditos representa 53,60% dos compromissos futuros a vencer, seguida por empréstimos (45,67%).",
        "carteiraVencidaPorModalidade": "Do total vencido, 58,36% está concentrado em financiamentos, seguido por empréstimos com 41,64%.",
        "carteiraPrejuizoPorModalidade": "Do total baixado como prejuízo, 71,73% originou-se de financiamentos, com empréstimos representando 28,06%.\nHistórico de perda concentrado em financiamentos — relevante para análise de risco."
      },
      "ultimoVencimento": "2030-05"
    },
    "status": "sucesso",
    "url": "https://sandbox-perfil-financeiro.databox360.com.br/75cb4884-4165-4a91-9c6d-dbdb402cf2be",
    "versao": "1.0"
  }
  ```

  ```json Bad Request (400) theme={null}
  {
    "data": "28/08/2026 22:29:47",
    "campo": {
      "documento": "Documento inválido"
    },
    "messagem": "Erro de validação",
    "status": "erro",
    "versao": "1.0"
  }
  ```
</ResponseExample>

## Requisição

<ParamField body="documento" type="string" required>
  CPF ou CNPJ do cliente consultado.
</ParamField>

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

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

## Resposta

<ResponseField name="id" type="string" required>
  Identificador único da consulta.
</ResponseField>

<ResponseField name="data" type="string" required>
  Data e hora em que a consulta foi realizada.
</ResponseField>

<ResponseField name="consulta" type="object" required>
  Objeto que contém os dados do Perfil Financeiro.

  <Expandable title="consulta properties">
    <ResponseField name="consulta.tipoDoCliente" type="string" required>
      Tipo do cliente: `PF` para Pessoa Física ou `PJ` para Pessoa Jurídica.
    </ResponseField>

    <ResponseField name="consulta.documentoTipo" type="string" required>
      Tipo do documento consultado: `CPF` ou `CNPJ`.
    </ResponseField>

    <ResponseField name="consulta.documento" type="string" required>
      Documento do cliente consultado.
    </ResponseField>

    <ResponseField name="consulta.dataRelacionamento" type="string">
      Data de início do relacionamento de crédito no formato `YYYY-MM`.
    </ResponseField>

    <ResponseField name="consulta.databaseConsultada" type="string" required>
      Data-base utilizada na consulta no formato `YYYY-MM`.
    </ResponseField>

    <ResponseField name="consulta.consultadoEm" type="string" required>
      Data e hora da consulta no formato ISO 8601.
    </ResponseField>

    <ResponseField name="consulta.valorContratadoIntervalo" type="object">
      Intervalo estimado do valor contratado.

      <Expandable title="valorContratadoIntervalo properties">
        <ResponseField name="consulta.valorContratadoIntervalo.minimo" type="number">
          Valor mínimo estimado do intervalo.
        </ResponseField>

        <ResponseField name="consulta.valorContratadoIntervalo.maximo" type="number">
          Valor máximo estimado do intervalo.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="consulta.resumo" type="object" required>
      Síntese dos principais indicadores do Perfil Financeiro.

      <Expandable title="resumo properties">
        <ResponseField name="consulta.resumo.principalCategoria" type="string">
          Categoria com maior participação na carteira.
        </ResponseField>

        <ResponseField name="consulta.resumo.principalCategoriaPercentual" type="number">
          Participação percentual da principal categoria.
        </ResponseField>

        <ResponseField name="consulta.resumo.relacionamentoAnos" type="number">
          Tempo de relacionamento de crédito, em anos.
        </ResponseField>

        <ResponseField name="consulta.resumo.operacoesQuantidade" type="number">
          Quantidade total de operações identificadas.
        </ResponseField>

        <ResponseField name="consulta.resumo.instituicoesQuantidade" type="number">
          Quantidade de instituições com relacionamento identificado.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="consulta.carteiraComposicao" type="array" required>
      Distribuição percentual da carteira por categoria.

      <Expandable title="carteiraComposicao item properties">
        <ResponseField name="consulta.carteiraComposicao[].categoria" type="string">
          Categoria da operação de crédito.
        </ResponseField>

        <ResponseField name="consulta.carteiraComposicao[].percentual" type="number">
          Participação percentual da categoria na carteira.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="consulta.vencimentoDistribuicao" type="array" required>
      Distribuição percentual da carteira por faixa de vencimento.

      <Expandable title="vencimentoDistribuicao item properties">
        <ResponseField name="consulta.vencimentoDistribuicao[].descricao" type="string">
          Descrição da faixa de vencimento.
        </ResponseField>

        <ResponseField name="consulta.vencimentoDistribuicao[].percentual" type="number">
          Participação percentual da faixa de vencimento.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="consulta.carteiraAVencerPorModalidade" type="array" required>
      Distribuição percentual da carteira a vencer por categoria.

      <Expandable title="carteiraAVencerPorModalidade item properties">
        <ResponseField name="consulta.carteiraAVencerPorModalidade[].categoria" type="string">
          Categoria da operação de crédito.
        </ResponseField>

        <ResponseField name="consulta.carteiraAVencerPorModalidade[].percentual" type="number">
          Participação percentual da categoria na carteira a vencer.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="consulta.carteiraVencidaPorModalidade" type="array" required>
      Distribuição percentual da carteira vencida por categoria.

      <Expandable title="carteiraVencidaPorModalidade item properties">
        <ResponseField name="consulta.carteiraVencidaPorModalidade[].categoria" type="string">
          Categoria da operação de crédito.
        </ResponseField>

        <ResponseField name="consulta.carteiraVencidaPorModalidade[].percentual" type="number">
          Participação percentual da categoria na carteira vencida.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="consulta.carteiraPrejuizoPorModalidade" type="array" required>
      Distribuição percentual da carteira baixada como prejuízo por categoria.

      <Expandable title="carteiraPrejuizoPorModalidade item properties">
        <ResponseField name="consulta.carteiraPrejuizoPorModalidade[].categoria" type="string">
          Categoria da operação de crédito.
        </ResponseField>

        <ResponseField name="consulta.carteiraPrejuizoPorModalidade[].percentual" type="number">
          Participação percentual da categoria na carteira em prejuízo.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="consulta.insights" type="object" required>
      Textos interpretativos gerados a partir dos indicadores da consulta.

      <Expandable title="insights properties">
        <ResponseField name="consulta.insights.carteiraComposicao" type="string">
          Interpretação da composição da carteira.
        </ResponseField>

        <ResponseField name="consulta.insights.vencimentoDistribuicao" type="string">
          Interpretação da distribuição dos vencimentos.
        </ResponseField>

        <ResponseField name="consulta.insights.carteiraAVencerPorModalidade" type="string">
          Interpretação da carteira a vencer por modalidade.
        </ResponseField>

        <ResponseField name="consulta.insights.carteiraVencidaPorModalidade" type="string">
          Interpretação da carteira vencida por modalidade.
        </ResponseField>

        <ResponseField name="consulta.insights.carteiraPrejuizoPorModalidade" type="string">
          Interpretação da carteira em prejuízo por modalidade.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="consulta.ultimoVencimento" type="string">
      Data do último vencimento identificado, no formato `YYYY-MM`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="status" type="string" required>
  Status da requisição: `sucesso` ou `erro`.
</ResponseField>

<ResponseField name="url" type="string" required>
  URL exclusiva para acesso à visualização completa do Perfil Financeiro.
</ResponseField>

<Tip>
  Utilize o endereço retornado em `url` para abrir ou compartilhar a visualização completa da consulta.
</Tip>

<ResponseField name="versao" type="string" required>
  Versão da API.
</ResponseField>

<ResponseField name="messagem" type="string">
  Mensagem retornada quando o status da requisição for `erro`.
</ResponseField>

<ResponseField name="campo" type="object">
  Detalhes dos campos que apresentaram erro de validação.
</ResponseField>