🖥️ API de Monitoramento
Para atender a processos que demandam uma maior recência das informações, sem comprometer restrições operacionais, a BigDataCorp desenvolveu a API de Monitoramento. Através dela, não é necessário realizar consultas frequentemente às APIs de Enriquecimento para ter acesso aos dados mais atualizados. Realizamos a verificação de todos os registros desejados e sempre que houver alguma alteração, ela será enviada diretamente para você.
Sobre o Serviço
Os dados públicos disponíveis na internet estão em constante atualização e passam por diversas alterações regularmente. A pluralidade de fontes de informação e suas diferentes finalidades, que abrangem desde registros cadastrais até indicadores econômicos e demográficos, levam a um cenário complexo e dinâmico. Isso torna o uso de dados atualizados um ponto crucial para a eficiência de processos de decisão.
O uso de dados atualizados é essencial em processos de análise de crédito e avaliação de risco, garantindo decisões mais assertivas e ajustadas à realidade atual, o que reduz a inadimplência e melhora a precisão nas políticas financeiras. Por outro lado, informações desatualizadas podem causar falhas críticas, levando a concessões indevidas de crédito e prejuízos financeiros, comprometendo a segurança e a eficácia das operações.
A BigDataCorp é uma referência em entregar informações atualizadas, diversas de nossas fontes são capturadas diariamente em um enforço contínuo para manter a qualidade e acurácia dos dados. No entanto, para que estas informações recentes sejam acessadas, é necessário realizar novas chamadas às APIs de Enriquecimento, o que pode ser um empecilho devido a fatores operacionais e orçamentários.
Para atender a processos que demandam uma maior recência das informações, sem comprometer restrições operacionais, a BigDataCorp desenvolveu a API de Monitoramento. Através dela, não é necessário realizar consultas frequentemente às APIs de Enriquecimento para ter acesso aos dados mais atualizados. Realizamos a verificação de todos as consultas as quais se deseja monitorar e sempre que houver alguma alteração, ela será enviada diretamente para você.
Usando a API
Para trazer maior versatilidade aos clientes, existem formas distintas de se utilizar a API de Monitoramento, cada uma visa atender a diferentes fluxos de processos. No entanto, todas elas partem da mesma etapa: a definição dos datasets, campos e parâmetros a serem monitorados.
Definindo os Dados de Monitoramento
Quando são realizadas chamadas às APIs de Enriquecimento da Plataforma de Dados, apenas dois campo são obrigatórios, o campo "Datasets" que contém uma lista de todos os conjuntos de dados desejados e o "Q" que deve receber os parâmetros de consulta necessários no processamento de cada dataset.
Exemplo:
POST: https://plataforma.bigdatacorp.com.br/pessoas
{
"Datasets": "basic_data, processes",
"Q": "doc{CPF}, returnupdates{false}"
}
Na chamada acima, dois datasets estão sendo solicitados, basic_data (Dados Cadastrais Básicos) e processes (Processos Judiciais e Administrativos). Por se tratarem de dados de pessoas, ambos os dataset requerem o parâmetro doc (documento de identificação - CPF). Já o returnupdates é um parâmetro exclusivo do dataset de processes que indica se as atualizações dos processos devem ou não ser entregues. Todas estas particularidades devem ser verificadas durante a escolha de quais dados utilizar.
Além dos datasets e parâmetros, é possível definir o Monitoramento de campos específicos de cada dataset. Isso pode ser feito de duas formas, através da seleção de campos ou do marcador listen. É importante se atentar à frequência de atualização de cada campo a ser monitorado. Por exemplo, o campo MotherName (nome da mãe) possivelmente nunca sofrerá alteração, o campo Age (idade) irá atualizar anualmente para indivíduos que estão vivos e o campo TaxIdStatusDate (data de última atualização do status do indivíduo na Receita Federal) pode atualizar de 3 em 3 meses.
Atenção
Alguns campos possuem uma frequência de atualização elevada, e podem não representar uma mudança significativa no dataset como um todo. Devido a isso, é recomendado que a seleção dos campos a serem monitorados seja feita de maneira meticulosa, a fim de evitar despesas inesperadas.
Utilizando a Seleção de Campos
Com a seleção de campos é possível limitar a resposta da API a apenas alguns os campos que são estritamente necessários ao seu processo, reduzindo o tráfego de dados e a latência das requisições.
Exemplos:
POST: https://plataforma.bigdatacorp.com.br/pessoas
Request:
{
"Datasets":"basic_data{TaxIdStatus, TaxIdStatusDate, MotherName, Age, BirthDate}",
"q":"doc{CPF}"
}
Response:
{
"Result": [
{
"MatchKeys": "doc{CPF}",
"BasicData": {
"BirthDate": "2001-03-05T00:00:00Z",
"Age": 23,
"MotherName": "LAI*****************UZA",
"TaxIdStatus": "REGULAR",
"TaxIdStatusDate": "2024-06-01T00:00:00"
}
}
],
"QueryId": "79c3cefb-1c23-41c1-9129-35211e846637",
"ElapsedMilliseconds": 54,
"QueryDate": "2024-09-18T18:00:43.2510993Z",
"Status": {
"basic_data": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {}
}
Request:
{
"Datasets": "processes{Lawsuits.Status}",
"q": "doc{CPF}, returnupdates{false}"
}
Response:
{
"Result": [
{
"MatchKeys": "doc{CPF}",
"Processes": {
"Lawsuits": [
{
"Status": "ARQUIVADO"
},
{
"Status": "EXTINTO"
},
{
"Status": "ARQUIVADO"
},
{
"Status": "TRANSITADO EM JULGADO"
},
{
"Status": "ARQUIVADO"
}
]
}
}
],
"QueryId": "4729a178-ce2b-4fcd-83dd-3f1e6441e2f8",
"ElapsedMilliseconds": 275,
"QueryDate": "2024-09-18T18:04:37.7339256Z",
"Status": {
"processes": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {}
}
Utilizando o Listen
Ao usar a marcação listen, é possível monitorar campos específicos sem abrir mão de receber todos os dados possíveis. Abaixo está um exemplo de uso dessa funcionalidade:
POST: https://plataforma.bigdatacorp.com.br/pessoas
Request:
{
"Datasets":"basic_data.listen(TaxIdStatus)",
"q":"doc{CPF}"
}
Response:
{
"Result": [
{
"MatchKeys": "doc{147*****682}",
"BasicData": {
"TaxIdNumber": "147*****682",
"TaxIdCountry": "BRAZIL",
"AlternativeIdNumbers": {},
"Name": "JOA******************TRO",
"Aliases": {
"CommonName": "JOA*****TRO",
"StandardizedName": "JOA*****************TRO"
},
"Gender": "M",
"NameWordCount": 4,
"NumberOfFullNameNamesakes": 1,
"NameUniquenessScore": 1,
"FirstNameUniquenessScore": 0.001,
"FirstAndLastNameUniquenessScore": 0.001,
"BirthDate": "2001-03-05T00:00:00Z",
"Age": 23,
"ZodiacSign": "PEIXES",
"ChineseSign": "Snake",
"BirthCountry": "BRASILEIRA",
"MotherName": "LAI*****************UZA",
"FatherName": "",
"MaritalStatusData": {},
"TaxIdStatus": "REGULAR",
"TaxIdOrigin": "RECEITA FEDERAL",
"TaxIdFiscalRegion": "MG",
"HasObitIndication": false,
"TaxIdStatusDate": "2024-06-01T00:00:00",
"TaxIdStatusRegistrationDate": "2015-01-12T00:00:00Z",
"CreationDate": "2018-10-22T00:00:00Z",
"LastUpdateDate": "2024-08-27T00:00:00Z"
}
}
],
"QueryId": "15df4b83-fff4-448e-a8ed-32bacc66d80b",
"ElapsedMilliseconds": 71,
"QueryDate": "2024-09-18T18:20:47.6033459Z",
"Status": {
"basic_data": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {}
}
Habilitando o Monitoramento
Definidos os dados necessários para o processo, o próximo passo é efetivamente habilitar o seu monitoramento. Todos os métodos para ativar uma inscrição de uma chamada retornam um SubscriptionId. O valor deste campo é responsável por identificar o registro de monitoramento de maneira única. Aconselhamos que esta informação seja armazenada, para que seja simples realizar alterações no registro posteriormente, caso necessário.
Atenção
Caso já exista um registro de monitoramento com os mesmos datasets e parâmetros, não será gerada uma nova inscrição.
Sempre verifique o status de retorno da API de Monitoramento através do campo
Status -> subscription -> Code. Chamadas bem sucedidas terão o código de retorno 0 ("OK").Garanta que o SubscriptionId seja salvo adequadamente, pois ele pode ser necessário posteriormente.
Habilitar Monitoramento na Chamada
A forma mais simples de habilitar o monitoramento, é informando esta opção no momento da chamada à API de enriquecimento através do campo Subscribe (increver-se). Em conjunto a este campo, é necessário informar o SubscriptionHooks, que será explicado em detalhes mais adiante.
POST: https://plataforma.bigdatacorp.com.br/pessoas
Request:
{
"Datasets": "basic_data.listen(TaxIdStatus)",
"q": "doc{147*****682}",
"Subscribe": true,
"SubscriptionHooks": "email{[email protected]}"
}
Response:
{
"Result": [
{
"MatchKeys": "doc{147*****682}",
"BasicData": {
"TaxIdNumber": "147*****682",
"TaxIdCountry": "BRAZIL",
"AlternativeIdNumbers": {},
"Name": "JOA******************TRO",
"Aliases": {
"CommonName": "JOA*****TRO",
"StandardizedName": "JOA*****************TRO"
},
"Gender": "M",
"NameWordCount": 4,
"NumberOfFullNameNamesakes": 1,
"NameUniquenessScore": 1,
"FirstNameUniquenessScore": 0.001,
"FirstAndLastNameUniquenessScore": 0.001,
"BirthDate": "2001-03-05T00:00:00Z",
"Age": 23,
"ZodiacSign": "PEIXES",
"ChineseSign": "Snake",
"BirthCountry": "BRASILEIRA",
"MotherName": "LAI*****************UZA",
"FatherName": "",
"MaritalStatusData": {},
"TaxIdStatus": "REGULAR",
"TaxIdOrigin": "RECEITA FEDERAL",
"TaxIdFiscalRegion": "MG",
"HasObitIndication": false,
"TaxIdStatusDate": "2024-06-01T00:00:00",
"TaxIdStatusRegistrationDate": "2015-01-12T00:00:00Z",
"CreationDate": "2018-10-22T00:00:00Z",
"LastUpdateDate": "2024-08-27T00:00:00Z"
}
}
],
"QueryId": "b9886b7d-c796-43ac-b97d-c5006a33ecd5",
"ElapsedMilliseconds": 88,
"QueryDate": "2024-09-18T19:07:56.7202733Z",
"Status": {
"basic_data": [
{
"Code": 0,
"Message": "OK"
}
],
"subscription": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {},
"SubscriptionId": "66eb250c116bae298ca4daee"
}
No exemplo acima, é habilitado o monitoramento do TaxIdStatus de um indivíduo no basic_data. Caso ocorra alteração neste campo, será enviado um e-mail para o solicitante com as informações atualizadas.
Habilitar Monitoramento com QueryId
Outra maneira de inscrever para alterações de um conjunto de dados é a partir do QueryId de uma chamada feita anteriormente.
Exemplo:
POST: https://plataforma.bigdatacorp.com.br/monitoramento/monitorar
Request:
{
"AccessToken": "<YOUR_ACCESS_TOKEN>",
"QueryId": "b9886b7d-c796-43ac-b97d-c5006a33ecd5",
"SubscriptionHooks": "email{[email protected]}"
}
Response:
{
"QueryId": "b9886b7d-c796-43ac-b97d-c5006a33ecd5",
"ElapsedMilliseconds": 88,
"QueryDate": "2024-09-18T19:07:56.7202733Z",
"Status": {
"subscription": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {},
"SubscriptionId": "66eb250c116bae298ca4daee"
}
Neste exemplo, os datasets e parâmetros desejados serão extraídos do registro relacionado ao QueryId informado. De modo que alterações do resultado desta chamada sejam enviadas ao email informado no campo SubscriptionHooks.
Recebendo os Dados Atualizados
Visando atender a diferentes fluxos e processos, existem três formas distintas em que a API de Monitoramento pode enviar suas atualizações. A forma de envio deve ser especificada no momento da inscrição, através do campo SubscriptionHooks. A seguir, serão explicados em detalhes cada um dos mecanismos de envio.
Atenção
O envio dos dados é feito para cada dataset incluido na assinatura. Ou seja, caso sejam informados 5 datasets na inscrição e houverem atualizações em 3 deles para um dado documento de entrada, ocorrerão 3 envios.
Recebendo Dados por E-mail
O mecanismo de e-mail é a forma mais simples de se obter as atualizações, não demanda de uma infraestrutura complexa e permite maior agilidade de integração. Por ser um método com automações restritas, recomendamos seu uso apenas para clientes que estejam monitorando uma quantidade reduzida de documentos ou que estejam realizando testes. Para usá-lo, basta informar o e-mail do parâmetro email do campo SubscriptionHooks.
POST: https://plataforma.bigdatacorp.com.br/monitoramento/monitorar
Request:
{
"AccessToken": "<YOUR_ACCESS_TOKEN>",
"QueryId": "b9886b7d-c796-43ac-b97d-c5006a33ecd5",
"SubscriptionHooks": "email{[email protected]}"
}
Response:
{
"QueryId": "b9886b7d-c796-43ac-b97d-c5006a33ecd5",
"ElapsedMilliseconds": 88,
"QueryDate": "2024-09-18T19:07:56.7202733Z",
"Status": {
"subscription": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {},
"SubscriptionId": "66eb250c116bae298ca4daee"
}
Recebendo Dados por Arquivos
O envio dos dados através de arquivos é recomendado quando se deseja receber as atualizações de forma consolidada, com alguma periodicidade predefinida (diária, semanal, mensal ou alguma outra). As informações atualizadas são armazenadas ao longo do tempo em arquivos, e em seguida enviadas através das credenciais definidas na chamada.
A tabela a seguir detalha os parâmetros possíveis ao usar o envio por arquivos:
| Parâmetro | É obrigatório? | Descrição | Valores Possíveis |
|---|---|---|---|
| file | Sim | Este campo deve conter a URL referente ao servidor de arquivos, informando obrigatoriamente o DNS e a porta de acesso, além do usuário e senha, caso necessário. | sftp://user:password@dns:port ou sftp://user:password@dns:port |
| remotefilepath | Não | Este parâmetro é utilizado para configurar o caminho no qual o arquivo gerado pelo processo de enriquecimento será armazenado no servidor. Caso não seja informado, o arquivo será enviado para raiz do diretório (/). | /path/to/folder/ |
| sshkeyauth | Não | É utilizado para possibilitar a autenticação via uma chave RSA (SSH) ao servidor SFTP. Caso seja true, é necessário habilitar a chave SSH da BigDataCorp para o caminho especificado. | true ou false |
Exemplos:
POST: https://plataforma.bigdatacorp.com.br/monitoramento/monitorar
{
"AccessToken": "<YOUR_ACCESS_TOKEN>",
"Api": "people",
"Datasets": "basic_data",
"q": "doc{xxxxxxxxxxx}",
"Subscribe": true,
"SubscriptionHooks": "file{sftp://user:password@dns:port},sshkeyauth{true},remotefilepath{/home/mydocs/}"
}
{
"AccessToken": "<YOUR_ACCESS_TOKEN>",
"Api": "people",
"Datasets": "basic_data",
"q": "doc{xxxxxxxxxxx}",
"Subscribe": true,
"SubscriptionHooks": "file{ftp://user:password@dns:port},remotefilepath{/home/mydocs/}"
}
Recebendo Dados por Webhook
Este mecanismo requere o desenvolvimento de uma API (Web Service) dedicada ao recebimento das atualizações de monitoramento. Os dados serão enviados de acordo com a frequência de atualização definida na API de Monitamento.
A tabela a seguir detalha os parâmetros possíveis ao usar o envio por webhook:
| Parâmetro | É obrigatório? | Descrição | Valores Possíveis |
|---|---|---|---|
| web | Sim | URL de acesso ao serviço de recebimento dos dados. | http://your-domain:1234 |
| postbacksecret | Não | Este é um campo de segurança que pode receber qualquer valor. Pode ser usado para validar que os dados enviados tem como origem a BigDataCorp. | YOUR_SECRET |
| authorizationtoken | Não | Chave de acesso utilizada no cabeçalho das requisições ao serviço de recebimento dos dados. Ela será enviada através da chave Authorization, com o prefixo Bearer. | YOUR_AUTH_TOKEN |
Exemplo:
POST: https://plataforma.bigdatacorp.com.br/monitoramento/monitorar
{
"AccessToken": "<YOUR_ACCESS_TOKEN>",
"Api": "people",
"Datasets": "basic_data",
"q": "doc{xxxxxxxxxxx}",
"Subscribe": true,
"SubscriptionHooks": "web{http://your-domain:1234}, postbacksecret{MY_SECRET}, authorizationtoken{YOUR_AUTH_TOKEN}"
}
Atenção
A BigDataCorp não se responsabiliza por falhas no serviço de recebimento dos dados. A cobrança será computada sempre que houver alterações identificadas, independente das falhas que venham a ocorrer no servidor/webhook definido para o monitoramento.
Cobrança
A cobrança pelo serviço de monitoramento inside sobre cada dataset que foi atualizado. O valor da atualização do dataset possui o mesmo custo de uma requisição padrão. As informações sobre precificação de datasets podem ser encontradas na página de Tabela de Preços Resumida.
Para ilustrar este mecanismo de cobrança, considere que um dado usuário possui 1000 inscrições ativas para os datasets de basic_data (preço base de R$ 0,05) e processes (preço base de R$ 0,07). Em um dado período de análise, houveram 100 alterações no basic_data e 200 em processes. A cobrança final deste período será de ´0,05 x 100 + 0,07 x 200 = R$ 14,00´.
Endpoints da API
A seguir serão descritos as funcionalidades disponíveis para uso na API de Monitoramento. Para obter mais detalhes sobre cada uma, acesse suas respectivas páginas de documentação.
Nota
Não há cobrança sobre o uso das funcionalidades descritas a seguir.
Esta funcionalidade permite listar todos os registros de monitoramento ativos para um domínio. Retorna informações sobre os parâmetros, datasets, APIs, dentre outras. Podem ser usados filtros e paginação para analisar volumes maiores de registros.
Este endpoint realiza a inscrição de monitoramento para um novo registro através do QueryId de uma chamada feita anteriormente.
Este método permite desabilitar um conjunto de registros de monitoramento assinados anteriormente. Isso pode ser feito através do SubscriptionId ou do QueryId da chamada original de monitoramento.
Nesta ferramenta, é possível verificar as mudanças entre diferentes resultados das APIs de Enriquecimento. Pode ser usado a partir de um SubscriptionId, de modo que será feita a comparação entre o registro mais recente e o mais antido referente a este monitoramento. Também é aceito o uso de dois identificadores de chamada (QueryId) para a realização da comparação.
Este recurso permite a configuração de informações importantes para o funcionamento adequado da API de Monitoramento, de acordo com as necessidades e preferências do usuário.
Tabela de Datasets Disponíveis para Monitoramento
A baixo está a tabela que descreve os datasets disponíveis para assinatura de monitoramento.
| API | Datasets |
|---|---|
| Pessoas | addresses, addresses_extended, apps_networks_and_platforms, awards_and_certifications, basic_data, business_relationships, circles_building, circles_college_class, circles_coworkers, circles_first_level_relatives, circles_household, circles_lawsuit_parties, circles_neighbors, circles_parents, circles_partners, circles_relatives, class_organization, collections, company_group_employed, company_group_family_ownership, company_group_ownership, company_group_sued, demographic_data, domains, election_candidate_data, electoral_data, emails_extended, financial_data, first_level_relatives_kyc, first_level_relatives_lawsuit_data, flags_and_features, interests_and_behaviors, kyc, media_profile_and_exposure, niches, occupation_data, online_ads, online_presence, passages, phones_extended, processes, profession_data, registration_data, related_people, related_people_addresses, related_people_emails, related_people_phones, social_assistance, university_student_data, vehicles |
| Empresas | activity_indicators, addresses, addresses_extended, basic_data, circles_employees, circles_first_level_owners, circles_legal_representatives, collections, company_group_building, company_group_documentroot, company_group_household, company_group_legal_representative, company_group_officialname, company_group_owners, company_group_tradename, domains, economic_group, economic_group_data, economic_group_first_level, economic_group_first_level_extended, economic_group_full, economic_group_full_extended, economic_group_kyc, economic_group_second_level, economic_group_second_level_extended, economic_group_third_level, economic_group_third_level_extended, employees_kyc, emails_extended, kyc, marketplace_data, media_profile_and_exposure, online_ads, owners_kyc, owners_lawsuits, passages, phones_extended, processes, registration_data, related_people_addresses, related_people_emails, related_people_phones, relationships, social_conscience, syndicate_agreements |
Nota
Caso você queira monitorar um dataset que não está presente na lista acima, contacte nossa Equipe de Suporte para avaliarmos a viabilidade da inclusão do dataset.
Casos de Uso
Onboarding de Clientes
A API de Monitoramento pode ser utilizada para acompanhar as informações de um indivíduo após este se inscrever em alguma plataforma ou serviço. Com isso, é possível garantir respostas ágeis a diversas mudanças, como falecimento, processos judicias, sanções, exposição política, entre outras. A seguir está um fluxograma simples descrevendo o passo-a-passo pra uso da API em um cenário como este.
Dúvidas Frequentes
- Somente datasets internos podem ser monitorados? Sim. Não é possível realizar o monitoramento de datasets com consultas externas, como nas APIs de Ondemand e Marketplace.
- Há cobrança sobre os endpoints da própria API de Monitoramento? Não. Os métodos fornecidos diretamente pela API de Monitoramento são de uso gratuito.
- Caso ocorra erro em algum dos datasets durante a chamada para ativar o monitoramento, o que pode ser feito? É possível refazer a chamada com os dataset que falharam e obter os dados desejados. Mesmo em casos de falha de um ou mais datasets, a inscrição pode ocorrer normalmente. A API de Monitoramento irá fazer novas tentativas de chamada e enviará os dados que forem extraídos com sucesso posteriormente.
Updated 3 days ago