JAAK Signa API — Documentación

Versión: 1.0.0
Contacto técnico: [email protected]
Licencia: Propietaria — https://jaak.ai

Tabla de Contenidos

1. Introducción
2. Ambientes y URLs base
3. Autenticación
4. Tipos de Firma
5. Manejo de Errores
6. Paginación
7. Módulos de la API
   • 7.1 Auth — Autenticación
   • 7.2 Templates — Plantillas
   • 7.3 Folders — Carpetas
   • 7.4 Submissions — Envíos para Firma
   • 7.5 Sign — Firma Pública (por Slug)
   • 7.6 Submitters — Firmantes de un Envío
   • 7.7 Companies — Empresas
   • 7.8 Signers — Directorio de Firmantes
   • 7.9 Contacts — Contactos
   • 7.10 Certificates — Certificados Digitales
   • 7.11 Storage — Almacenamiento
   • 7.12 Dashboard — Estadísticas
   • 7.13 Quotas — Cuotas y Suscripciones
   • 7.14 Audit — Auditoría y Compliance
   • 7.15 KYC Verifications — Verificaciones de Identidad
   • 7.16 Settings — Configuración
   • 7.17 Webhooks
8. Modelos de Datos
9. Flujo Completo de Firma
10. Glosario

1. Introducción

JAAK Signa es una API REST para gestión de firma digital de documentos. Permite crear plantillas de documentos, enviarlos a firmantes, y gestionar el proceso completo de firma electrónica — desde la firma simple hasta firma biométrica o con FIEL.

Internamente, el sistema traduce las peticiones HTTP a servicios gRPC. Como cliente, solo necesitas trabajar con los endpoints REST descritos en esta documentación.

¿Qué puedes hacer con esta API?

• Subir documentos PDF y convertirlos en plantillas reutilizables
• Enviar documentos a uno o varios firmantes por correo electrónico
• Gestionar el proceso de firma (seguimiento, cancelación, reenvíos)
• Descargar documentos firmados con su audit trail
• Administrar un directorio de firmantes y empresas
• Gestionar certificados digitales (FIEL, PSC)
• Consultar estadísticas y reportes de compliance

2. Ambientes y URLs base

Todos los endpoints descritos en este documento se agregan a la URL base. Por ejemplo:

POST https://api.sandbox.jaak.ai/api/v1/sign-in

3. Autenticación

La mayoría de los endpoints requieren un Bearer Token JWT en el header de cada petición.

Header requerido

Authorization: Bearer <access_token>

Obtener un token

Llama al endpoint de login con tus credenciales:

POST /api/v1/sign-in
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "tu_password"
}

Respuesta exitosa (200):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600,
  "user": { ... }
}

Renovar el token

Cuando el access_token expire, usa el refresh_token para obtener uno nuevo sin volver a iniciar sesión:

POST /api/v1/refresh-token
Content-Type: application/json

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Endpoints públicos (sin autenticación)

Los siguientes endpoints no requieren Bearer Token, ya que son usados por los firmantes desde su navegador:

• GET/POST /api/v1/sign/{slug} — Página de firma
• POST /api/v1/sign/{slug}/reject — Rechazar firma
• GET /api/v1/submitters/{slug} — Datos del firmante
• POST /api/v1/submitters/send-otp — Enviar OTP
• POST /api/v1/submitters/verify-otp — Verificar OTP
• POST /api/v1/submitters/exchange-code — Intercambiar código de invitación

4. Tipos de Firma

JAAK Signa soporta cinco modalidades de firma:

El tipo de firma se define al crear la plantilla y aplica a todos los envíos basados en ella.

5. Manejo de Errores

Todos los errores retornan un objeto JSON con la siguiente estructura:

{
  "error": "Descripción del error"
}

Códigos de respuesta comunes

6. Paginación

Los listados usan dos esquemas de paginación según el endpoint:

Paginación por offset (page/limit)

GET /api/v1/submissions?page=2&limit=20

La respuesta incluye un objeto pagination:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "has_more": true
  }
}

Paginación por cursor (after/before)

Usada principalmente en /api/v1/templates:

GET /api/v1/templates?limit=10&after=45

• after: ID del último elemento de la página anterior (siguiente página)
• before: ID del primer elemento de la página actual (página anterior)

7. Módulos de la API

7.1 Auth — Autenticación

Gestión de sesiones de usuario.

POST /api/v1/sign-in — Iniciar sesión

Body:

Respuesta: Token de acceso y refresh token.

POST /api/v1/sign-out — Cerrar sesión

Invalida el refresh token activo. Requiere autenticación.

Body: Vacío.

POST /api/v1/refresh-token — Renovar token

Body:

7.2 Templates — Plantillas

Las plantillas son documentos PDF base con campos configurados para capturar firmas y datos de los firmantes. Son la base para crear envíos.

GET /api/v1/templates — Listar plantillas

Query params:

POST /api/v1/templates — Crear plantilla desde PDF

Body:

Cada documento en el array documents:

Ejemplo:

{
  "name": "Contrato de Servicios",
  "folder_name": "Contratos 2025",
  "signature_type": "advanced",
  "documents": [
    {
      "name": "Contrato Principal",
      "file": "JVBERi0xLjQKJ..."
    }
  ]
}

GET /api/v1/templates/{id} — Obtener plantilla por ID

PUT /api/v1/templates/{id} — Actualizar plantilla

Body:

DELETE /api/v1/templates/{id} — Eliminar plantilla

Realiza un soft-delete (la plantilla no se borra físicamente, se marca como eliminada). Retorna 204 No Content.

POST /api/v1/templates/{id}/clone — Clonar plantilla

Crea una copia de la plantilla identificada por {id} en el path.

Body (opcional):

POST /api/v1/templates/clone — Clonar plantilla (ID en body)

Alternativa al endpoint anterior, enviando el ID en el cuerpo.

Body:

7.3 Folders — Carpetas

Las carpetas permiten organizar las plantillas.

GET /api/v1/templates/folders — Listar carpetas

POST /api/v1/templates/folders — Crear carpeta

Body:

GET /api/v1/templates/folders/{id} — Obtener carpeta

PUT /api/v1/templates/folders/{id} — Actualizar carpeta

Body: { "name": "Nuevo nombre" }

DELETE /api/v1/templates/folders/{id} — Eliminar carpeta

7.4 Submissions — Envíos para Firma

Un submission es una instancia de una plantilla enviada a firmantes específicos. Representa el proceso de firma completo para un documento.

Estados de un envío

GET /api/v1/submissions — Listar envíos

Query params:

POST /api/v1/submissions — Crear envío

Body:

Cada objeto en submitters:

Ejemplo:

{
  "template_id": 12,
  "submitters": [
    {
      "email": "[email protected]",
      "name": "Juan Pérez",
      "role": "Contratante"
    },
    {
      "email": "[email protected]",
      "name": "Depto. Legal",
      "role": "Testigo"
    }
  ],
  "message": "Por favor firma el contrato antes del viernes.",
  "expires_in_days": 7,
  "send_emails": true
}

GET /api/v1/submissions/{id} — Obtener envío por ID

PATCH /api/v1/submissions/{id} — Actualizar envío

Permite actualizar el company_id asociado al envío.

Body: { "company_id": 5 }

PUT /api/v1/submissions/{id}/cancel — Cancelar envío

Cancela el envío y notifica a los firmantes pendientes.

Body (opcional):

GET /api/v1/submissions/{id}/download — Descargar documento firmado

Retorna el PDF firmado con todas las firmas aplicadas. Respuesta en application/pdf.

GET /api/v1/submissions/{id}/audit-trail — Obtener trail de auditoría

Retorna el historial completo de eventos del envío (quién abrió, firmó, rechazó, en qué fecha y hora).

GET /api/v1/submissions/{id}/verify-integrity — Verificar integridad del documento

Verifica que el documento no haya sido alterado desde su firma.

7.5 Sign — Firma Pública (por Slug)

Estos endpoints son usados por la interfaz de firma que ve el firmante. No requieren autenticación Bearer, pero operan con el slug único asignado a cada firmante.

GET /api/v1/sign/{slug} — Obtener plantilla para firma

Retorna la plantilla y sus campos para renderizar la página de firma. El slug identifica al firmante dentro del envío.

POST /api/v1/sign/{slug} — Enviar firma

El firmante completa y envía su firma.

Body:

Ejemplo:

{
  "signature_data": "iVBORw0KGgoAAAANS...",
  "field_values": {
    "nombre_completo": "Juan Pérez",
    "fecha": "2025-03-11"
  }
}

POST /api/v1/sign/{slug}/reject — Rechazar firma

El firmante declina firmar el documento. No requiere body.

7.6 Submitters — Firmantes de un Envío

Un submitter es la instancia de un firmante dentro de un envío específico.

Estados de un submitter

GET /api/v1/submitters/{slug} — Obtener firmante por slug

Endpoint público. Retorna información del firmante y el estado de su proceso.

PATCH /api/v1/submitters/{slug}/status — Actualizar estado de firmante

Body:

POST /api/v1/submitters/exchange-code — Intercambiar código de invitación

Cuando el firmante accede mediante un código (en lugar de link directo), este endpoint intercambia el código por un sessionId.

Body:

Respuesta:

{
  "sessionId": "abc123",
  "expiresAt": "2025-03-11T18:00:00Z"
}

POST /api/v1/submitters/send-otp — Enviar código OTP

Para firmas de tipo advanced. Envía un código de 6 dígitos al correo del firmante.

Header requerido: X-Session-JTI: <sessionId>

Body: { "slug": "abc123xyz" }

POST /api/v1/submitters/verify-otp — Verificar código OTP

Valida el OTP ingresado por el firmante y eleva sus permisos para poder firmar.

Header requerido: X-Session-JTI: <sessionId>

Body:

POST /api/v1/submitters/{id}/resend-email — Reenviar email de invitación

Permite reenviar el correo de firma a un firmante, opcionalmente a un nuevo email.

Body (todo opcional):

POST /api/v1/submitters/{slug}/face-image — Subir imagen facial (KYC)

Para firmas biométricas. Sube la imagen del rostro capturada durante la verificación.

Body:

DELETE /api/v1/submitters/{slug}/face-image — Eliminar imagen facial

Elimina la imagen facial previamente subida.

GET /api/v1/submitters/{slug}/face-image-url — Obtener URL de imagen facial

Retorna la URL donde está almacenada la imagen facial.

7.7 Companies — Empresas

Gestión del directorio de empresas clientes (B2B).

GET /api/v1/companies — Listar empresas

Query params:

POST /api/v1/companies — Crear empresa

Body:

GET /api/v1/companies/{id} — Obtener empresa

PUT /api/v1/companies/{id} — Actualizar empresa

DELETE /api/v1/companies/{id} — Eliminar empresa

GET /api/v1/companies/{id}/submissions — Listar envíos de una empresa

Query params: page, limit, status

GET /api/v1/companies/{id}/activity — Feed de actividad de empresa

Retorna los últimos eventos relacionados con la empresa.

Query params: limit (default: 20)

GET /api/v1/companies/{id}/signers — Listar firmantes de una empresa

POST /api/v1/companies/{id}/signers — Crear firmante asociado a una empresa

Ver campos en la sección de Signers.

7.8 Signers — Directorio de Firmantes

El address book de firmantes del tenant. Permite tener un registro reutilizable de personas que firman documentos frecuentemente.

GET /api/v1/signers — Listar firmantes

Query params:

POST /api/v1/signers — Crear firmante

Body:

El objeto address contiene: street, city, state, postalCode, country.

GET /api/v1/signers/{id} — Obtener firmante

PUT /api/v1/signers/{id} — Actualizar firmante

DELETE /api/v1/signers/{id} — Eliminar firmante

PATCH /api/v1/signers/{id}/status — Actualizar estado de firmante

Body: { "status": "active" } o { "status": "archived" }

GET /api/v1/signers/{id}/submissions — Envíos de un firmante

Query params: page, limit, status

GET /api/v1/signers/{id}/kyc-sessions — Listar sesiones KYC del firmante

POST /api/v1/signers/{id}/kyc-sessions — Crear sesión KYC

Body:

PUT /api/v1/signers/{id}/kyc-sessions/{session_id} — Actualizar sesión KYC

Body:

7.9 Contacts — Contactos

Los contactos son derivados de los firmantes y representan entidades de menor granularidad.

GET /api/v1/contacts — Listar contactos

GET /api/v1/contacts/{id} — Obtener contacto

PUT /api/v1/contacts/{id} — Actualizar contacto

DELETE /api/v1/contacts/{id} — Eliminar contacto

7.10 Certificates — Certificados Digitales

Gestión de certificados digitales usados para firma con FIEL o PSC.

GET /api/v1/certificates — Listar certificados

Query params:

POST /api/v1/certificates — Almacenar certificado

Body:

GET /api/v1/certificates/{id} — Obtener certificado

DELETE /api/v1/certificates/{id} — Revocar certificado

Retorna 204 No Content.

POST /api/v1/certificates/validate — Validar certificado

Body:

GET /api/v1/certificates/psc/submission/{submission_id} — Certificado PSC de un envío

Obtiene el certificado PSC asociado a un envío completado.

7.11 Storage — Almacenamiento

Gestión de archivos y documentos almacenados.

Nota: La subida de archivos (POST /api/v1/storage/files) no está implementada vía REST. Para subir archivos usa el canal gRPC streaming directo.

GET /api/v1/storage/files — Listar archivos

Query params:

GET /api/v1/storage/files/{id} — Obtener metadata de archivo

{id} es un UUID v4.

DELETE /api/v1/storage/files/{id} — Eliminar archivo

Retorna 204 No Content.

GET /api/v1/storage/files/{id}/signed-url — Obtener URL firmada temporal

Genera una URL de acceso temporal al archivo.

Query params:

Respuesta:

{
  "url": "https://storage.jaak.ai/files/abc123?token=...",
  "expires_at": "2025-03-11T13:00:00Z"
}

GET /api/v1/storage/files/{id}/download — Descargar archivo

Query params:

GET /api/v1/storage/files/{id}/preview — Preview del documento

Retorna una imagen PNG de la primera página del documento. Útil para mostrar miniaturas.

POST /api/v1/storage/download-with-audit — Descargar con audit trail

Genera un PDF que incluye el documento firmado más el trail de auditoría adjunto.

Body:

Cada objeto en events contiene: type, timestamp, actor, actor_email, description.

GET /api/v1/storage/submissions/{id}/document-with-audit — Ver documento con audit trail

Query params:

7.12 Dashboard — Estadísticas

GET /api/v1/dashboard/stats — Estadísticas generales

Retorna métricas globales del dashboard (totales, tasas de completado, etc.).

GET /api/v1/dashboard/pending — Envíos pendientes

Lista los envíos que aún no han sido completados.

GET /api/v1/stats/submissions — Estadísticas de envíos

Estadísticas detalladas sobre el historial de envíos.

7.13 Quotas — Cuotas y Suscripciones

GET /api/v1/quotas/status — Estado actual de cuotas

Retorna cuánto del plan disponible se ha consumido.

GET /api/v1/quotas/subscription — Detalles de la suscripción activa

GET /api/v1/quotas/plans — Listar planes disponibles

GET /api/v1/quotas/plans/{identifier} — Obtener plan específico

{identifier} puede ser el ID o slug del plan.

POST /api/v1/quotas/check — Verificar si hay cuota disponible

Verifica si se puede ejecutar una operación antes de intentarla.

Body:

7.14 Audit — Auditoría y Compliance

GET /api/v1/audit/compliance-report — Generar reporte de compliance

Genera un reporte de cumplimiento normativo del tenant.

GET /api/v1/audit/search — Buscar eventos de auditoría

Permite consultar el log de eventos del sistema para auditorías.

7.15 KYC Verifications — Verificaciones de Identidad

Gestión de sesiones de verificación KYC asociadas a firmantes biométricos.

GET /api/v1/kyc-verifications — Listar verificaciones

POST /api/v1/kyc-verifications — Crear verificación

GET /api/v1/kyc-verifications/{id} — Obtener verificación por ID

GET /api/v1/kyc-verifications/slug/{slug} — Obtener verificación por slug

Endpoint público (sin autenticación). Usado durante el flujo de verificación del firmante.

7.16 Settings — Configuración

GET /api/v1/settings/profile — Obtener perfil de usuario

PUT /api/v1/settings/profile — Actualizar perfil de usuario

GET /api/v1/settings/company — Obtener configuración de empresa

PUT /api/v1/settings/company — Actualizar configuración de empresa

7.17 Webhooks

Endpoints para recibir notificaciones de terceros. No requieren autenticación Bearer.

POST /api/v1/webhooks/kyc — Webhook de proveedor KYC

Recibe notificaciones del proveedor KYC cuando una verificación cambia de estado.

8. Modelos de Datos

AuthResponse

{
  "access_token": "string",
  "refresh_token": "string",
  "expires_in": 3600,
  "user": {}
}

TemplateResponse

{
  "id": 1,
  "name": "Contrato de Servicios",
  "folder_name": "Contratos 2025",
  "signature_type": "advanced",
  "status": "active",
  "fields": [],
  "documents": [],
  "submission_count": 15,
  "created_at": "2025-01-10T09:00:00Z",
  "updated_at": "2025-03-01T14:30:00Z"
}

SubmissionResponse

{
  "id": 101,
  "slug": "sub_abc123",
  "template": { ... },
  "status": "in_progress",
  "signature_type": "advanced",
  "submitters": [
    {
      "id": 201,
      "slug": "sbm_xyz789",
      "email": "[email protected]",
      "name": "Juan Pérez",
      "role": "Contratante",
      "status": "opened",
      "sent_at": "2025-03-10T10:00:00Z",
      "opened_at": "2025-03-10T11:30:00Z",
      "completed_at": null
    }
  ],
  "combined_document_url": "https://...",
  "psc_constancia_url": null,
  "psc_certificate_id": null,
  "created_at": "2025-03-10T09:55:00Z",
  "completed_at": null
}

Pagination

{
  "page": 1,
  "limit": 10,
  "total": 250,
  "has_more": true
}

Error

{
  "error": "Descripción del error"
}

9. Flujo Completo de Firma

A continuación se describe el flujo típico de extremo a extremo para enviar un documento a firma:

1. Autenticación
   POST /api/v1/sign-in
   → Obtienes access_token

2. Crear plantilla (una sola vez por tipo de documento)
   POST /api/v1/templates
   → Obtienes template_id

3. Crear envío (cada vez que necesites firmas)
   POST /api/v1/submissions
   Body: { template_id, submitters: [{ email, name }] }
   → Se envía email automático a cada firmante
   → Obtienes submission_id y por cada firmante un slug

4. El firmante recibe el email con su link único
   Link contiene el slug personal del firmante

5. El firmante abre la página de firma
   GET /api/v1/sign/{slug}   (sin auth)

   [Si es firma advanced]
   POST /api/v1/submitters/send-otp    (envía OTP al correo)
   POST /api/v1/submitters/verify-otp  (el firmante ingresa el código)

   [Si es firma biometric]
   POST /api/v1/submitters/{slug}/face-image  (sube selfie en base64)

6. El firmante envía la firma
   POST /api/v1/sign/{slug}
   Body: { signature_data, field_values }

7. Cuando todos firman, el envío pasa a status "completed"

8. Descargar el documento firmado
   GET /api/v1/submissions/{id}/download
   → PDF firmado con todas las firmas

9. (Opcional) Descargar con audit trail
   GET /api/v1/storage/submissions/{id}/document-with-audit
   → PDF + registro completo de eventos

10. Glosario

Documentación generada para JAAK Signa API v1.0.0 — [email protected]