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.

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.
2. Utilizando o listen: Permite monitorar campos específicos sem abrir mão de receber todos os dados possíveis do dataset.

---

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.

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).

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.

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.

---

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).

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.

---

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.

---

Endpoints da API de Monitoramento

A API de Monitoramento oferece funcionalidades de gerenciamento sem custos.