ImagSign — API Reference

Endpoints Publicos (via Gateway)

Todos requieren autenticacion JWT excepto los de firma publica.

Solicitudes de Firma

Metodo	Endpoint	Rol requerido	Descripcion
`POST`	`/api/v1/signature-requests`	operator	Crear solicitud de firma
`GET`	`/api/v1/signature-requests`	operator, tenant_admin	Listar solicitudes (paginado)
`GET`	`/api/v1/signature-requests/{id}`	operator, tenant_admin	Detalle de solicitud
`POST`	`/api/v1/signature-requests/{id}/cancel`	operator	Cancelar solicitud (revocar)

Documentos

Metodo	Endpoint	Rol requerido	Descripcion
`POST`	`/api/v1/signature-requests/{id}/documents`	operator	Subir documento (obtener presigned URL)
`GET`	`/api/v1/signature-requests/{id}/documents`	operator, tenant_admin	Listar documentos de la solicitud
`GET`	`/api/v1/signature-requests/{id}/documents/{docId}`	operator, tenant_admin	Detalle y estado del documento
`GET`	`/api/v1/signature-requests/{id}/documents/{docId}/download`	operator, tenant_admin	Obtener presigned URL de descarga
`GET`	`/api/v1/signature-requests/{id}/documents/{docId}/download-signed`	operator, tenant_admin	Obtener presigned URL del documento firmado

Proveedores (Platform Admin)

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

Endpoints Publicos de Firma (sin JWT — usa signing_token)

Estos endpoints son accedidos por el firmante a traves del link publico. No requieren autenticacion JWT; la autorizacion se basa en el signing_token.

Metodo	Endpoint	Auth	Descripcion
`GET`	`/sign/{token}`	signing_token	Obtener informacion de la firma (documentos, tipo, estado)
`POST`	`/sign/{token}/execute`	signing_token	Ejecutar la firma
`POST`	`/sign/{token}/otp/send`	signing_token	Solicitar envio de OTP (firma electronica)
`POST`	`/sign/{token}/otp/verify`	signing_token	Verificar OTP ingresado
`GET`	`/sign/{token}/status`	signing_token	Consultar estado (polling)

Endpoints Internos (servicio-a-servicio)

Invocados por ImagFlow e ImagLend con JWT propagado. Misma interfaz que los endpoints publicos pero con header adicional X-Internal-Service.

Metodo	Endpoint	Consumidor	Descripcion
`POST`	`/api/v1/signature-requests`	ImagFlow, ImagLend	Crear solicitud de firma programaticamente
`GET`	`/api/v1/signature-requests/{id}`	ImagFlow, ImagLend	Consultar estado de la solicitud
`GET`	`/api/v1/signature-requests/{id}/result`	ImagFlow, ImagLend	Obtener resultado final (certificado, documento firmado)

Webhook para Callbacks de Proveedores

Los proveedores externos notifican a ImagSign cuando una firma se completa o falla en su lado.

Metodo	Endpoint	Auth	Descripcion
`POST`	`/api/v1/webhooks/providers/{providerCode}/callback`	HMAC signature	Callback del proveedor

El webhook valida la firma HMAC del proveedor antes de procesar. Cada proveedor tiene su propio secret configurado en connection_config.

Ejemplos de Request/Response

Crear Solicitud de Firma (Standalone)

http

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

json

{
  "signature_type": "digital_certificate",
  "provider_code": "firmalo-ec",
  "signer": {
    "name": "Maria Garcia Lopez",
    "email": "maria.garcia@email.com",
    "phone": "+593991234567",
    "identifier_type": "cedula",
    "identifier_value": "1712345678"
  },
  "documents": [
    {
      "file_name": "contrato-prestamo.pdf",
      "content_type": "application/pdf"
    }
  ],
  "expires_in_hours": 72,
  "notification_channels": ["email", "sms"],
  "metadata": {
    "purpose": "Firma de contrato de prestamo",
    "reference": "LOAN-2026-001"
  }
}

Response 201:

json

{
  "data": {
    "id": "sr-uuid-001",
    "status": "created",
    "signature_type": "digital_certificate",
    "provider_code": "firmalo-ec",
    "signing_token": "tk_abc123def456ghi789",
    "signing_url": "https://sign.fintech-abc.reimaginetech.io/tk_abc123def456ghi789",
    "signer": {
      "name": "Maria Garcia Lopez",
      "email": "maria.garcia@email.com",
      "identifier_value": "1712345678"
    },
    "documents": [
      {
        "id": "doc-uuid-001",
        "file_name": "contrato-prestamo.pdf",
        "status": "pending_upload",
        "upload_url": "https://s3.amazonaws.com/imagy-sign-docs/...",
        "upload_expires_at": "2026-05-18T10:40:00Z"
      }
    ],
    "expires_at": "2026-05-21T10:30:00Z",
    "created_at": "2026-05-18T10:30:00Z"
  },
  "metadata": {
    "request_id": "req-abc123",
    "timestamp": "2026-05-18T10:30:00Z"
  }
}

Crear Solicitud de Firma (desde ImagFlow)

http

POST /api/v1/signature-requests
Content-Type: application/json
Idempotency-Key: 660e8400-e29b-41d4-a716-446655440001
Authorization: Bearer {jwt-propagado}
X-Internal-Service: imagy-flow-engine

json

{
  "signature_type": "electronic_otp",
  "provider_code": "electronic-generic",
  "signer": {
    "name": "Juan Perez",
    "email": "juan@email.com",
    "phone": "+573001234567",
    "identifier_type": "cedula",
    "identifier_value": "1234567890"
  },
  "documents": [
    {
      "file_name": "terminos-condiciones.pdf",
      "content_type": "application/pdf",
      "s3_key": "tenants/tenant-uuid/flows/request-uuid/documents/terms.pdf"
    }
  ],
  "callback_url": "https://api.fintech-abc.reimaginetech.io/v1/flow/webhooks/sign-result",
  "origin_service": "imagflow",
  "origin_request_id": "flow-request-uuid",
  "expires_in_hours": 24,
  "metadata": {
    "flow_id": "flow-uuid",
    "step_id": "step-uuid"
  }
}

Response 201:

json

{
  "data": {
    "id": "sr-uuid-002",
    "status": "pending_signature",
    "signature_type": "electronic_otp",
    "signing_token": "tk_xyz789abc123",
    "signing_url": "https://sign.fintech-abc.reimaginetech.io/tk_xyz789abc123",
    "expires_at": "2026-05-19T10:30:00Z"
  },
  "metadata": {
    "request_id": "req-def456",
    "timestamp": "2026-05-18T10:30:00Z"
  }
}

Obtener Informacion de Firma (Firmante - Publico)

http

GET /sign/tk_abc123def456ghi789

Response 200:

json

{
  "data": {
    "status": "pending_signature",
    "signature_type": "digital_certificate",
    "provider_code": "firmalo-ec",
    "signer_name": "Maria Garcia Lopez",
    "documents": [
      {
        "id": "doc-uuid-001",
        "file_name": "contrato-prestamo.pdf",
        "file_size_bytes": 245000,
        "preview_url": "https://s3.amazonaws.com/imagy-sign-docs/...",
        "preview_expires_at": "2026-05-18T10:45:00Z"
      }
    ],
    "ui_config": {
      "title": "Firma de Contrato",
      "instructions": "Revise el documento y proceda a firmar",
      "requires_otp": false,
      "requires_biometric": false
    },
    "expires_at": "2026-05-21T10:30:00Z"
  }
}

Ejecutar Firma (Firmante - Publico)

http

POST /sign/tk_abc123def456ghi789/execute
Content-Type: application/json

json

{
  "confirmation": true,
  "signer_ip": "auto",
  "provider_data": {
    "certificate_password": "****"
  }
}

Response 200:

json

{
  "data": {
    "status": "signed",
    "signed_at": "2026-05-18T11:00:00Z",
    "certificate": {
      "serial": "ABC123456",
      "issuer": "Banco Central del Ecuador",
      "valid_to": "2027-05-18T00:00:00Z"
    },
    "documents": [
      {
        "id": "doc-uuid-001",
        "status": "signed",
        "download_url": "https://s3.amazonaws.com/imagy-sign-docs/...",
        "download_expires_at": "2026-05-18T11:15:00Z"
      }
    ]
  }
}

Ejecutar Firma Electronica con OTP

Paso 1: Solicitar OTP

http

POST /sign/tk_xyz789abc123/otp/send
Content-Type: application/json

json

{
  "channel": "sms"
}

Response 200:

json

{
  "data": {
    "otp_sent": true,
    "channel": "sms",
    "masked_destination": "+57300***4567",
    "expires_in_seconds": 300
  }
}

Paso 2: Verificar OTP y Firmar

http

POST /sign/tk_xyz789abc123/otp/verify
Content-Type: application/json

json

{
  "otp_code": "847291"
}

Response 200:

json

{
  "data": {
    "status": "signed",
    "signed_at": "2026-05-18T11:05:00Z",
    "verification_method": "otp_sms",
    "documents": [
      {
        "id": "doc-uuid-002",
        "status": "signed",
        "download_url": "https://s3.amazonaws.com/imagy-sign-docs/..."
      }
    ]
  }
}

Cancelar Solicitud

http

POST /api/v1/signature-requests/sr-uuid-001/cancel
Content-Type: application/json
Authorization: Bearer {jwt}

json

{
  "reason": "Firmante solicito cancelacion"
}

Response 200:

json

{
  "data": {
    "id": "sr-uuid-001",
    "status": "revoked",
    "revoked_at": "2026-05-18T12:00:00Z",
    "reason": "Firmante solicito cancelacion"
  }
}

Webhook de Proveedor (Callback)

http

POST /api/v1/webhooks/providers/firmalo-ec/callback
Content-Type: application/json
X-Webhook-Signature: sha256=abc123...
X-Webhook-Timestamp: 1716030000

json

{
  "event_type": "signature.completed",
  "external_id": "firmalo-tx-12345",
  "status": "completed",
  "signed_document_url": "https://firmalo.ec/documents/12345/download",
  "certificate": {
    "serial": "ABC123456",
    "issuer": "Banco Central del Ecuador",
    "subject": "Maria Garcia Lopez",
    "algorithm": "RSA-SHA256"
  },
  "timestamp": "2026-05-18T11:00:00Z"
}

Response 200:

json

{
  "received": true
}

Headers Especiales

Header	Direccion	Descripcion
`Idempotency-Key`	Request (POST)	UUID para idempotencia
`If-Match`	Request (PATCH)	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
`X-Internal-Service`	Request	Identifica servicio interno que invoca
`X-Webhook-Signature`	Request (webhook)	Firma HMAC del proveedor
`X-Webhook-Timestamp`	Request (webhook)	Timestamp del webhook para replay protection

Codigos de Estado

Status	Cuando
200	Operacion exitosa (GET, firma ejecutada, cancelacion)
201	Solicitud creada (POST)
400	Validacion fallida, OTP incorrecto
401	No autenticado
403	Sin permisos para la operacion
404	Recurso no encontrado
409	Conflicto (solicitud ya firmada, ya cancelada)
410	Solicitud expirada
412	ETag mismatch (concurrencia)
422	Proveedor rechazo la firma (certificado invalido, etc.)
429	Rate limit excedido
500	Error interno
502	Error de comunicacion con proveedor externo

ImagSign — API Reference ​

Endpoints Publicos (via Gateway) ​

Solicitudes de Firma ​

Documentos ​

Proveedores (Platform Admin) ​

Endpoints Publicos de Firma (sin JWT — usa signing_token) ​

Endpoints Internos (servicio-a-servicio) ​

Webhook para Callbacks de Proveedores ​

Ejemplos de Request/Response ​

Crear Solicitud de Firma (Standalone) ​

Crear Solicitud de Firma (desde ImagFlow) ​

Obtener Informacion de Firma (Firmante - Publico) ​

Ejecutar Firma (Firmante - Publico) ​

Ejecutar Firma Electronica con OTP ​

Cancelar Solicitud ​

Webhook de Proveedor (Callback) ​

Headers Especiales ​

Codigos de Estado ​

ImagSign — API Reference

Endpoints Publicos (via Gateway)

Solicitudes de Firma

Documentos

Proveedores (Platform Admin)

Endpoints Publicos de Firma (sin JWT — usa signing_token)

Endpoints Internos (servicio-a-servicio)

Webhook para Callbacks de Proveedores

Ejemplos de Request/Response

Crear Solicitud de Firma (Standalone)

Crear Solicitud de Firma (desde ImagFlow)

Obtener Informacion de Firma (Firmante - Publico)

Ejecutar Firma (Firmante - Publico)

Ejecutar Firma Electronica con OTP

Cancelar Solicitud

Webhook de Proveedor (Callback)

Headers Especiales

Codigos de Estado