Monitoramento de APIs

Manual de Integração — API Direct Data

---

Produto: Monitoramento de APIs — Acompanhamento de Alterações em Documentos

Base URL: /api/MonitorApp

Autenticação: Header Token (Guid)

Versão: 1.0

1. Visão Geral

1.1 Descrição do Produto

O Monitoramento de APIs é o produto Direct Data que executa periodicamente um conjunto de consultas configuradas para os documentos (CPFs e CNPJs) que o cliente deseja acompanhar. Sempre que uma execução detecta uma alteração em relação ao último resultado gravado, um evento é registrado e fica disponível para consulta — permitindo ao cliente reagir a mudanças cadastrais, fiscais, regulatórias etc. de forma automatizada.

Esta API permite ao cliente consultar as listas, entidades, monitoramentos e eventos já configurados na plataforma e pausar/retomar monitoramentos em três níveis de granularidade: por monitoramento individual, por entidade (todos os monitoramentos de um documento) ou por lista (todos os monitoramentos de um lote).

1.2 Conceitos-Chave

Antes de usar a API, é importante entender as quatro entidades centrais do produto:

1.3 Autenticação

Todos os endpoints exigem autenticação via header Token contendo o GUID de API emitido pela Direct Data para a sua empresa. Esse token é único por empresa e deve ser tratado como credencial sensível.

1.4 Estrutura de Resposta Padrão

Todas as respostas estendem o envelope ResponseMetaDataDTO. Independente de sucesso ou falha, o cliente sempre receberá os campos abaixo no corpo da resposta:

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 124,
  "dateTimeExecution": "08/05/2026 14:32:15",
  "error": null
}

1.5 Enumeradores

Status de Entidade Monitorada

Usado como filtro no parâmetro status de GetMonitoredEntities e também retornado nos campos status das listagens. Aceita o nome (ex: Available) ou o número correspondente.

Status Agregado de Lista

Retornado no campo status de GetLists:

1.6 Fluxo de Integração Recomendado

O fluxo padrão de uso da API combina os endpoints de descoberta (listas → entidades → APIs), consulta de eventos e controle (pause/resume), conforme o diagrama abaixo:

2. Endpoints GET — Consultas

2.1 GetLists

Retorna todas as listas (lotes) de monitoramento da empresa autenticada. Sem paginação — devolve todos os registros. Suporta filtros opcionais por listGuid (uma lista específica) e por intervalo de criação (dateFrom / dateTo).

Query Parameters

Exemplo de Requisição

GET /api/MonitorApp/GetLists?dateFrom=2026-01-01&dateTo=2026-05-31 HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 142,
  "dateTimeExecution": "08/05/2026 14:32:15",
  "error": null,
  "lists": [
    {
      "listGuid": "a1b2c3d4-...",
      "listName": "Fornecedores Críticos — 2026",
      "entityCount": 48,
      "apiCount": 5,
      "createdDate": "12/01/2026",
      "lastUpdated": "07/05/2026",
      "status": "Parcialmente Ativa"
    }
  ]
}

Campos da Resposta

2.2 GetMonitoredEntities

Retorna todas as entidades (documentos CPF/CNPJ) monitoradas pela empresa autenticada. Sem paginação. Suporta filtro opcional por status agregado.

Query Parameters

Exemplo de Requisição

GET /api/MonitorApp/GetMonitoredEntities?status=Paused HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 168,
  "dateTimeExecution": "08/05/2026 14:33:02",
  "error": null,
  "entities": [
    {
      "entityGuid": "b2c3d4e5-...",
      "entityName": "EXEMPLO TECNOLOGIA LTDA",
      "document": "12.345.678/0001-90",
      "apiCount": 3,
      "status": "Pausado",
      "origin": "Fornecedores Críticos — 2026"
    }
  ]
}

Campos da Resposta

2.3 GetEntityApis

Retorna todas as APIs configuradas para uma entidade específica, com frequência, período de vigência, status atual e datas de execução. Sem paginação.

Query Parameters

Exemplo de Requisição

GET /api/MonitorApp/GetEntityApis?entityGuid=b2c3d4e5-... HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 95,
  "dateTimeExecution": "08/05/2026 14:34:18",
  "error": null,
  "apis": [
    {
      "monitoringGuid": "c3d4e5f6-...",
      "apiName": "Sintegra - ES",
      "apiCategory": "Cadastro",
      "origin": "Fornecedores Críticos — 2026",
      "frequency": "Mensal",
      "interval": 30,
      "period": "1 ano",
      "lastExecution": "01/05/2026",
      "nextExecution": "31/05/2026",
      "status": "Disponível",
      "reason": null
    }
  ]
}

Campos da Resposta

2.4 GetMonitoringDetail

Retorna a visão completa de um único monitoramento configurado: dados da entidade e da API, configuração (frequência, período), histórico de execuções e eventos detectados. É o endpoint recomendado quando o cliente precisa exibir uma "tela de detalhe" de um monitoramento.

Query Parameters

Exemplo de Requisição

GET /api/MonitorApp/GetMonitoringDetail?monitoringGuid=c3d4e5f6-... HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 215,
  "dateTimeExecution": "08/05/2026 14:35:40",
  "error": null,
  "monitoringGuid": "c3d4e5f6-...",
  "entityGuid": "b2c3d4e5-...",
  "entityName": "EXEMPLO TECNOLOGIA LTDA",
  "document": "12.345.678/0001-90",
  "apiName": "Sintegra - ES",
  "apiCategory": "Cadastro",
  "origin": "Fornecedores Críticos — 2026",
  "listGuid": "a1b2c3d4-...",
  "frequency": "Mensal",
  "interval": 30,
  "period": "1 ano",
  "startDate": "12/01/2026",
  "endDate": "12/01/2027",
  "lastExecution": "01/05/2026",
  "nextExecution": "31/05/2026",
  "status": "Disponível",
  "reason": null,
  "executionHistory": [
    { "executionDate": "01/05/2026, 03:12", "result": "Sem alteração",       "status": "Sucesso" },
    { "executionDate": "01/04/2026, 03:08", "result": "Alteração detectada", "status": "Sucesso" },
    { "executionDate": "12/01/2026, 03:05", "result": "Primeira consulta",   "status": "Sucesso" }
  ],
  "events": [
    {
      "eventGuid": "d4e5f6a7-...",
      "eventDescription": "Situação cadastral alterada de ATIVA para SUSPENSA",
      "executionDate": "01/04/2026, 03:08"
    }
  ]
}

Campos da Resposta — Bloco Principal

Campos — executionHistory[]

Campos — events[]

2.5 GetMonitoringEvents

Retorna todos os eventos (alterações detectadas) de um único monitoramento, com filtro opcional por intervalo de execução. Útil para auditar o histórico de mudanças capturadas em uma API específica de uma entidade. Sem paginação.

Query Parameters

Exemplo de Requisição

GET /api/MonitorApp/GetMonitoringEvents?monitoringGuid=c3d4e5f6-...&dateFrom=2026-01-01 HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 88,
  "dateTimeExecution": "08/05/2026 14:36:12",
  "error": null,
  "events": [
    {
      "eventGuid": "d4e5f6a7-...",
      "entityGuid": "b2c3d4e5-...",
      "entityName": "EXEMPLO TECNOLOGIA LTDA",
      "apiName": "Sintegra - ES",
      "apiCategory": "Cadastro",
      "eventDescription": "Situação cadastral alterada de ATIVA para SUSPENSA",
      "executionDate": "01/04/2026, 03:08"
    }
  ]
}

Campos — events[]

2.6 GetEntityEvents

Retorna todos os eventos detectados em todos os monitoramentos de uma entidade, com filtro opcional por intervalo de execução. Útil para construir uma timeline consolidada de alterações de um documento. Sem paginação.

Query Parameters

Exemplo de Requisição

GET /api/MonitorApp/GetEntityEvents?entityGuid=b2c3d4e5-... HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000

Estrutura da resposta idêntica a GetMonitoringEvents — o array events[] agrega eventos de todas as APIs configuradas para a entidade no período consultado.

2.7 GetListEvents

Retorna todos os eventos detectados em todas as entidades de uma lista, com filtro opcional por intervalo de execução. É a visão mais ampla do produto — útil para gerar um relatório consolidado de alterações de um lote inteiro. Sem paginação.

Query Parameters

Exemplo de Requisição

GET /api/MonitorApp/GetListEvents?listGuid=a1b2c3d4-...&dateFrom=2026-04-01&dateTo=2026-04-30 HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000

Estrutura da resposta idêntica a GetMonitoringEvents — o array events[] agrega eventos de todas as entidades e APIs da lista no período consultado.

3. Endpoints PATCH — Pause & Resume

Os endpoints de pausa e retomada permitem suspender e religar a execução de monitoramentos em três níveis de granularidade: por monitoramento individual, por entidade ou por lista. Todos retornam o mesmo envelope ResponseAPIMonitorAppToggleDTO, com a quantidade de monitoramentos afetados e uma mensagem descritiva.

Estrutura de Resposta dos PATCH (comum)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 95,
  "dateTimeExecution": "08/05/2026 14:42:18",
  "error": null,
  "affectedCount": 3,
  "summary": "3 monitoramento(s) pausado(s) com sucesso."
}

3.1 PauseMonitoring

Pausa um único monitoramento de API configurada, identificado pelo monitoringGuid.

Body da Requisição

Exemplo de Requisição

PATCH /api/MonitorApp/PauseMonitoring HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000
Content-Type: application/json

{
  "monitoringGuid": "c3d4e5f6-..."
}

3.2 ResumeMonitoring

Retoma um único monitoramento previamente pausado.

Body da Requisição

Idêntico a PauseMonitoring.

Exemplo de Requisição

PATCH /api/MonitorApp/ResumeMonitoring HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000
Content-Type: application/json

{
  "monitoringGuid": "c3d4e5f6-..."
}

3.3 PauseEntity

Pausa todos os monitoramentos de uma entidade (CPF ou CNPJ). O campo affectedCount da resposta indica quantos monitoramentos foram pausados.

Body da Requisição

Exemplo de Requisição

PATCH /api/MonitorApp/PauseEntity HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000
Content-Type: application/json

{
  "entityGuid": "b2c3d4e5-..."
}

3.4 ResumeEntity

Retoma todos os monitoramentos previamente pausados de uma entidade.

Body da Requisição

Idêntico a PauseEntity.

Exemplo de Requisição

PATCH /api/MonitorApp/ResumeEntity HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000
Content-Type: application/json

{
  "entityGuid": "b2c3d4e5-..."
}

3.5 PauseList

Pausa todos os monitoramentos de uma lista (lote). O campo affectedCount da resposta indica o total de monitoramentos afetados — somando todas as APIs de todas as entidades da lista.

Body da Requisição

Exemplo de Requisição

PATCH /api/MonitorApp/PauseList HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000
Content-Type: application/json

{
  "listGuid": "a1b2c3d4-..."
}

3.6 ResumeList

Retoma todos os monitoramentos previamente pausados de uma lista.

Body da Requisição

Idêntico a PauseList.

Exemplo de Requisição

PATCH /api/MonitorApp/ResumeList HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000
Content-Type: application/json

{
  "listGuid": "a1b2c3d4-..."
}

4. Mapeamento de Erros por Endpoint

4.1 Estrutura do Erro

Quando uma requisição falha, o envelope ResponseMetaDataDTO retorna o campo error preenchido com o nome do campo problemático e a mensagem correspondente. O campo success será false e o status HTTP refletirá o tipo de falha.

// Exemplo de resposta 401 Unauthorized (token inválido)
{
  "success": false,
  "status": "Unauthorized",
  "elapsedTimeMs": 12,
  "dateTimeExecution": "08/05/2026 14:40:01",
  "error": {
    "fieldName": "Token",
    "message": "Token de acesso inválido. Verifique suas credenciais."
  }
}

// Exemplo de resposta 404 Not Found (Guid não pertence à empresa)
{
  "success": false,
  "status": "Not Found",
  "elapsedTimeMs": 28,
  "dateTimeExecution": "08/05/2026 14:40:14",
  "error": {
    "fieldName": "monitoringGuid",
    "message": "Monitoramento não encontrado para esta empresa."
  }
}

4.2 Endpoints GET

GetLists, GetMonitoredEntities

GET /api/MonitorApp/GetLists · GET /api/MonitorApp/GetMonitoredEntities

GetEntityApis, GetMonitoringDetail, GetMonitoringEvents, GetEntityEvents, GetListEvents

Endpoints GET que recebem um Guid obrigatório.

4.3 Endpoints PATCH

PauseMonitoring · ResumeMonitoring · PauseEntity · ResumeEntity · PauseList · ResumeList