Os parâmetros estruturam a consulta e orientam a Plataforma de Dados sobre quem localizar e qual conjunto de informações retornar.

Aqui você aprenderá:

A função de cada parâmetro (q, Datasets, Limit).

Como declarar chaves de identificação.

As diferenças entre chaves principais, alternativas e opcionais.

Quando e como combinar chaves.

As listas completas de chaves, por tipo.

Quando utilizar Limit.

Esses conceitos são essenciais para que as próximas páginas façam sentido.

⭐
Ao concluir esta seção, você saberá transformar parâmetros e chaves em consultas mais precisas, consistentes e alinhadas ao seu objetivo.

1️⃣ Parâmetros disponíveis

Parâmetro	Descrição	Tipo
`q`	Lista de chaves de busca da consulta, separadas por vírgula.	🛑 Obrigatório
`Datasets`	Lista de datasets retornados, podendo incluir modificadores.	🛑 Obrigatório
`Limit`	Limite máximo de entidades retornadas.	ℹ️ Opcional

2️⃣ Sobre o parâmetro `q`

O parâmetro q reúne as chaves de identificação enviadas para localizar uma entidade na Plataforma de Dados. Ele funciona como o “quem estou tentando encontrar” dentro da sua consulta.

Cada chave segue o formato: nome_da_chave{valor}. Abaixo um exemplo simples:

"q": "name{Maria Souza}"

❗️
O envio de q é obrigatório em todas as consultas.

🔑 Chaves de identificação

A Plataforma de Dados utiliza três tipos de chaves de identificação:

Chaves principais

Identificam a entidade de forma única (1:1).

Chaves alternativas

Permitem retornar mais de uma entidade.

Chaves complementares

Refinam a busca e aumentam a precisão.

A seguir, detalhamos cada grupo.

São identificadores que possuem relação 1:1 com a entidade consultada.

Chave Principal	Descrição	Exemplo	API
`doc`	Número de Identificação de Pessoa ou Empresa (CPF/CNPJ)	`doc{12345678900}`	Pessoa ou Empresa
`zipcode`	Código Postal	`zipcode{12345000}`	Endereço
`licenseplate`	Número da Placa	`licenseplate{ABC1D23}`	Veículo
`processnumber`	Número do Processo	`processnumber{10000000120258260302}`	Processo
`receiptnumber`	Número da Nota Fiscal	`receiptnumber{123456789}`	Nota Fiscal
`ean`	Número do Código de Barras	`ean{12345678890123}`	Produto

3️⃣ Sobre o parâmetro `Datasets`

O parâmetro Datasets informa quais conjuntos de dados devem ser retornados pela API. Ele funciona como o “o que quero receber dessa entidade”.

📘
Exemplos de datasets comuns: basic_data, kyc, processes
A lista completa de datasets fica na documentação específica de cada API, no menu lateral.

O parâmetro `Datasets` também permite personalizar a resposta da API:

Seleção de campos

Define quais campos de um dataset devem ser retornados.

Modificadores

Permite aplicar filtros, ordenação, paginação e outras regras ao retorno.

Múltiplos datasets

Permite combinar diferentes datasets em uma mesma chamada.

Essas funcionalidades são detalhadas na página “Personalizar retorno”.

4️⃣ Sobre o parâmetro `Limit`

O Limit controla o máximo de entidades retornadas quando a consulta não for suficientemente específica.

Use quando:

Não houver chave principal.

A busca puder retornar múltiplas ocorrências.

Você quiser limitar a quantidade de entidades retornadas.

ℹ️
Consultas que retornam múltiplas entidades são cobradas pela quantidade de entidades retornadas.

Exemplo:

{
  "Datasets": "basic_data",
  "q": "name{Joao da Silva}, birthdate{10-02-1995}, dateformat{dd-mm-yyyy}",
  "Limit": 5
}

5️⃣ Resumo prático

q → quem estou procurando
Datasets → o que quero receber
Limit → quantidade máxima de entidades que desejo receber, quando a chave de busca não for 1:1

Esses três parâmetros formam a base de todas as consultas da Plataforma de Dados.