Logs

Consulta de logs de auditoria e gerenciamento de configuração.

Endpoints

Método	Endpoint	Descrição	Permissão
GET	`/audit/api/v1/logs`	Listar logs de auditoria	`AUDIT_LOGS_READ`
GET	`/audit/api/v1/logs/resource/:type/:id`	Timeline de um recurso	`AUDIT_LOGS_READ`
GET	`/audit/api/v1/config`	Obter configuração atual	`AUDIT_LOGS_READ`
PUT	`/audit/api/v1/config/retention`	Configurar retenção	`AUDIT_CONFIG_MANAGE`
POST	`/audit/api/v1/cleanup`	Executar limpeza manual	`AUDIT_CONFIG_MANAGE`

Atributos do Log

Campo	Tipo	Descrição
`eventType`	string	Tipo completo do evento (ex: `iam.user.created`)
`action`	enum	Ação: `CREATE`, `UPDATE`, `DELETE`, `LOGIN`, `LOGOUT`, etc
`actorId`	string (UUID)	ID do ator que realizou a ação
`actorType`	enum	Tipo do ator: `user`, `system`, `api_client`
`resourceType`	string	Tipo do recurso afetado (ex: `users`, `products`)
`resourceId`	string (UUID)	ID do recurso afetado
`changes`	object	Objeto com `before` e `after`
`ipAddress`	string	Endereço IP da requisição
`userAgent`	string	User-Agent do cliente
`metadata`	object	Dados adicionais
`createdAt`	datetime	Timestamp do evento

Listar Logs de Auditoria

GET /audit/api/v1/logs

Lista logs de auditoria com suporte a paginação e filtros.

Query Parameters

Parâmetro	Tipo	Descrição
`page[number]`	integer	Número da pagina
`page[size]`	integer	Itens por pagina
`filter[actorId]`	UUID	Filtrar por ID do ator
`filter[resourceType]`	string	Filtrar por tipo de recurso
`filter[resourceId]`	UUID	Filtrar por ID do recurso
`filter[action]`	enum	Filtrar por ação
`filter[eventType]`	string	Filtrar por tipo de evento
`filter[dateFrom]`	datetime	Data inicial (ISO 8601)
`filter[dateTo]`	datetime	Data final (ISO 8601)

cURL
JavaScript

curl 'https://audit.stg.catalisa.app/audit/api/v1/logs?filter[action]=CREATE&filter[resourceType]=users&filter[dateFrom]=2024-01-01T00:00:00Z' \
  -H 'Authorization: Bearer SEU_TOKEN'

const params = new URLSearchParams({
  'filter[action]': 'CREATE',
  'filter[resourceType]': 'users',
  'filter[dateFrom]': '2024-01-01T00:00:00Z',
});

const response = await fetch(`https://audit.stg.catalisa.app/audit/api/v1/logs?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data, meta, links } = await response.json();

Response (200 OK)

{
  "data": [
    {
      "type": "audit-logs",
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "attributes": {
        "eventType": "iam.user.created",
        "action": "CREATE",
        "actorId": "550e8400-e29b-41d4-a716-446655440001",
        "actorType": "user",
        "resourceType": "users",
        "resourceId": "550e8400-e29b-41d4-a716-446655440002",
        "changes": {
          "after": {
            "email": "newuser@example.com",
            "name": "New User",
            "password": "***"
          }
        },
        "ipAddress": "192.168.1.1",
        "userAgent": "Mozilla/5.0 ...",
        "createdAt": "2024-01-15T10:30:00Z"
      },
      "links": {
        "self": "/api/v1/logs/550e8400-e29b-41d4-a716-446655440010"
      }
    }
  ],
  "meta": {
    "totalItems": 150,
    "totalPages": 8,
    "currentPage": 1,
    "itemsPerPage": 20
  },
  "links": {
    "self": "/api/v1/logs?page[number]=1&page[size]=20",
    "next": "/api/v1/logs?page[number]=2&page[size]=20",
    "last": "/api/v1/logs?page[number]=8&page[size]=20"
  }
}

Timeline de Recurso

GET /audit/api/v1/logs/resource/:type/:id

Obtém o histórico completo de ações em um recurso específico.

cURL
JavaScript

curl 'https://audit.stg.catalisa.app/audit/api/v1/logs/resource/users/550e8400-e29b-41d4-a716-446655440002' \
  -H 'Authorization: Bearer SEU_TOKEN'

const resourceType = 'users';
const resourceId = '550e8400-e29b-41d4-a716-446655440002';

const response = await fetch(`https://audit.stg.catalisa.app/audit/api/v1/logs/resource/${resourceType}/${resourceId}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();

// Exibir timeline
data.forEach(log => {
  console.log(`${log.attributes.createdAt}: ${log.attributes.action} by ${log.attributes.actorId}`);
});

Response (200 OK)

{
  "data": [
    {
      "type": "audit-logs",
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "attributes": {
        "eventType": "iam.user.created",
        "action": "CREATE",
        "actorId": "550e8400-e29b-41d4-a716-446655440001",
        "actorType": "user",
        "changes": {
          "after": {
            "email": "user@example.com",
            "name": "User Name"
          }
        },
        "createdAt": "2024-01-15T10:30:00Z"
      }
    },
    {
      "type": "audit-logs",
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "attributes": {
        "eventType": "iam.user.updated",
        "action": "UPDATE",
        "actorId": "550e8400-e29b-41d4-a716-446655440001",
        "actorType": "user",
        "changes": {
          "before": { "name": "User Name" },
          "after": { "name": "User Name Updated" }
        },
        "createdAt": "2024-01-15T11:00:00Z"
      }
    }
  ]
}

Obter Configuração

GET /audit/api/v1/config

Obtém a configuração atual de auditoria da organização.

cURL
JavaScript

curl 'https://audit.stg.catalisa.app/audit/api/v1/config' \
  -H 'Authorization: Bearer SEU_TOKEN'

const response = await fetch('https://audit.stg.catalisa.app/audit/api/v1/config', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Retenção: ${data.attributes.retentionDays} dias`);

Response (200 OK)

{
  "data": {
    "type": "audit-config",
    "id": "550e8400-e29b-41d4-a716-446655440020",
    "attributes": {
      "retentionDays": 365,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z"
    }
  }
}

Configurar Retenção

PUT /audit/api/v1/config/retention

Define o período de retenção de logs de auditoria.

Atributos

Campo	Tipo	Obrigatório	Descrição
`retentionDays`	integer	Sim	Dias de retenção (1-3650)

cURL
JavaScript

curl -X PUT 'https://audit.stg.catalisa.app/audit/api/v1/config/retention' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "retentionDays": 90
  }'

const response = await fetch('https://audit.stg.catalisa.app/audit/api/v1/config/retention', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    retentionDays: 90,
  }),
});

const { data } = await response.json();
console.log(`Nova retenção: ${data.attributes.retentionDays} dias`);

Response (200 OK)

{
  "data": {
    "type": "audit-config",
    "id": "550e8400-e29b-41d4-a716-446655440020",
    "attributes": {
      "retentionDays": 90,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T11:00:00Z"
    }
  }
}

Executar Limpeza Manual

POST /audit/api/v1/cleanup

Executa limpeza manual de logs expirados com base na política de retenção.

cURL
JavaScript

curl -X POST 'https://audit.stg.catalisa.app/audit/api/v1/cleanup' \
  -H 'Authorization: Bearer SEU_TOKEN'

const response = await fetch('https://audit.stg.catalisa.app/audit/api/v1/cleanup', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Logs removidos: ${data.attributes.deletedCount}`);
console.log(`Retenção aplicada: ${data.attributes.retentionDays} dias`);

Response (200 OK)

{
  "data": {
    "type": "cleanup-result",
    "attributes": {
      "organizationId": "550e8400-e29b-41d4-a716-446655440000",
      "deletedCount": 1500,
      "retentionDays": 90
    }
  }
}

Exemplos de Uso

Dashboard de Auditoria

// Buscar estatisticas de ações dos últimos 30 dias
async function getAuditStats() {
  const thirtyDaysAgo = new Date();
  thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);

  const actions = ['CREATE', 'UPDATE', 'DELETE', 'LOGIN'];
  const stats = {};

  for (const action of actions) {
    const response = await fetch(
      `https://audit.stg.catalisa.app/audit/api/v1/logs?filter[action]=${action}&filter[dateFrom]=${thirtyDaysAgo.toISOString()}&page[size]=1`,
      {
        headers: { 'Authorization': `Bearer ${token}` },
      }
    );
    const { meta } = await response.json();
    stats[action] = meta.totalItems;
  }

  return stats;
}

// Resultado: { CREATE: 150, UPDATE: 320, DELETE: 45, LOGIN: 890 }

Investigacao de Seguranca

// Buscar tentativas de acesso negado de um IP específico
async function investigateIP(ipAddress) {
  const response = await fetch(
    `https://audit.stg.catalisa.app/audit/api/v1/logs?filter[action]=ACCESS_DENIED`,
    {
      headers: { 'Authorization': `Bearer ${token}` },
    }
  );

  const { data } = await response.json();

  // Filtrar por IP (lado cliente)
  return data.filter(log => log.attributes.ipAddress === ipAddress);
}

Relatorio de Compliance

// Gerar relatorio de modificações em dados sensíveis
async function generateComplianceReport(startDate, endDate) {
  const resourceTypes = ['users', 'persons', 'products'];
  const report = [];

  for (const resourceType of resourceTypes) {
    const params = new URLSearchParams({
      'filter[resourceType]': resourceType,
      'filter[dateFrom]': startDate,
      'filter[dateTo]': endDate,
      'page[size]': '100',
    });

    const response = await fetch(
      `https://audit.stg.catalisa.app/audit/api/v1/logs?${params}`,
      {
        headers: { 'Authorization': `Bearer ${token}` },
      }
    );

    const { data, meta } = await response.json();

    report.push({
      resourceType,
      totalEvents: meta.totalItems,
      events: data.map(log => ({
        action: log.attributes.action,
        actorId: log.attributes.actorId,
        timestamp: log.attributes.createdAt,
        resourceId: log.attributes.resourceId,
      })),
    });
  }

  return report;
}

Monitoramento de Atividade de Usuário

// Ver todas as ações de um usuário específico
async function getUserActivity(userId) {
  const response = await fetch(
    `https://audit.stg.catalisa.app/audit/api/v1/logs?filter[actorId]=${userId}&page[size]=50`,
    {
      headers: { 'Authorization': `Bearer ${token}` },
    }
  );

  const { data } = await response.json();

  return data.map(log => ({
    action: log.attributes.action,
    resourceType: log.attributes.resourceType,
    resourceId: log.attributes.resourceId,
    timestamp: log.attributes.createdAt,
    ipAddress: log.attributes.ipAddress,
  }));
}

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	Parametros de filtro inválidos
400	`VALIDATION`	`retentionDays` fora do intervalo (1-3650)
403	`FORBIDDEN`	Sem permissão para acessar logs ou configuração
404	`NOT_FOUND`	Recurso nao encontrado (timeline)

Endpoints​

Atributos do Log​

Listar Logs de Auditoria​

Query Parameters​

Response (200 OK)​

Timeline de Recurso​

Response (200 OK)​

Obter Configuração​

Response (200 OK)​

Configurar Retenção​

Atributos​

Response (200 OK)​

Executar Limpeza Manual​

Response (200 OK)​

Exemplos de Uso​

Dashboard de Auditoria​

Investigacao de Seguranca​

Relatorio de Compliance​

Monitoramento de Atividade de Usuário​

Erros Comuns​

Endpoints

Atributos do Log

Listar Logs de Auditoria

Query Parameters

Response (200 OK)

Timeline de Recurso

Response (200 OK)

Obter Configuração

Response (200 OK)

Configurar Retenção

Atributos

Response (200 OK)

Executar Limpeza Manual

Response (200 OK)

Exemplos de Uso

Dashboard de Auditoria

Investigacao de Seguranca

Relatorio de Compliance

Monitoramento de Atividade de Usuário

Erros Comuns