Orientações básicas

Os recursos relacionados a consultas permitem a criação de consultas na plataforma utilizando poucos parâmetros no corpo da requisição.

Autorização

Todos os endpoints de consultas exigem autorização do usuário através de um access token. Esse token deve ser enviado no cabeçalho Authorization no formato Authorization: Bearer <access_token>.

Requisição

Os parâmetros da consulta devem ser enviados no corpo da requisição em formato JSON, contendo obrigatoriamente o tipo de consulta type, o tipo de chave de busca key_type, o valor da chave de busca key_value e a lista contendo um ou mais conjuntos de dados datasets . Veja um exemplo a seguir:

{
	"type": "persons",
	"key_type": "cpf",
	"key_value": "***********",
	"filters": [
		{ "key_type": "birthdate", "key_value": "**/**/****" }
	],
	"datasets": [ "basic" ]
}

Chaves de busca

A chave de busca é o parâmetro a ser utilizado pela plataforma para localizar a entidade desejada, e possui um tipo key_type e um valor key_value. Os tipos de chaves de busca disponíveis variam de acordo com o conjunto de dados a ser consultado, e você pode verificar quais deles estão disponíveis diretamente na documentação do conjunto de dados em questão. Veja todos os tipos de chaves de busca disponíveis a seguir:

Entidade	Chave	Descrição	Exemplo
Pessoas	`cpf`	Número do CPF da pessoa a ser consultada, contendo exatamente 11 dígitos numéricos.	`00000000000`
Pessoas e empresas	`name`	Nome da entidade a ser consultada, preferencialmente completo e sem abreviações.	`XXXXX XXXXX XXXXX`
Pessoas e empresas	`phone`	Número do telefone da entidade a ser consultada, contendo exatamente 2 dígitos numéricos para o código de área, seguido de 10 dígitos numéricos para telefones fixos ou 11 dígitos numéricos para telefones móveis. Importante: o código de área deve ser inserido sem o zero, e telefones móveis devem obrigatoriamente conter o nono dígito.	`11999999999`
Pessoas e empresas	`email`	Endereço de e-mail da entidade a ser consultada, contento o nome de usuário, o caractere `@` e o nome do domínio.	`[email protected]`
Empresas	`cnpj`	Número do CNPJ da pessoa a ser consultada, contendo exatamente 14 dígitos numéricos.	`00000000000000`

Em breve, novas chaves de busca serão disponibilizadas em nossa API.

Filtros

Opcionalmente, é possível realizar a filtragem dos resultados de busca, através de uma lista de parâmetros adicionais do tipo key_type e key_value, enviados na matriz filters. A disponibilidade dos filtros varia de acordo com a combinação de tipo de entidade e chave de busca utilizada. Veja todos os filtros disponíveis para cada combinação de tipo de entidade e chave de busca:

Entidade	Chave	Filtro	Descrição	Exemplo
Pessoas	`name`	`mother_name`	Nome da mãe da pessoa a ser consultada, preferencialmente completo e sem abreviações.	`XXXXX XXXXX XXXXX`
Pessoas	`name`	`birthdate`	Data de nascimento da entidade a ser consultada, no formato `DD/MM/AAAA`.	`30/01/1990`
Pessoas	`name`	`address_street`	Logradouro de um endereço da entidade a ser consultada.	`XXXXX XXXXX XXXXX`
Pessoas	`name`	`address_number`	Número de um endereço da entidade a ser consultada.	`123`
Pessoas	`name`	`address_neighborhood`	Bairro de um endereço da entidade a ser consultada.	`XXXXX XXXXX XXXXX`
Pessoas	`name`	`address_city`	Cidade de um endereço da entidade a ser consultada.	`XXXXX XXXXX XXXXX`
Pessoas	`name`	`address_state`	Estado (UF) de um endereço da entidade a ser consultada, contendo exatamente dois caracteres.	`SP`
Pessoas	`name`	`cpf_masked`	Parte do número do CPF da pessoa consultada, inserindo o caractere `*` na posição onde os dígitos são desconhecidos.	`*456789`

Retorno

O retorno das requisições aos endpoints de consultas seguem um padrão unificado, onde:

O campo status contém um código de resposta, mensagem descritiva e detalhes sobre o retorno (sempre que aplicável). Para mais informações sobre códigos e mensagens de retorno, visite a página códigos de retorno.
O campo data contém o resultado da requisição, onde:
- Em caso de sucesso, irá retornar as informações relacionadas à requisição.
- Em caso de falha na requisição, irá retornar vazio.
- Se ocorrer uma falha isolada na consulta a um dos conjuntos de dados requisitados, o respectivo objeto de resposta poderá conter um elemento error com a descrição do problema. Isso não impede o retorno bem-sucedido dos demais conjuntos de dados da requisição.

Exemplos de retorno

{
  "status": {
    "code": 4000,
    "message": "Success",
    "details": ""
  },
  "data": {
    "basic": { ... }
  }
}

{
  "status": {
    "code": 4000,
    "message": "Success",
    "details": ""
  },
  "data": {
    "basic": {
      "error": "Internal error"
    },
    "phones": { ... },
    "emails": { ... },
    "addresses": { ... }
  }
}

{
  "status": {
    "code": 4001,
    "message": "Authorization error",
    "details": "Access token invalid, expired or revoked"
  },
  "data": { }
}