imagy-audit — API Reference

Base URL

https://api.reimaginetech.io/api/v1

Todos los endpoints requieren autenticacion JWT excepto los internos (service-to-service).

Headers Estandar

Request Headers

Header	Obligatorio	Descripcion
`Authorization`	Si	`Bearer {JWT}`
`Content-Type`	Si (en body)	`application/json`
`Idempotency-Key`	Si (en POST)	UUID v4 generado por cliente

Response Headers

Header	Descripcion
`X-Request-Id`	ID de trazabilidad
`X-Total-Count`	Total de resultados (en listados)

Eventos de Auditoria

Consultar eventos

GET /audit/events
Authorization: Bearer {jwt}

Retorna eventos de auditoria del tenant con filtros opcionales. Los resultados estan paginados y ordenados por tiempo descendente (mas recientes primero).

Query params:

Parametro	Tipo	Descripcion
`page`	INT	Pagina (default: 1)
`page_size`	INT	Resultados por pagina (default: 50, max: 200)
`actor_id`	UUID	Filtrar por actor
`actor_uid`	STRING	Filtrar por UID del actor en la plataforma
`resource_id`	UUID	Filtrar por recurso
`resource_type`	STRING	Filtrar por tipo de recurso (credit, user, document, etc.)
`category_uid`	INT	Filtrar por categoria OCSF
`class_uid`	INT	Filtrar por clase OCSF
`activity_id`	INT	Filtrar por actividad OCSF
`severity_id`	INT	Filtrar por severidad minima (>= valor)
`time_from`	ISO8601	Inicio del rango temporal
`time_to`	ISO8601	Fin del rango temporal
`sort`	STRING	Campo de ordenamiento (default: `created_at:desc`)

Response 200:

json

{
  "data": [
    {
      "id": "evt-550e8400-e29b-41d4-a716-446655440001",
      "class_uid": 3001,
      "class_name": "Account Change",
      "category_uid": 3,
      "category_name": "Identity & Access Management",
      "activity_id": 1,
      "activity_name": "Create",
      "severity_id": 1,
      "severity": "Informational",
      "time": 1716048000000,
      "message": "User account created during credit origination",
      "actor": {
        "id": "act-uuid-001",
        "user_uid": "user-456",
        "user_name": "Sistema de Originacion",
        "user_type": "System"
      },
      "resource": {
        "id": "res-uuid-001",
        "resource_uid": "user-789",
        "resource_type": "user",
        "resource_name": "Juan Perez",
        "domain": "identity"
      },
      "src_endpoint": {
        "ip": "10.0.1.50",
        "name": "imagy-lending"
      },
      "metadata": {
        "version": "1.1.0",
        "product": {
          "name": "Imagy Platform",
          "vendor_name": "ReimagineTech",
          "version": "1.0.0"
        },
        "tenant_uid": "tenant-abc",
        "profiles": ["cloud", "financial_services"]
      },
      "unmapped": {
        "credit_id": "credit-123",
        "pipeline_step": "user_registration"
      },
      "created_at": "2026-05-18T10:00:00Z"
    }
  ],
  "metadata": {
    "request_id": "req-abc123",
    "timestamp": "2026-05-20T14:30:00Z",
    "pagination": {
      "page": 1,
      "page_size": 50,
      "total": 1247,
      "total_pages": 25
    }
  }
}

Obtener evento por ID

GET /audit/events/{id}
Authorization: Bearer {jwt}

Retorna el detalle completo de un evento de auditoria.

Response 200:

json

{
  "data": {
    "id": "evt-550e8400-e29b-41d4-a716-446655440001",
    "class_uid": 6001,
    "class_name": "Web Resources Activity",
    "category_uid": 6,
    "category_name": "Application Activity",
    "activity_id": 1,
    "activity_name": "Create",
    "severity_id": 2,
    "severity": "Low",
    "time": 1716134400000,
    "message": "Credit application submitted via digital wizard",
    "actor": {
      "id": "act-uuid-002",
      "user_uid": "system-origination",
      "user_name": "Origination Service",
      "user_type": "Service",
      "session_uid": "session-xyz"
    },
    "resource": {
      "id": "res-uuid-002",
      "resource_uid": "app-uuid-001",
      "resource_type": "application",
      "resource_name": "Solicitud Microcredito #1247",
      "domain": "imaglend"
    },
    "src_endpoint": {
      "ip": "10.0.2.30",
      "name": "imagy-lending"
    },
    "metadata": {
      "version": "1.1.0",
      "product": {
        "name": "Imagy Platform",
        "vendor_name": "ReimagineTech",
        "version": "1.0.0"
      },
      "tenant_uid": "tenant-abc",
      "profiles": ["cloud", "financial_services"]
    },
    "unmapped": {
      "credit_id": "credit-uuid-001",
      "product_id": "microcredito-30d",
      "amount": { "value": 300000, "currency": "COP" },
      "decision": "approved",
      "origin_channel": "digital"
    },
    "created_at": "2026-05-19T12:00:00Z"
  },
  "metadata": {
    "request_id": "req-def456",
    "timestamp": "2026-05-20T14:30:00Z"
  }
}

Response 404:

json

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Audit event not found",
    "request_id": "req-def456"
  }
}

Crear evento manual

POST /audit/events
Authorization: Bearer {jwt}
Idempotency-Key: {uuid}

Permite registrar un evento de auditoria custom. Util para acciones que no generan eventos de dominio automaticamente o para integraciones externas.

Request Body:

json

{
  "class_uid": 6001,
  "class_name": "Web Resources Activity",
  "category_uid": 6,
  "category_name": "Application Activity",
  "activity_id": 2,
  "activity_name": "Update",
  "severity_id": 3,
  "severity": "Medium",
  "message": "Manual override: credit limit increased by admin",
  "actor": {
    "user_uid": "admin-001",
    "user_name": "Carlos Admin",
    "user_type": "Admin"
  },
  "resource": {
    "resource_uid": "credit-uuid-050",
    "resource_type": "credit",
    "resource_name": "Credito #050",
    "domain": "imaglend"
  },
  "src_endpoint": {
    "ip": "192.168.1.100",
    "name": "admin-panel"
  },
  "unmapped": {
    "previous_limit": 500000,
    "new_limit": 1000000,
    "reason": "Client upgrade request approved by compliance"
  }
}

Response 201:

json

{
  "data": {
    "id": "evt-7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "class_uid": 6001,
    "class_name": "Web Resources Activity",
    "severity_id": 3,
    "message": "Manual override: credit limit increased by admin",
    "created_at": "2026-05-20T14:35:00Z"
  },
  "metadata": {
    "request_id": "req-ghi789",
    "timestamp": "2026-05-20T14:35:00Z"
  }
}

Reportes

Resumen por periodo

GET /audit/reports/summary
Authorization: Bearer {jwt}

Retorna un resumen agregado de actividad de auditoria para el periodo especificado.

Query params:

Parametro	Tipo	Descripcion
`time_from`	ISO8601	Inicio del periodo (requerido)
`time_to`	ISO8601	Fin del periodo (requerido)
`granularity`	STRING	`hour`, `day`, `week`, `month` (default: `day`)

Response 200:

json

{
  "data": {
    "period": {
      "from": "2026-05-01T00:00:00Z",
      "to": "2026-05-31T23:59:59Z"
    },
    "total_events": 15420,
    "by_severity": {
      "informational": 12300,
      "low": 2100,
      "medium": 850,
      "high": 150,
      "critical": 20
    },
    "by_category": [
      { "category_uid": 3, "category_name": "Identity & Access Management", "count": 8500 },
      { "category_uid": 6, "category_name": "Application Activity", "count": 5920 },
      { "category_uid": 2, "category_name": "Findings", "count": 1000 }
    ],
    "timeline": [
      { "date": "2026-05-01", "count": 487 },
      { "date": "2026-05-02", "count": 523 },
      { "date": "2026-05-03", "count": 412 }
    ]
  },
  "metadata": {
    "request_id": "req-jkl012",
    "timestamp": "2026-05-20T14:30:00Z"
  }
}

Top actores

GET /audit/reports/actors
Authorization: Bearer {jwt}

Retorna los actores con mayor volumen de actividad en el periodo.

Query params:

Parametro	Tipo	Descripcion
`time_from`	ISO8601	Inicio del periodo (requerido)
`time_to`	ISO8601	Fin del periodo (requerido)
`limit`	INT	Cantidad de actores a retornar (default: 10, max: 50)
`user_type`	STRING	Filtrar por tipo de actor (User, System, Service, Admin)

Response 200:

json

{
  "data": {
    "period": {
      "from": "2026-05-01T00:00:00Z",
      "to": "2026-05-31T23:59:59Z"
    },
    "actors": [
      {
        "actor_id": "act-uuid-010",
        "user_uid": "system-origination",
        "user_name": "Origination Service",
        "user_type": "Service",
        "event_count": 4520,
        "last_activity": "2026-05-20T14:00:00Z"
      },
      {
        "actor_id": "act-uuid-011",
        "user_uid": "admin-001",
        "user_name": "Carlos Admin",
        "user_type": "Admin",
        "event_count": 1230,
        "last_activity": "2026-05-20T13:45:00Z"
      },
      {
        "actor_id": "act-uuid-012",
        "user_uid": "system-identity",
        "user_name": "Identity Service",
        "user_type": "Service",
        "event_count": 980,
        "last_activity": "2026-05-20T14:10:00Z"
      }
    ]
  },
  "metadata": {
    "request_id": "req-mno345",
    "timestamp": "2026-05-20T14:30:00Z"
  }
}

Recursos mas activos

GET /audit/reports/resources
Authorization: Bearer {jwt}

Retorna los recursos con mayor cantidad de eventos asociados (mas accedidos o modificados).

Query params:

Parametro	Tipo	Descripcion
`time_from`	ISO8601	Inicio del periodo (requerido)
`time_to`	ISO8601	Fin del periodo (requerido)
`limit`	INT	Cantidad de recursos a retornar (default: 10, max: 50)
`resource_type`	STRING	Filtrar por tipo (credit, user, document, flow)
`domain`	STRING	Filtrar por dominio de origen

Response 200:

json

{
  "data": {
    "period": {
      "from": "2026-05-01T00:00:00Z",
      "to": "2026-05-31T23:59:59Z"
    },
    "resources": [
      {
        "resource_id": "res-uuid-020",
        "resource_uid": "credit-uuid-001",
        "resource_type": "credit",
        "resource_name": "Credito Microcredito #001",
        "domain": "imaglend",
        "event_count": 47,
        "last_activity": "2026-05-20T12:00:00Z"
      },
      {
        "resource_id": "res-uuid-021",
        "resource_uid": "user-uuid-100",
        "resource_type": "user",
        "resource_name": "Juan Perez",
        "domain": "identity",
        "event_count": 35,
        "last_activity": "2026-05-20T10:30:00Z"
      }
    ]
  },
  "metadata": {
    "request_id": "req-pqr678",
    "timestamp": "2026-05-20T14:30:00Z"
  }
}

Exportaciones

Crear job de exportacion

POST /audit/exports
Authorization: Bearer {jwt}
Idempotency-Key: {uuid}

Crea un job asincronico de exportacion. El job procesa los eventos que coinciden con los filtros y genera un archivo descargable.

Request Body:

json

{
  "format": "ocsf_json",
  "filters": {
    "time_from": "2026-05-01T00:00:00Z",
    "time_to": "2026-05-31T23:59:59Z",
    "category_uid": 3,
    "severity_id": 2
  }
}

Formatos soportados:

ocsf_json — Archivo JSON con array de eventos en formato OCSF completo
csv — Archivo CSV con columnas aplanadas (ideal para BI y reportes regulatorios)

Response 202:

json

{
  "data": {
    "id": "export-uuid-001",
    "status": "pending",
    "format": "ocsf_json",
    "filters": {
      "time_from": "2026-05-01T00:00:00Z",
      "time_to": "2026-05-31T23:59:59Z",
      "category_uid": 3,
      "severity_id": 2
    },
    "requested_at": "2026-05-20T14:35:00Z"
  },
  "metadata": {
    "request_id": "req-stu901",
    "timestamp": "2026-05-20T14:35:00Z"
  }
}

Consultar estado de exportacion

GET /audit/exports/{id}
Authorization: Bearer {jwt}

Retorna el estado actual del job de exportacion. Cuando el status es completed, incluye la URL de descarga.

Response 200 (en progreso):

json

{
  "data": {
    "id": "export-uuid-001",
    "status": "processing",
    "format": "ocsf_json",
    "filters": {
      "time_from": "2026-05-01T00:00:00Z",
      "time_to": "2026-05-31T23:59:59Z",
      "category_uid": 3,
      "severity_id": 2
    },
    "requested_at": "2026-05-20T14:35:00Z",
    "started_at": "2026-05-20T14:35:05Z"
  },
  "metadata": {
    "request_id": "req-vwx234",
    "timestamp": "2026-05-20T14:36:00Z"
  }
}

Response 200 (completado):

json

{
  "data": {
    "id": "export-uuid-001",
    "status": "completed",
    "format": "ocsf_json",
    "filters": {
      "time_from": "2026-05-01T00:00:00Z",
      "time_to": "2026-05-31T23:59:59Z",
      "category_uid": 3,
      "severity_id": 2
    },
    "file_url": "https://exports.reimaginetech.io/audit/export-uuid-001/events.json?token=presigned-token",
    "total_events": 8500,
    "requested_at": "2026-05-20T14:35:00Z",
    "started_at": "2026-05-20T14:35:05Z",
    "completed_at": "2026-05-20T14:37:30Z"
  },
  "metadata": {
    "request_id": "req-yza567",
    "timestamp": "2026-05-20T14:38:00Z"
  }
}

Endpoints Internos (Service-to-Service)

Estos endpoints son consumidos por otros microservicios de la plataforma para registrar eventos de auditoria directamente, sin pasar por RabbitMQ.

Registrar evento de auditoria (interno)

POST /internal/audit/record
X-Service-Auth: {service_token}

Endpoint optimizado para servicios internos que necesitan registrar auditoria de forma sincronica. No requiere JWT de usuario — usa autenticacion service-to-service.

Request Body:

json

{
  "class_uid": 3001,
  "class_name": "Account Change",
  "category_uid": 3,
  "category_name": "Identity & Access Management",
  "activity_id": 1,
  "activity_name": "Create",
  "severity_id": 1,
  "message": "New user registered via credit origination pipeline",
  "actor": {
    "user_uid": "system-lending",
    "user_name": "ImagLend Service",
    "user_type": "Service"
  },
  "resource": {
    "resource_uid": "user-new-001",
    "resource_type": "user",
    "domain": "identity"
  },
  "src_endpoint": {
    "ip": "10.0.1.50",
    "name": "imagy-lending"
  },
  "unmapped": {
    "credit_id": "credit-123",
    "pipeline_step": "user_registration",
    "product_id": "microcredito-express"
  }
}

Response 201:

json

{
  "data": {
    "id": "evt-b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "created_at": "2026-05-20T14:40:00Z"
  },
  "metadata": {
    "request_id": "req-internal-001",
    "timestamp": "2026-05-20T14:40:00Z"
  }
}

Paginacion

Todos los endpoints de listado soportan paginacion basada en offset:

Parametro	Default	Max	Descripcion
`page`	1	—	Numero de pagina
`page_size`	50	200	Resultados por pagina

La respuesta incluye metadata de paginacion:

json

{
  "metadata": {
    "pagination": {
      "page": 1,
      "page_size": 50,
      "total": 1247,
      "total_pages": 25
    }
  }
}

Para datasets muy grandes (> 10,000 eventos), se recomienda usar filtros temporales (time_from, time_to) para acotar el rango y mejorar el rendimiento.

Filtrado Avanzado

Los filtros se pueden combinar libremente. Todos los filtros se aplican con AND logico:

GET /audit/events?category_uid=3&severity_id=3&time_from=2026-05-01T00:00:00Z&time_to=2026-05-31T23:59:59Z&actor_uid=admin-001

Este ejemplo retorna: eventos de categoria IAM, con severidad >= Medium, del mes de mayo, ejecutados por el actor admin-001.

Codigos de Error

Codigo	HTTP	Descripcion
`VALIDATION_ERROR`	400	Datos de entrada invalidos o filtros mal formados
`MISSING_IDEMPOTENCY_KEY`	400	Falta header Idempotency-Key en POST
`INVALID_TIME_RANGE`	400	time_from es posterior a time_to
`UNAUTHORIZED`	401	No autenticado o JWT expirado
`FORBIDDEN`	403	Sin permisos para acceder a auditoria
`NOT_FOUND`	404	Evento o export job no encontrado
`EXPORT_TOO_LARGE`	422	El rango de exportacion excede el limite (> 1M eventos)
`EXPORT_IN_PROGRESS`	409	Ya existe un export job activo con los mismos filtros
`INTERNAL_ERROR`	500	Error interno del servidor

imagy-audit — API Reference ​

Base URL ​

Headers Estandar ​

Request Headers ​

Response Headers ​

Eventos de Auditoria ​

Consultar eventos ​

Obtener evento por ID ​

Crear evento manual ​

Reportes ​

Resumen por periodo ​

Top actores ​

Recursos mas activos ​

Exportaciones ​

Crear job de exportacion ​

Consultar estado de exportacion ​

Endpoints Internos (Service-to-Service) ​

Registrar evento de auditoria (interno) ​

Paginacion ​

Filtrado Avanzado ​

Codigos de Error ​

imagy-audit — API Reference

Base URL

Headers Estandar

Request Headers

Response Headers

Eventos de Auditoria

Consultar eventos

Obtener evento por ID

Crear evento manual

Reportes

Resumen por periodo

Top actores

Recursos mas activos

Exportaciones

Crear job de exportacion

Consultar estado de exportacion

Endpoints Internos (Service-to-Service)

Registrar evento de auditoria (interno)

Paginacion

Filtrado Avanzado

Codigos de Error