ImagFlow — API Reference

Endpoints Publicos (via Gateway)

Todos requieren autenticacion JWT excepto los de ejecucion publica.

Flujos

Metodo	Endpoint	Rol requerido	Descripcion
POST	/api/v1/flows	platform_admin	Crear flujo (crea v1 en draft)
GET	/api/v1/flows	platform_admin	Listar flujos (paginado, filtros)
GET	/api/v1/flows/{id}	platform_admin	Obtener flujo con version published
PATCH	/api/v1/flows/{id}	platform_admin	Actualizar metadata del flujo
DELETE	/api/v1/flows/{id}	platform_admin	Desactivar flujo (soft delete)

Versiones

Metodo	Endpoint	Rol requerido	Descripcion
GET	/api/v1/flows/{id}/versions	platform_admin	Listar todas las versiones
GET	/api/v1/flows/{id}/versions/draft	platform_admin	Obtener draft actual
GET	/api/v1/flows/{id}/versions/published	authenticated	Obtener version publicada
GET	/api/v1/flows/{id}/versions/{versionId}	platform_admin	Obtener version especifica
POST	/api/v1/flows/{id}/versions/new	platform_admin	Crear draft desde published
POST	/api/v1/flows/{id}/versions/draft/publish	platform_admin	Publicar draft
DELETE	/api/v1/flows/{id}/versions/draft	platform_admin	Descartar draft

Pasos (operan sobre el draft)

Metodo	Endpoint	Rol requerido	Descripcion
GET	/api/v1/flows/{id}/versions/draft/steps	platform_admin	Listar pasos
POST	/api/v1/flows/{id}/versions/draft/steps	platform_admin	Agregar paso
PATCH	/api/v1/flows/{id}/versions/draft/steps/{stepId}	platform_admin	Actualizar paso
DELETE	/api/v1/flows/{id}/versions/draft/steps/{stepId}	platform_admin	Eliminar paso
PUT	/api/v1/flows/{id}/versions/draft/steps/reorder	platform_admin	Reordenar pasos

Reglas (operan sobre el draft)

Metodo	Endpoint	Rol requerido	Descripcion
GET	/api/v1/flows/{id}/versions/draft/rules	platform_admin	Listar reglas
POST	/api/v1/flows/{id}/versions/draft/rules	platform_admin	Agregar regla
PATCH	/api/v1/flows/{id}/versions/draft/rules/{ruleId}	platform_admin	Actualizar regla
DELETE	/api/v1/flows/{id}/versions/draft/rules/{ruleId}	platform_admin	Eliminar regla

Proveedores

Metodo	Endpoint	Rol requerido	Descripcion
GET	/api/v1/providers	platform_admin	Listar proveedores
POST	/api/v1/providers	platform_admin	Crear proveedor
GET	/api/v1/providers/{id}	platform_admin	Obtener proveedor
PATCH	/api/v1/providers/{id}	platform_admin	Actualizar proveedor
DELETE	/api/v1/providers/{id}	platform_admin	Desactivar proveedor
POST	/api/v1/providers/{id}/health-check	platform_admin	Verificar conectividad

Asignaciones

Metodo	Endpoint	Rol requerido	Descripcion
GET	/api/v1/flow-assignments	tenant_admin	Listar flujos asignados al tenant
POST	/api/v1/flow-assignments	platform_admin, delegated_admin	Asignar flujo a tenant/org
DELETE	/api/v1/flow-assignments/{id}	platform_admin, delegated_admin	Desasignar flujo

Solicitudes (Requests)

Metodo	Endpoint	Rol requerido	Descripcion
POST	/api/v1/requests	operator	Crear solicitud (genera link)
GET	/api/v1/requests	operator, tenant_admin	Listar solicitudes (paginado)
GET	/api/v1/requests/{id}	operator, tenant_admin	Detalle de solicitud
GET	/api/v1/requests/{id}/attempts	operator, tenant_admin	Intentos por paso
GET	/api/v1/requests/{id}/enrichments	operator, tenant_admin	Resultados de enriquecimiento

Ejecucion Publica (sin JWT — usa access_token)

Metodo	Endpoint	Auth	Descripcion
GET	/api/v1/execute/{token}	access_token	Estado actual de la ejecucion
POST	/api/v1/execute/{token}/steps/{stepId}	access_token	Enviar datos de un paso
GET	/api/v1/execute/{token}/status	access_token	Status resumido (polling)

Endpoints Internos (servicio-a-servicio)

Invocados por otros dominios con JWT propagado.

Metodo	Endpoint	Consumidor	Descripcion
POST	/api/v1/executions/trigger	ImagLend	Iniciar ejecucion de un flujo programaticamente
GET	/api/v1/executions/{id}/result	ImagLend	Obtener resultado de una ejecucion
GET	/api/v1/executions/{id}/status	ImagLend	Polling de estado

Ejemplos de Request/Response

Crear Flujo

POST /api/v1/flows
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer {jwt}

{
  "name": "Validacion de Identidad Basica",
  "slug": "validacion-identidad-basica",
  "description": "Flujo de 3 pasos: liveness, captura documento, match biometrico",
  "is_template": true,
  "template_category": "identity-verification"
}

Response 201:

{
  "data": {
    "id": "flow-uuid",
    "name": "Validacion de Identidad Basica",
    "slug": "validacion-identidad-basica",
    "version": {
      "id": "version-uuid",
      "version_number": 1,
      "status": "draft"
    }
  },
  "metadata": {
    "request_id": "req-abc123",
    "timestamp": "2026-05-18T10:30:00Z"
  }
}

Crear Solicitud

POST /api/v1/requests
Content-Type: application/json
Idempotency-Key: 660e8400-e29b-41d4-a716-446655440001
Authorization: Bearer {jwt}

{
  "flow_id": "flow-uuid",
  "subject_data": {
    "identifier_type": "cedula",
    "identifier_value": "1234567890",
    "name": "Juan Perez",
    "email": "juan@email.com",
    "phone": "+573001234567"
  },
  "expires_in_hours": 48,
  "metadata": {
    "origin": "imagy-lending",
    "origin_id": "application-uuid",
    "channel": "digital"
  }
}

Response 201:

{
  "data": {
    "id": "request-uuid",
    "status": "created",
    "access_token": "abc123def456",
    "execution_url": "https://validate.fintech-abc.reimaginetech.io/abc123def456",
    "expires_at": "2026-05-20T10:30:00Z"
  },
  "metadata": {
    "request_id": "req-def456",
    "timestamp": "2026-05-18T10:30:00Z"
  }
}

Trigger de Ejecucion (interno, desde ImagLend)

POST /api/v1/executions/trigger
Content-Type: application/json
Idempotency-Key: 770e8400-e29b-41d4-a716-446655440002
Authorization: Bearer {jwt-propagado}

{
  "flow_id": "flow-uuid",
  "subject_data": {
    "identifier_type": "cedula",
    "identifier_value": "1234567890",
    "name": "Juan Perez"
  },
  "callback_url": "https://api.fintech-abc.reimaginetech.io/v1/lending/callbacks/flow-result",
  "metadata": {
    "origin": "imagy-lending",
    "origin_id": "credit-application-uuid"
  }
}

Response 201:

{
  "data": {
    "execution_id": "exec-uuid",
    "request_id": "request-uuid",
    "execution_url": "https://validate.fintech-abc.reimaginetech.io/token123",
    "status": "created"
  }
}

Obtener Estado de Ejecucion (publico)

GET /api/v1/execute/abc123def456

Response 200:

{
  "data": {
    "status": "in_progress",
    "current_step": {
      "id": "step-uuid",
      "type": "card_capture",
      "name": "Captura de documento",
      "config": {
        "ui": {
          "title": "Captura de documento",
          "instructions": "Tome una foto clara de su cedula"
        },
        "validation": {
          "accepted_document_types": ["cedula", "pasaporte"],
          "capture_sides": ["front", "back"]
        }
      },
      "attempts_used": 0,
      "attempts_remaining": 3
    },
    "progress": {
      "completed_steps": 1,
      "total_steps": 3
    }
  }
}

Enviar Datos de un Paso (publico)

POST /api/v1/execute/abc123def456/steps/step-uuid
Content-Type: multipart/form-data

Response 200 (exito, siguiente paso):

{
  "data": {
    "step_result": "success",
    "next_step": {
      "id": "next-step-uuid",
      "type": "liveness",
      "name": "Verificacion facial"
    }
  }
}

Response 200 (exito, flujo completado):

{
  "data": {
    "step_result": "success",
    "flow_status": "capture_completed",
    "message": "Todos los pasos completados. Su solicitud esta siendo procesada."
  }
}

Response 400 (fallo con reintentos):

{
  "error": {
    "code": "STEP_FAILED",
    "message": "La captura no cumple los requisitos de calidad",
    "details": [
      { "field": "image_quality", "message": "Imagen borrosa" }
    ]
  },
  "data": {
    "attempts_remaining": 2,
    "can_retry": true
  }
}

Headers Especiales

Header	Direccion	Descripcion
Idempotency-Key	Request (POST)	UUID para idempotencia
If-Match	Request (PATCH/PUT)	ETag para concurrencia
ETag	Response (GET)	Version del recurso
X-Idempotent-Replayed	Response	true si es respuesta cacheada
X-Request-Id	Response	ID de trazabilidad

Codigos de Estado

Status	Cuando
200	Operacion exitosa (GET, PATCH, paso completado)
201	Recurso creado (POST)
400	Validacion fallida, paso fallido con reintentos
401	No autenticado
403	Sin permisos para la operacion
404	Recurso no encontrado
409	Conflicto (ej: ya existe draft, doble ejecucion concurrente)
410	Solicitud expirada
412	ETag mismatch (concurrencia)
429	Rate limit o max reintentos excedidos
500	Error interno