API de Monitoramento

Visão Geral do Serviço

A API de Monitoramento foi desenvolvida pela BigDataCorp para atender a processos que exigem maior recência das informações sem incorrer em restrições operacionais. Diferentemente das APIs de Enriquecimento, onde consultas frequentes são necessárias para obter dados atualizados, a API de Monitoramento gerencia a verificação dos registros desejados, e qualquer alteração identificada é enviada diretamente ao cliente.

O uso de dados atualizados é fundamental para a eficiência dos processos de decisão, sendo especialmente crítico em análise de crédito e avaliação de risco, garantindo decisões mais assertivas, reduzindo a inadimplência e melhorando a precisão das políticas financeiras.

Apesar do esforço contínuo da BigDataCorp em manter a qualidade e acurácia dos dados, com muitas fontes sendo capturadas diariamente, o acesso contínuo a essas informações recentes via APIs de Enriquecimento pode se tornar um impedimento devido a fatores operacionais e orçamentários. A API de Monitoramento resolve essa complexidade.

Casos de Uso

A API de Monitoramento é valiosa em cenários que exigem respostas rápidas a mudanças no perfil de um indivíduo ou empresa. A seguir estão alguns casos de uso em que esta API pode ser aplicada:

• Onboarding e Manutenção Cadastral: Acompanhar as informações de um indivíduo após sua inscrição em uma plataforma ou serviço. Isso garante respostas ágeis a alterações como falecimento, processos judiciais, sanções ou exposição política, mantendo a base de clientes sempre atualizada.

• Prevenção à Fraude Contínua: Monitorar clientes para identificar alterações cadastrais suspeitas, como múltiplas mudanças de endereço em curto período ou inconsistências no status do documento (ex: CPF de titular falecido), que podem indicar roubo de identidade ou fraude.

• Gestão de Risco de Crédito: Acompanhar a saúde financeira de clientes e parceiros. Alterações em indicadores financeiros, novas dívidas (collections) ou o surgimento de processos judiciais (processes) podem acionar uma reavaliação automática do risco de crédito.

• Compliance e KYC Contínuo: Manter a conformidade regulatória (AML/PLD) monitorando continuamente clientes para mudanças no status de Pessoa Politicamente Exposta (PEP) ou inclusão em listas de sanções nacionais e internacionais, garantindo que a empresa esteja sempre em conformidade.

Definindo os Dados de Monitoramento

O primeiro passo para utilizar a API de Monitoramento, independentemente do fluxo de processo, é definir os datasets, campos e parâmetros a serem monitorados.

Estrutura de Consulta

Ao realizar chamadas às APIs de Enriquecimento da Plataforma de Dados, dois campos são obrigatórios:

1. Datasets: Uma lista de todos os conjuntos de dados desejados.
2. Q: Os parâmetros de consulta necessários para o processamento de cada dataset (ex: o parâmetro doc é obrigatório para datasets de pessoas).

Todas as particularidades dos parâmetros devem ser verificadas durante a escolha dos dados a serem utilizados. Para mais detalhes, consulte nossa página de Parâmetros de Consulta.

Atributos para Monitoramento

É possível definir o monitoramento de campos específicos dentro de cada dataset. A seleção de campos deve ser feita de maneira cuidadosa, visto que alguns campos possuem alta frequência de atualização, mas podem não representar uma mudança significativa no dataset como um todo, o que pode gerar custos inesperados.

O monitoramento de campos específicos pode ser feito de duas formas:

1. Utilizando a Seleção de Campos: Permite limitar a resposta da API apenas aos campos estritamente necessários ao processo, o que otimiza o tráfego de dados e reduz a latência das requisições. Para mais detalhes, acesse o guia de Selecionando Campos de Um Dataset.
2. Utilizando o listen: Permite monitorar campos específicos sem abrir mão de receber todos os dados possíveis do dataset. Clique aqui para navegar para os exemplos de uso da configuração de monitoramento com o listen.

❗️

Atenção

Por padrão, se não for utilizado o listen, todos os campos no retorno do dataset serão monitorados.

Habilitando o Monitoramento

Após a definição dos dados, o próximo passo é habilitar o monitoramento, o que resulta na geração de um SubscriptionId. Este valor identifica o registro de monitoramento de forma única e deve ser armazenado para futuras alterações, se necessário.

Atenção: Caso já exista um registro de monitoramento com os mesmos datasets e parâmetros, uma nova inscrição não será gerada. O status de retorno da API de Monitoramento deve ser verificado através do campo Status -> subscription -> Code; chamadas bem-sucedidas retornam o código 0 ("OK").

Existem três maneiras de ativar o monitoramento:

Habilitar Monitoramento na Chamada (Enriquecimento)

Esta é a forma mais direta, informando a opção no momento da chamada à API de enriquecimento através do campo Subscribe, juntamente com o SubscriptionHooks (o mecanismo de envio das atualizações).

Exemplo de Requisição:

POST: https://plataforma.bigdatacorp.com.br/pessoas

{
  "Datasets": "basic_data.listen(TaxIdStatus)",
  "q": "doc{147*****682}",
  "Subscribe": true,
  "SubscriptionHooks": "email{[email protected]}"
}

Exemplo de Resposta:

{
  "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

É possível inscrever-se para monitoramento a partir do <glossary:QueryId> de uma chamada realizada anteriormente. Neste caso, os datasets e parâmetros desejados são extraídos do registro original. O parâmetro Datasets pode ser enviado na requisição para editar as configurações extraídas do QueryId. É possível selecionar apenas datasets específicos para monitoramento ou sobrescrever as configurações de campos a serem monitorados (o parâmetro listen). Não é permitido alterar filtros, ordenação, limite ou seleção de campos.

Exemplo de Requisição:

POST: https://plataforma.bigdatacorp.com.br/monitoramento/monitorar

Request:

{
  "AccessToken": "<YOUR_ACCESS_TOKEN>",
  "QueryId": "b9886b7d-c796-43ac-b97d-c5006a33ecd5",
  "SubscriptionHooks": "email{[email protected]}"
}

Exemplo de Resposta:

{
  "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.

❗️

Atenção

Os QueryIds originados por requisições em lote não são aceitos para ativar o monitoramento.

Habilitar Monitoramento em Lote

É possivel habilitar o monitoramento para múltiplos documentos de uma só fez através da API de Processamento em Lote. Isso permite maior agilidade no processo e reduz a carga de trabalho necessário para o fluxo de ativação do monitoramento. Para realizar esse processamento, é necessário possuir o arquivo de entrada com os parâmetros de cada chamada, separados por linhas, que seja acessível através dos diferentes métodos aceitos pela API, como descrito aqui.

Exemplo de arquivo:

Doc
12345678910
15916512102
...

Exemplo de Requisição:

POST https://plataforma.bigdatacorp.com.br/lote/salvarDefinicao

Headers AccessToken: {{YOUR_ACCESS_TOKEN}}, TokenId: {{YOUR_TOKEN_ID}}

{
  "InputFileUrl": "file{ftp://user(:password)@dns(:port)}, remotefilepath{path_to_file_in_ftp}",
  "OutputFileUrl": "file{ftp://user(:password)@dns(:port)}, remotefilepath{path_for_file_to_be_saved_at}",
  "SubscriptionHooks": "file{ftp://user(:password)@dns(:port)}, remotefilepath{path_for_file_to_be_saved_at}",
  "InputFileDelimiter": ",",
  "InputFileHasHeader": true,
  "OutputFileFormat": "json",
  "InputKeysHeader": "Doc",
  "AutomaticallyStartQuerying": true,
  "CopyEmails": [
    "[email protected]"
  ],
  "APIName": "people",
  "Datasets": "basic_data.listen(TaxIdStatus), processes.listen(TotalLawsuits)",
  "QueryTemplate": "doc{{0}}, returnupdates{false}"
}

Exemplo de Resposta:

{
  "JobId": "761388a5-5c23-4cbf-9437-a8456339b0a2",
  "StatusCode": 0,
  "StatusMessage": "OK",
  "TotalExecutionTime": 1677,
  "RequestTimestamp": "2024-12-05T11:21:03.995435+00:00",
  "QueryId": "a2adf547-c9fa-4f08-828c-f4e2eb75b714"
}

A partir da requisição acima, será criada uma nova tarefa de enriquecimento em lote, que irá consultar todas as linhas do arquivo de entrada de acordo com o QueryTemplate, Datasets e Api informados. Clique aqui para visualizar a tabela com a descrição de cada um dos campos. É possível adicionar ou modificar parâmetros conforme necessário.

❗️

Atenção

O campo SubscriptionHooks deve ser informado para que o monitoramento seja habilitado.

Atualizações de Monitoramento

A forma de envio das atualizações deve ser especificada no momento da inscrição através do campo SubscriptionHooks, mas pode ser modificada posteriormente. O envio das atualizações é feito de forma periódica, sendo o padrão de 15 dias, ajustável conforme a necessidade e volume monitorado.

O envio dos dados é feito individualmente para cada dataset incluído na assinatura que sofreu alteração. Por exemplo, se houverem atualizações em 3 de 5 datasets monitorados para um documento, ocorrerão 3 envios.

Recebendo Atualizações por E-mail

Este é o mecanismo mais simples e ágil, pois dispensa infraestrutura complexa. Ao receber o e-mail, será fornecido um link para download de um arquivo compactado (ZIP) e protegido por senha, que também estará contida na mensagem, além do total de atualizações.

Recebendo Atualizações por Arquivos (FTP/SFTP)

Recomendado para recebimento consolidado das atualizações em periodicidade predefinida (diária, semanal, mensal, etc.). As informações são enviadas através das credenciais definidas na chamada, tipicamente para um servidor SFTP ou FTP.

Recebendo Atualizações por Webhook

Este mecanismo exige o desenvolvimento de uma API (Web Service) dedicada para o recebimento dos dados.

Se houver alguma mudança, os dados completos são enviados individualmente para cada dataset. A estrutura JSON enviada segue os mesmos padrões de retorno das APIs de Enriquecimento.

Formatos de Saída dos Dados de Monitoramento

Os formatos de saída variam dependendo do mecanismo de envio (E-mail/Arquivo ou Webhook), mas a estrutura dos dados atualizados segue o padrão JSON das APIs de Enriquecimento.

Formato de Arquivos (E-mail e FTP)

Para envios por E-mail ou Arquivos (FTP/SFTP), o formato de saída primário é um arquivo compactado (ZIP).

1. Arquivo Principal: O arquivo principal é gerado no formato ZIP, com o padrão de nomenclatura ID_USER_DOMAIN_DATE.ZIP.
2. Arquivos CSV: Neste formato, o arquivo ZIP conterá diversos arquivos CSV (Comma Separated Values) para diferentes conjuntos de dados. Este formato permite fácil visualização e tratamento dos dados atualizados. Um dataset pode necessitar de um ou mais arquivos para compreender todos os seus dados em formato tabular. Além dos arquivos com dados atualizados, também são entregues os seguintes arquivos:
   • Dicionário de Dados.csv: Descreve em detalhes cada coluna de dados.
   • {API}_Atualizações.csv: Contém as principais alterações encontradas para cada registro monitorado.
   • Arquivo Completo.xlsx: Arquivo de Excel com os dados de todos os arquivos CSV separados em abas. Ideal para uma pré-visualização manual dos dados.
3. Arquivos JSONL: Nesta configuração, o arquivo ZIP conterá, individualmente, os dados de atualização para cada dataset monitorado. Cada dataset monitorado será referente a um arquivo com a extensão TXT (exemplo: ID_USER_DOMAIN_DATE_DATASET.TXT). Dentro desses arquivos JSONL, cada linha corresponderá a um objeto JSON. Este objeto JSON replica exatamente a estrutura de dados fornecida pela API de enriquecimento para o respectivo dataset (ex: basic_data ou kyc). Este formato é ideal para permitir reaproveitamento das estruturas e tratamentos realizados dos retornos das APIs de enriquecimento.
4. Configuração de Formato: É possível configurar o formato do arquivo de saída para os envios de monitoramento através do endpoint /monitoramento/definirUsuario. O campo OutputFileFormat define o formato como CSV ou JSONL (padrão é CSV).

Clique aqui para mais ver mais detalhes acerca dos arquivos de saída.

Estrutura JSON para Webhook

Para o mecanismo de Webhook, os dados são enviados diretamente em JSON. O envio é feito de maneira individual, de modo que, se o monitoramento for referente a múltiplos datasets, apenas o dataset alterado será enviado por vez. Esta regra evita a redundância de dados que não sofreram alterações.

A estrutura JSON enviada segue os mesmos padrões de retorno das APIs de Enriquecimento da BigData Corp. Para um dataset de Pessoas (assumindo a chamada inicial de enriquecimento), a estrutura de retorno JSON será idêntica àquela esperada de uma requisição de enriquecimento bem-sucedida, mas limitada ao dataset que sofreu a atualização.

ℹ️

Nota

A estrutura JSON exata para um dataset específico deve ser verificada na documentação daquele dataset.

Cobrança

A cobrança pelo serviço de monitoramento incide sobre cada dataset que foi atualizado. O custo da atualização de um dataset é o mesmo de uma requisição padrão.

Exemplo: Se um usuário possui 1000 inscrições ativas para dois datasets (R$ 0,05 e R$ 0,07) e em um período ocorreram 100 alterações no primeiro e 200 no segundo, a cobrança total será de R$ 14,00 (0,05 x 100 + 0,07 x 200).

Observação: Não há cobrança sobre o uso dos endpoints de gerenciamento da própria API de Monitoramento (como listar, atualizar ou desabilitar).

Perguntas Frequentes

1. Datasets on-demand podem ser monitorados? Não, bloqueamos o monitoramento de datasets nas APIs de On-demand ou Marketplace.
2. Como sou cobrado pelo serviço? A cobrança incide sobre cada dataset que foi atualizado. O custo da atualização é o mesmo de uma requisição padrão para aquele dataset. Não há cobrança pelo uso dos endpoints de gerenciamento da API de Monitoramento (listar, atualizar, testar, etc.).
3. O que acontece se meu webhook ou servidor SFTP estiver indisponível? A responsabilidade de manter o serviço de recepção dos dados é do cliente. A cobrança será computada sempre que uma alteração for identificada e enviada, independentemente de falhas no serviço de destino.
4. Como posso testar minha configuração de monitoramento? Utilize o endpoint /monitoramento/testar. Ele permite simular e validar as configurações de envio (e-mail, webhook ou SFTP) a partir de um monitoramento ativo ou de uma consulta recente, sem custos (sujeito a um limite de 500 requisições mensais).
5. É possível alterar uma inscrição de monitoramento depois de criada? Sim. O endpoint /monitoramento/atualizar permite modificar os campos monitorados (a configuração do listen) e o mecanismo de envio (SubscriptionHooks).
6. Como posso parar de monitorar um registro? Utilize o endpoint /monitoramento/desabilitar. A desativação pode ser feita pelo SubscriptionId, QueryId da consulta original ou pela combinação de parâmetros da chamada (Api, Datasets e Parameters). Uma vez desabilitado, o monitoramento não pode ser reativado.
7. Qual a diferença entre usar a seleção de campos e o listen? A seleção de campos (ex: basic_data{TaxIdStatus}) limita o retorno da API apenas aos campos especificados, tanto na consulta inicial quanto nas atualizações. O listen (ex: basic_data.listen(TaxIdStatus)) monitora apenas as alterações nos campos especificados, mas, ao detectar uma mudança, envia o objeto completo do dataset na notificação.
8. Qual a frequência de envio das atualizações? O envio é periódico, com um padrão de 15 dias. Este intervalo pode ser ajustado conforme a necessidade e o volume de registros monitorados.
9. Como configuro a autenticação para meu webhook ou servidor SFTP?
   • Webhook: Utilize o parâmetro authorizationtoken no SubscriptionHooks para enviar um token de autenticação no cabeçalho da requisição.
   • SFTP: Para autenticação com chave pública, use sshkeyauth{true} no SubscriptionHooks e garanta que a chave pública da BigDataCorp esteja autorizada no seu servidor. Para usar uma chave privada, configure-a através do campo SftpPrivateKey no endpoint /monitoramento/definirUsuario.

Exemplos Práticos

A seguir são apresentados diversos exemplos práticos que podem ser utilizados na API de Monitoramento em diferentes fluxos de processos para atender necessidades específicas.

Exemplos para Habilitação de Monitoramento

Como descrito anteriormente, o monitoramento de um registro pode ser feito das seguintes formas: a partir de uma requisição a API de enriquecimento (Pessoas, Empresas ou Processos), em solicitação direta à API de Monitoramento ou através da API de Enriquecimento em Lote. Em todos os casos, é preciso determinar de antemão as configurações e parâmetros dos datasets, como no seguinte exemplo:

{
  "Datasets": "dataset_name.listen(Field_1, Field_2, ...)",
  "q": "doc{CPF/CNPJ}, parameter_1{}, parameter_2{}, ...",
  "Subscribe": true,
  "SubscriptionHooks": "<HOOKS>"
}

A seguir estão exemplos de configurações, que podem ser utilizadas como base para diferentes soluções.

1. Monitorar Dados Cadastrais Básicos de Pessoas:

Monitora status, nome de registro e nome social na Receita Federal através do dataset de Dados Cadastrais Básicos de Pessoas.

[POST] https://plataforma.bigdatacorp.com.br/pessoas

{
  "Datasets": "basic_data.listen(TaxIdStatus, Name, Aliases.SocialName)",
  "q": "doc{CPF}",
  "Subscribe": true,
  "SubscriptionHooks": "<HOOKS>"
}

2. Monitorar Exposição e Restrições de Pessoas:

Monitora indicadores de exposição política e presença em sanções com os dados de KYC e Compliance de Pessoas.

[POST] https://plataforma.bigdatacorp.com.br/pessoas

{
  "Datasets": "kyc.listen(IsCurrentlyPEP, IsCurrentlySanctioned)",
  "q": "doc{CPF}",
  "Subscribe": true,
  "SubscriptionHooks": "<HOOKS>"
}

3. Monitorar Utilização de Crédito de Pessoas:

Monitora os níveis de utilização de crédito a partir do dataset de Interesses e Comportamentos de Pessoas.

[POST] https://plataforma.bigdatacorp.com.br/pessoas

{
  "Datasets": "interests_and_behaviors.listen(Behaviors.CreditCardScore, Behaviors.CreditSeeker)",
  "q": "doc{CPF}",
  "Subscribe": true,
  "SubscriptionHooks": "<HOOKS>"
}

4. Monitorar Relacionamentos Econômicos de Pessoas:

Monitora a inclusão de novos relacionamentos empresariais e o término dos vínculos existentes no dataset de Relacionamentos Econômicos de Pessoas.

[POST] https://plataforma.bigdatacorp.com.br/pessoas

{
  "Datasets": "business_relationships.listen(TotalRelationships, BusinessRelationships.IsCurrentlyActive)",
  "q": "doc{CPF}",
  "Subscribe": true,
  "SubscriptionHooks": "<HOOKS>"
}

5. Monitorar Quadro Societário de Empresas:

Monitora a inclusão ou retirada de indivíduos do quadro societário de uma empresa com o dataset de Relacionamentos de Empresas.

[POST] https://plataforma.bigdatacorp.com.br/empresas

{
  "Datasets": "relationships.filter(relationshiptype=[QSA]).listen(TotalOwners, CurrentRelationships.RelatedEntityTaxIdNumber)",
  "q": "doc{CNPJ}",
  "Subscribe": true,
  "SubscriptionHooks": "<HOOKS>"
}

6. Monitorar Processos Judiciais de Empresas:

Monitora a captura de novos processos judicias referentes à empresa com o dataset de Processos Judiciais e Administrativos de Empresas.

[POST] https://plataforma.bigdatacorp.com.br/empresas

{
  "Datasets": "processes.listen(TotalLawsuits)",
  "q": "doc{CNPJ},returnupdates{false}",
  "Subscribe": true,
  "SubscriptionHooks": "<HOOKS>"
}

Exemplos de Hooks no Monitoramento

1. Recebimento via e-mail:

No exemplo a seguir, e definido um monitoramento com envio de atualizações para um único e-mail.

{
  "SubscriptionHooks": "email{[email protected]}"
}

2. Recebimento em múltiplos e-mails:

Neste exemplo, as atualizações serão enviadas para e e-mail principal e para dois e-mails adicionais que estarão em cópia.

{
  "SubscriptionHooks": "email{[email protected]}, copyemails{[email protected], [email protected]}"
}

3. Recebimento por webhook:

A configuração abaixo representa a forma mais simples de envios via webhook, em que é informado apenas a URL da API de recebimento. É importante que o protocolo seja HTTPS para permitir comunicação seguração entre os processos. Além disso, como não há autenticação, é necessário adicionar um bloqueio de firewall ou aplicação para aceitar apenas envios provenientes da BigDataCorp, que sempre envia as atualizações através do IP 52.5.51.103.

{
  "SubscriptionHooks": "web{https://your-domain.com.br/webhook/bigdata/monitoramento}"
}

4. Recebimento por webhook com autenticação:

Neste exemplo, temos o envio de atualizações configurado para um webhook autenticado, em que será enviado no cabeçalho da requisição HTTP a chave Authorization com valor Bearer <YOUR_AUTH_TOKEN>. O token informado fica armazenado de forma segura pela BigDataCorp e é acessado apenas no momento do envio de cada atualização.

{
  "SubscriptionHooks": "web{https://your-domain.com.br/webhook/bigdata/monitoramento}, authorizationtoken{YOUR_AUTH_TOKEN},authorizationmethod{Bearer}"
}

5. Recebimento em servidor SFTP:

O seguinte exemplo ilustra a configuração do envio via SFPT (SSH File Transfer Protocol). Neste caso, é necessário que o certificado SSH da BigDataCorp esteja instalado no servidor de destino.

{
  "SubscriptionHooks": "file{sftp://john:[email protected]:22},sshkeyauth{true},remotefilepath{/bigdata/monitoramento}"
}

ℹ️

Nota

A chave SSH da BigDataCorp é a seguinte:

Shell

---- BEGIN SSH2 PUBLIC KEY ----
Comment: "rsa-key-20200814"
AAAAB3NzaC1yc2EAAAABJQAAAQEAk3BBwvZWGEaEFAu+sz6ssIBQe+Bz0LB3ri+/
0PXTVOtjejpOmVbbZtzzTSv6jN/yNAP2mGHcDGF1jJsHQc95TC+VeTSDKovEweEX
TqiacgMk9D2tC3L3IDNbT6PjXLkMqm9lVenkHAqKoNCLoasBU5kL4u1PyE1N6lCZ
fo+lsIenmhT5QKZr/evn3CmF3UDNEjegzNNmMrQpiWVvs13Bc4CFpEHKUNKhBzP+
l+7IYx3Er1ge12Ylvgfc5F5MOVOGjnJbqL1xRaMRydzOUIlQtXu0phva/gYaTliA
kJ3STDZJBScmnIF2el5FuUir2NGnHiiazVa+4QOVXwThgRNAgQ==
---- END SSH2 PUBLIC KEY ----

6. Recebimento em servidor FTP:

O seguinte exemplo ilustra a configuração do envio via FPT (File Transfer Protocol).

{
  "SubscriptionHooks": "file{ftp://user:password@dns:port},remotefilepath{/path/to/file}"
}

Exemplos de Envios do Monitoramento

Quando uma alteração é detectada no campo monitorado (ex: TaxIdStatus), o Webhook recebe o objeto JSON completo daquele documento e dataset, seguindo a estrutura padrão da API de Enriquecimento (Pessoas, Empresas, etc).

1. Envio de Dados Cadastrais por Webhook:

O exemplo abaixo ilustra um envio de dados, via webhook, após detectada alteração de status na Receita Federal para um dado indivíduo.

{
    "Result": [
        {
            "MatchKeys": "doc{xxxxxxxxxxx}",
            "BasicData": {
                "TaxIdNumber": "xxxxxxxxxxx",
                "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": "PENDENTE DE REGULARIZACAO",
                "TaxIdOrigin": "RECEITA FEDERAL",
                "TaxIdFiscalRegion": "MG",
                "HasObitIndication": false,
                "TaxIdStatusDate": "2025-02-01T00:00:00",
                "TaxIdStatusRegistrationDate": "2015-01-12T00:00:00Z",
                "CreationDate": "2018-10-22T00:00:00Z",
                "LastUpdateDate": "2025-02-01T00:00:00"
            }
        }
    ],
    "Changes":[
      "O valor do campo 'BasicData.TaxIdStatus' mudou de 'REGULAR' para 'PENDENTE DE REGULARIZACAO'."
    ],
    "QueryId": "14cb8ed2-fd3c-46e1-a4f2-70f6dd6e8ff2",
    "ElapsedMilliseconds": 50,
    "QueryDate": "2025-02-17T17:56:24.3371934Z",
    "Status": {
        "basic_data": [
            {
                "Code": 0,
                "Message": "OK"
            }
        ]
    },
    "Evidences": {}
}

2. Envio de Atualizações em CSV por E-mail:

Em caso de envios por e-mail, quando houver atualizações, será gerado um arquivo compactado (ZIP) e compartilhada a URL para download pelo e-mail. A mensagem de e-mail enviada pela BigDataCorp tem como remetente o endereço [email protected]. E o corpo da mensagem é como o seguinte:

Atualizações de Monitoramento

Um novo arquivo de atualizações de monitoramento foi gerado para o usuário <USER>.

- Arquivo para download: https://files.bigdatacorp.com.br/go/ID_USER_DOMAIN_DATE.zip
- Senha: <SENHA>
- Total de Registros Monitorados: <NÚMERO>
- Total de Atualizações: <NÚMERO>
- Mudanças por dataset:
    - people.basic_data: <NÚMERO> (<PERCENTUAL>%)
    - people.kyc: <NÚMERO> (<PERCENTUAL>%)
    - [...]

[...]

Clique aqui para baixar um arquivo de exemplo.

3. Envio de Atualizações em JSONL por FTP:

Assim como no exemplo anterior, em envios por FTP, será gerado um arquivo compactado (ZIP). Neste exemplo, os arquivos estão no formato JSONL (JSON Lines). O arquivo será postado no caminho predefinido no SubscriptionHooks, como por exemplo bigdata/monitoramento. O arquivo principal terá o nome no padrão ID_USER_DOMAIN_DATE.zip e os arquivos internos ID_USER_DOMAIN_DATE_DATASET.txt. Neste mecanismo de envio, o arquivo ZIP não é protegido por senha.

Clique aqui para baixar um arquivo de exemplo.

Endpoints da API de Monitoramento

A API de Monitoramento oferece funcionalidades de gerenciamento sem custos.

Tabela de Datasets Disponíveis para Monitoramento

Abaixo está a tabela que descreve os datasets disponíveis para monitoramento.

ℹ️

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.