Parâmetros de Consulta

Visão Geral

Todos os datasets da Plataforma de Dados necessitam que sejam informados um ou mais campos de entrada, que são inseridos no parâmetro q do objeto de requisição. Parâmetros de chamada como doc, zipcode e licenseplate são utilizados para a identificação da entidade a ser consultada, pois possuem uma relação 1:1. Outros parâmetros, como referencedate, radius e mothername, são utilizados para configurar o retorno dos datasets ou inserir informações para suporte aos processo internos de obtenção dos dados.

Os parâmetros dos datasets da Plataforma de Dados são divididos em quatro categorias:

• 🛑 OBRIGATÓRIOS: o campo ou um parâmetro equivalente deve sempre ser informado, caso contrário a chamada irá falhar. Em alguns datasets, há campos que podem são obrigatórios apenas em certas condições, como em Unidades Federativas específicas.
• ⚠️ SEMI-OBRIGATÓRIOS: são campos necessários no processo de consulta, mas a BigData Corp tentará obter os dados internamente se não forem informados na chamada.
•  ℹ️  OPCIONAIS : os campos podem ser passados ou não, porém as chances de resultados satisfatórios aumentam quando estes são utilizados na consulta.
• 🔑 CHAVES ALTERNATIVAS: são campos equivalentes à chave obrigatória de consulta no dataset, podendo ser utilizados de forma isolada para consultar a entidade desejada.

Os parâmetros de entrada devem ser concatenados por vírgula, como a seguir:

{
    "Datasets": "basic_data",
    "q": "doc{1234567890}, name{Joao da Silva}"
}

As chaves podem ser combinadas de acordo com a necessidade do usuário. Por padrão, caso mais de um "candidato" possível seja encontrado associado às informações de entrada, a API retornará apenas um dos candidatos encontrados. Para sempre receber uma quantidade específica de candidatos, deve ser usado o parâmetro Limit, como no exemplo abaixo, que contém uma requisição por nome e data de nascimento:

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

CUIDADO: O preço da consulta é contabilizado por entidade retornada para cada dataset consultado. Se, em uma pesquisa com chaves alternativas, forem encontradas e retornadas 2 entidades diferentes, o custo será o valor dos datasets selecionados multiplicado por 2.

Chaves Principais por Entidade

Cada uma das entidades de consulta das APIs apresenta uma chave principal padrão. Abaixo está um tabela com a descrição de cada uma dessas chaves e sua(s) entidade(s).

Chaves Alternativas de Consulta

Para o caso de consultas por pessoas ou empresas, entendemos que você nem sempre terá o documento para utilizar como chave. Por isso, a BigData Corp desenvolveu uma ferramenta que possibilita a obtenção do documento de identificação a partir de campos alternativos. A tabela a seguir apresenta os campos alternativos aceitos para substituir o parâmetro doc. Pelo menos um deles deve estar preenchido dentro do parâmetro q para que uma busca seja bem sucedida.

Nota: Essa ferramenta é usada apenas nas APIs de Pessoas, Empresas e OnDemand. As APIs de Produtos e Endereços também possibilitam o uso de chaves alternativas de consulta, como descrito em seus respectivos datasets.

Exemplos de Uso

A seguir estão exibidos alguns exemplos de uso para as chaves alternativas de consulta, que fazem uso de integração com o serviço de DocFinder da BigDataCorp.

Exemplo com Documento Parcial

O exemplo abaixo é utilizado para obter os dados básicos de uma companhia através da API de Empresas sem saber de antemão a razão social ou CNPJ exatos. Para isso, é utilizado o parâmetro partialdoc, que possibilita a busca de documentos que correspondam exatamente à posição dos caracteres informados, onde os asteriscos (*) atuam como curingas (ex: partialdoc{***753238**} busca correspondência a partir do quarto caractere). Caso seja utilizado o parâmetro PartialDocExactMatch como false, a API relaxa essa regra, de modo que os números da máscara ainda precisam estar contidos no documento, mas não necessariamente na posição exata. Após aplicar esse filtro mais flexível pela máscara, a API utiliza o nome informado (namematch) como critério de prioridade para ordenar os resultados encontrados.

{
    "Datasets": "basic_data",
    "q": "name{bigdata corp},partialdoc{*8768627******}"
}

{
    "Datasets": "basic_data",
    "q": "name{bigdata corp},partialdoc{8768627},partialdocexactmatch{false}"
}

Exemplo com Telefone

O exemplo a seguir pode ser utilizado tanto na API de Pessoas quanto de Empresas para obter possíveis documentos relacionados a um número de telefone específico.

{
    "Datasets": "basic_data",
    "q": "phone{5511999999999}"
}

Parâmetros Opcionais

Além dos parâmetros descritos anteriormente, as APIs da Plataforma de Dados permitem a utilização de diversos outros parâmetros para se chegar a um resultado final mais assertivo, que estão descritos abaixo.