Guia dos parâmetros que estruturam uma consulta na Plataforma.
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
qO 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:
Identificam a entidade de forma única (1:1).
Permitem retornar mais de uma entidade.
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 |
Quando o usuário não possuir uma chave principal, deve enviar ao menos uma chave alternativa. Por serem menos específicas, recomenda-se enviar duas ou mais chaves alternativas, ou combiná-las com chaves complementares.
Chaves alternativas (clique para expandir)
| Chave Alternativa | Descrição | Exemplo | API |
|---|---|---|---|
name | Nome da entidade | name{josé da silva} | Pessoa ou Empresa |
classnumber + classorganization | Número de registro em conselho de classe e nome da organização | classnumber{123456}, classorganization{CFMSP} | Pessoa |
nit | Número de Inscrição do Trabalhador (ou número do RG) | nit{123456789} | Pessoa |
rntrc | Número de Registro na ANTT | rntrc{12345678} | Pessoa ou Empresa |
domain | Domínio (URL do site) | domain{seudominio.com} | Pessoa ou Empresa |
name + partialdoc | Nome e informação parcial do documento de identificação da entidade | name{big corp}, partialdoc{*8768627*} | Pessoa ou Empresa |
Atenção:
Quanto mais chaves alternativas e complementares forem enviadas, maiores as chances de chegar à entidade correta.
Essas consultas podem retornar mais de uma entidade, e a cobrança considera a quantidade de entidades retornadas. Para limitar esse volume, utilize o parâmetro
Limit.
Chaves complementares não identificam sozinhas, mas ajudam a reduzir ambiguidades, aumentam a precisão e complementam as chaves alternativas.
Chaves complementares (clique para expandir)
| Chave | Descrição | Exemplo |
|---|---|---|
address | Endereço | address{Rua das Flores, 123} |
addresscore | Núcleo do endereço | addresscore{Rua das Flores} |
addressnumber | Número do endereço | addressnumber{123} |
addresstypology | Tipologia | addresstypology{casa} |
all | Retornar todas as movimentações | all{true} |
birthdate + dateformat | Data de nascimento e formato da data enviada | birthdate{01-10-1990}, dateformat{dd-mm-yyyy} |
brand | Marca dos produtos | brand{nike} |
buildingcode | Código postal / inscrição do prédio | buildingcode{123456} |
category | Categoria de produtos | category{eletronicos} |
cities | Lista de cidades | cities{São Paulo, Rio de Janeiro} |
city | Nome da cidade | city{Curitiba} |
cnae | Número da Atividade Econômica | cnae{6201501} |
complement | Complemento do endereço | complement{Apto 12} |
court | Tribunal | court{TRF3} |
distance | Tamanho do raio de pesquisa, em km | distance{10} |
dividaativa | Usar fonte de Dívida Ativa | dividaativa{true} |
ean | Número do código de barras | ean{7891234567890} |
email | E-mail adicional de entrada | email{[email protected]} |
enddate + dateformat | Data de término do período a ser consultado e o formato da data enviada | enddate{31-12-2025}, dateformat{dd-mm-yyyy} |
extended | Retornar todas as entidades | extended{true} |
fathername | Nome do pai | fathername{José Silva} |
floor | Andar do imóvel | floor{12} |
geocode | Código da área definida | geocode{1234567} |
group_level | Nível de relacionamentos | group_level{2} |
householdcode | Código postal / inscrição da casa | householdcode{987654} |
indigenouslandcode | Código da terra indígena | indigenouslandcode{TI1234} |
isbn | Código ISBN | isbn{978-3-16-148410-0} |
keywords | Palavras-chave | keywords{energia solar} |
latitude | Latitude | latitude{-23.5505} |
longitude | Longitude | longitude{-46.6333} |
minmatch | Similaridade mínima, em porcentagem | minmatch{80} |
mothername | Nome da mãe | mothername{Maria Souza} |
neighborhood | Bairro | neighborhood{Centro} |
nit | Número de Inscrição do Trabalhador | nit{123456789} |
op | Esferas de pesquisa | op{CIVIL} |
phone | Telefone adicional | phone{11999999999} |
placeofbirth | Local de nascimento | placeofbirth{Sorocaba} |
polygon | Lista de coordenadas que formam um polígono | polygon[-63.522601288613465, -2.0852205227110474, -62.91458204285954, -2.061274857038942, -63.070330815170884, -2.4697949735684355, -63.45385082496132, -2.5320904654187366] |
prefix | Consultar filiais e matrizes | prefix{true} |
radius | Raio de pesquisa (km) | radius{1} |
referencedate + dateformat | Data de referência para consulta, utilizada para consultas históricas (backtest), e o formato da data enviada. Se a data enviada for inválida, o retorno considerará a data atual. | referencedate{01-01-2020}, dateformat{dd-mm-yyyy} |
relationshiptype | Tipo de relacionamento | relationshiptype{coworker} |
returncvmprocesses | Retornar processos da CVM | returncvmprocesses{true} |
returnonlydifferentaddresses | Retornar endereços diferentes | returnonlydifferentaddresses{true} |
returnonlydifferentemails | Retornar e-mails diferentes | returnonlydifferentemails{true} |
returnonlydifferentphones | Retornar telefones diferentes | returnonlydifferentphones{true} |
returnonlyvalidemails | Retornar apenas e-mails válidos | returnonlyvalidemails{false} |
returnupdates | Retornar atualizações | returnupdates{true} |
rgexpeditiondate + dateformat | Data de emissão do RG | rgexpeditiondate{12-05-2010}, dateformat{dd-mm-yyyy} |
rgissuingagency | Agência emissora do RG | rgissuingagency{SSP} |
rgissuinguf | UF emissora do RG | rgissuinguf{SP} |
scnr | Código de Imóvel Rural | scnr{123456789} |
searchterms | Palavras-chave para busca | searchterms{mineração} |
startdate + dateformat | Data de início e formato da data informada | startdate{01-2020}, dateformat{mm-yyyy} |
state | Estado do Brasil | state{São Paulo} |
stateregistration | Inscrição Estadual | stateregistration{123456789} |
type | Tipo da consulta | type{list} |
uf | Unidade Federativa | uf{RJ} |
updateslimit | Limite de retorno das atualizações | updateslimit{100} |
withmatchrate | Utilizar taxa de similaridade | withmatchrate{true} |
year | Ano de referência | year{2023} |
zipcode | Código postal (CEP) | zipcode{01311000} |
Atenção:Em determinados datasets, chaves classificadas como complementares podem tornar-se obrigatórias em função de exigências específicas das fontes de dados.
Quando isso ocorrer, a obrigatoriedade será explicitamente indicada na seção "Chaves complementares relevantes" do respectivo dataset.
3️⃣ Sobre o parâmetro Datasets
DatasetsO 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,processesA 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:
Datasets também permite personalizar a resposta da API:Define quais campos de um dataset devem ser retornados.
Permite aplicar filtros, ordenação, paginação e outras regras ao retorno.
Permite combinar diferentes datasets em uma mesma chamada.
Essas funcionalidades são detalhadas na página “Personalizar retorno”.
4️⃣ Sobre o parâmetro Limit
LimitO 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 procurandoDatasets→ o que quero receberLimit→ 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.