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

# Datasets e preços

> Liste os datasets disponíveis, preços aplicados e, quando necessário, a estrutura completa de retorno.

Retorna os datasets disponíveis para um tipo de consulta, já considerando o preço final aplicado para a conta autenticada.

Use este endpoint para montar seletores de datasets, calcular estimativas de custo e entender quais campos cada dataset pode retornar.

Por padrão, a API retorna a visualização completa. Para respostas menores, use `view=simple`.

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "message": "Datasets retornados com sucesso.",
    "result": {
      "target": "person",
      "currency": "BRL",
      "view": "simple",
      "datasets": [
        {
          "id": "person_basic_data",
          "name": "Dados básicos",
          "price": 0.05,
          "active": true,
          "debit_only_if_found": false
        }
      ]
    }
  }
  ```

  ```json 200 theme={null}
  {
    "code": 200,
    "message": "Datasets retornados com sucesso.",
    "result": {
      "target": "person",
      "currency": "BRL",
      "view": "complete",
      "datasets": [
        {
          "id": "person_basic_data",
          "name": "Dados básicos",
          "price": 0.05,
          "active": true,
          "debit_only_if_found": false,
          "description": "Informações cadastrais consolidadas do CPF consultado.",
          "source": "database",
          "additional_fields": {},
          "struct_type": "object",
          "struct": {
            "name": {
              "type": "string",
              "description": "Nome da pessoa consultada."
            },
            "birth_date": {
              "type": "date",
              "description": "Data de nascimento."
            },
            "tax_id": {
              "type": "string",
              "description": "CPF consultado."
            }
          },
          "time": 1.2
        }
      ]
    }
  }
  ```

  ```json 400 theme={null}
  {
    "code": 400,
    "message": "Tipo de consulta inválido."
  }
  ```

  ```json 401 theme={null}
  {
    "code": 401,
    "message": "Credencial da API inválida."
  }
  ```

  ```json 403 theme={null}
  {
    "code": 403,
    "message": "A credencial da API não possui permissão para este recurso."
  }
  ```
</ResponseExample>

## Parâmetros

<ParamField path="target" type="string" required placeholder="person">
  Tipo de consulta usado para listar os datasets disponíveis.
</ParamField>

Valores aceitos para `target`:

| Valor     | Descrição                    |
| --------- | ---------------------------- |
| `person`  | Datasets de pessoa física.   |
| `pf`      | Alias de `person`.           |
| `company` | Datasets de pessoa jurídica. |
| `pj`      | Alias de `company`.          |
| `process` | Datasets processuais.        |
| `vehicle` | Datasets veiculares.         |

<ParamField query="view" default="complete" type="string" placeholder="simple">
  Formato da listagem retornada.
</ParamField>

Valores aceitos para `view`:

| Valor      | Descrição                                                                           |
| ---------- | ----------------------------------------------------------------------------------- |
| `simple`   | Retorna apenas dados mínimos para listagem e cálculo de estimativa.                 |
| `complete` | Retorna dados mínimos, descrição, origem, campos adicionais e estrutura de retorno. |

## Resposta

<ResponseField name="code" type="integer" required>
  Código da resposta da API.
</ResponseField>

<ResponseField name="message" type="string" required>
  Mensagem descritiva da resposta.
</ResponseField>

<ResponseField name="result" type="object" required>
  Objeto principal com o tipo de consulta, moeda, visualização usada e lista de datasets disponíveis.
</ResponseField>

## Estrutura de `result`

| Campo      | Tipo            | Descrição                                              |
| ---------- | --------------- | ------------------------------------------------------ |
| `target`   | `string`        | Tipo de consulta informado na rota.                    |
| `currency` | `string`        | Moeda usada nos preços retornados. Atualmente `BRL`.   |
| `view`     | `string`        | Visualização usada no retorno: `simple` ou `complete`. |
| `datasets` | `array<object>` | Lista de datasets disponíveis para o tipo de consulta. |

## Visualização simplificada

Use `view=simple` quando você só precisa montar uma lista de seleção ou calcular a estimativa da consulta.

```text theme={null}
GET /v1/search/datasets/person
Query: view=simple
```

### Estrutura de `result.datasets[]`

| Campo                 | Tipo      | Descrição                                                                                            |
| --------------------- | --------- | ---------------------------------------------------------------------------------------------------- |
| `id`                  | `string`  | Identificador do dataset. Use este valor no campo `datasets` das consultas.                          |
| `name`                | `string`  | Nome amigável exibido no painel ou na sua interface.                                                 |
| `price`               | `number`  | Preço final da consulta daquele dataset, já com regras comerciais aplicadas à conta autenticada.     |
| `active`              | `boolean` | Indica se o dataset está disponível para uso. Datasets inativos não devem ser enviados em consultas. |
| `debit_only_if_found` | `boolean` | Indica se a cobrança deve ocorrer apenas quando houver retorno útil.                                 |

## Visualização completa

Use `view=complete` quando você precisa exibir a descrição do dataset, campos adicionais exigidos ou a estrutura de retorno esperada.

```text theme={null}
GET /v1/search/datasets/person
Query: view=complete
```

### Estrutura de `result.datasets[]`

| Campo                 | Tipo      | Descrição                                                                                             |
| --------------------- | --------- | ----------------------------------------------------------------------------------------------------- |
| `id`                  | `string`  | Identificador do dataset. Use este valor no campo `datasets` das consultas.                           |
| `name`                | `string`  | Nome amigável exibido no painel ou na sua interface.                                                  |
| `price`               | `number`  | Preço final da consulta daquele dataset, já com regras comerciais aplicadas à conta autenticada.      |
| `active`              | `boolean` | Indica se o dataset está disponível para uso.                                                         |
| `debit_only_if_found` | `boolean` | Indica se a cobrança deve ocorrer apenas quando houver retorno útil.                                  |
| `description`         | `string`  | Descrição do dataset e do tipo de informação retornada.                                               |
| `source`              | `string`  | Origem operacional do dataset, como `database` ou `online`.                                           |
| `additional_fields`   | `object`  | Campos adicionais exigidos pelo dataset, quando houver.                                               |
| `struct_type`         | `string`  | Tipo da estrutura de retorno esperada, como `object`, `array` ou outro formato definido pelo dataset. |
| `struct`              | `object`  | Descrição dos campos que podem ser retornados pelo dataset.                                           |
| `time`                | `number`  | Tempo estimado de execução em segundos, quando disponível.                                            |

<Warning>
  Campos descritos em `struct` podem não ser retornados em todas as consultas. Alguns retornos dependem da disponibilidade da fonte, do documento consultado e das regras específicas de cada dataset.
</Warning>

## Campos adicionais

O campo `additional_fields` aparece apenas na visualização completa e informa parâmetros extras que devem ser enviados no objeto `additional` durante uma consulta.

Quando estiver vazio, o dataset não exige dados adicionais:

```json theme={null}
{
  "additional_fields": {}
}
```

Quando houver campos adicionais, a estrutura indica o tipo, rótulo e obrigatoriedade:

```json theme={null}
{
  "additional_fields": {
    "state": {
      "type": "string",
      "label": "UF",
      "required": true,
      "description": "Sigla da unidade federativa usada na consulta."
    }
  }
}
```

Campos comuns em `additional_fields`:

| Campo         | Tipo      | Descrição                                 |
| ------------- | --------- | ----------------------------------------- |
| `type`        | `string`  | Tipo esperado do valor.                   |
| `label`       | `string`  | Nome amigável para exibição em interface. |
| `required`    | `boolean` | Indica se o campo é obrigatório.          |
| `description` | `string`  | Explicação sobre o valor esperado.        |

## Estrutura de retorno do dataset

O campo `struct` aparece apenas na visualização completa e descreve os dados que podem ser retornados por cada dataset.

Exemplo:

```json theme={null}
{
  "struct": {
    "name": {
      "type": "string",
      "description": "Nome da pessoa consultada."
    },
    "birth_date": {
      "type": "date",
      "description": "Data de nascimento."
    },
    "tax_id": {
      "type": "string",
      "description": "CPF consultado."
    }
  }
}
```

Campos comuns dentro de `struct`:

| Campo         | Tipo     | Descrição                                         |
| ------------- | -------- | ------------------------------------------------- |
| `type`        | `string` | Tipo esperado do campo retornado.                 |
| `description` | `string` | Descrição do campo.                               |
| `label`       | `string` | Nome amigável, quando disponível.                 |
| `items`       | `object` | Estrutura de itens, quando o campo for uma lista. |
| `properties`  | `object` | Subcampos, quando o campo for um objeto composto. |

## Respostas esperadas

As respostas possíveis estão exemplificadas no painel lateral da página.

| Status | Quando ocorre                                                                                 |
| ------ | --------------------------------------------------------------------------------------------- |
| `200`  | A listagem foi retornada com sucesso.                                                         |
| `400`  | O `target` ou o `view` informado não é aceito.                                                |
| `401`  | A chave da API está ausente, inválida ou não pôde ser autenticada.                            |
| `403`  | A credencial não possui escopo de consulta ou o plano da conta não permite acesso ao recurso. |
| `422`  | Validação do parâmetro de rota ou query falhou no schema da API reference.                    |

## Como usar o retorno

1. Liste os datasets do tipo desejado usando `target`.
2. Use `view=simple` para montar listas e estimativas com resposta menor.
3. Use `view=complete` quando precisar de `description`, `additional_fields` ou `struct`.
4. Exiba apenas datasets com `active: true`.
5. Use `price` para calcular a estimativa da consulta.
6. Use `id` no campo `datasets` das requisições de consulta.
7. Se `additional_fields` tiver campos obrigatórios, colete esses dados antes de executar a consulta.

## Exemplo de uso em uma consulta

Após obter o dataset `person_basic_data`, envie o ID no campo `datasets` de uma consulta compatível:

```json theme={null}
{
  "taxid": "00000000000",
  "mode": "async",
  "datasets": ["person_basic_data"],
  "additional": {}
}
```

<Note>
  O CPF acima é fictício e serve apenas para demonstrar a estrutura da requisição. Em consultas reais ou testes sandbox, informe documentos válidos conforme o ambiente utilizado.
</Note>