Firma Electrónica SIGNA - JAAK

Contacto: engineering@jaak.ai | Versión: 1.0.0

Descripción

JAAK Signa es una API REST para gestión de firmas digitales de documentos. Permite crear plantillas de documentos, enviarlas a firmantes y gestionar el flujo completo de firma electrónica.

Capacidades

• Cargar PDFs y convertirlos en plantillas reutilizables
• Distribuir documentos a múltiples firmantes vía email
• Rastrear procesos de firma y descargar documentos firmados
• Gestionar directorios de firmantes e información de empresa
• Manejar certificados digitales (FIEL, PSC)
• Generar reportes de cumplimiento

Ambientes

Autenticación

JWT Bearer tokens. Obtener via /api/v1/sign-in. Header requerido:

Authorization: Bearer <access_token>

Los tokens pueden refrescarse sin re-autenticación.

Tipos de Firma Soportados

Módulos Principales de la API

7.1 Autenticación

Gestión de sesiones con operaciones de inicio/cierre de sesión.

7.2 Plantillas (Templates)

Gestión de documentos:

• Crear, actualizar, clonar y eliminar plantillas basadas en PDF
• Campos configurables

7.3 Carpetas (Folders)

Sistema de organización para agrupar plantillas.

7.4 Submissions

Flujo de trabajo principal para distribución de documentos:

• Estados: pending, in_progress, completed, declined, expired, cancelled

7.4.1 Enlace de firma para el firmante (signing_url)

Cuando la función de enlace de firma está habilitada para tu empresa, puedes pedir un enlace de firma nuevo para un submitter específico. El enlace se entrega al firmante por tu propio canal (por ejemplo, un mensaje de tu sistema) en lugar de depender del correo que envía Signa.

Autenticación: Bearer token (JWT) de un usuario con rol owner o administrator de la empresa. Otros roles reciben 403.

Requisito previo: la empresa debe haber activado la función. Un owner o administrator la activa con PUT /api/v1/settings/signing-link, aceptando el texto de consentimiento vigente. El texto y su versión se consultan antes con GET /api/v1/settings/signing-link.

curl -X PUT https://api.sandbox.jaak.ai/api/v1/settings/signing-link \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "consent": {
      "accepted": true,
      "text_version": "<version del GET>",
      "text_sha256": "<sha256 del GET>"
    }
  }'

Emitir el enlace

El :id es el identificador numérico del submitter (submitters[].id) que devuelve la creación del envío. La solicitud no lleva body.

curl -X POST https://api.sandbox.jaak.ai/api/v1/submitters/4812/signing-link \
  -H "Authorization: Bearer $TOKEN"

Respuesta (200 OK):

{
  "signing_url": "https://signa.sandbox.jaak.ai/ejemplo-firmante-7f3a?code=ejemplo-codigo-ficticio-no-real",
  "expires_at": "2026-10-16T18:45:00Z"
}

Campos de la respuesta:

Comportamiento:

• Cada emisión revoca los enlaces vivos anteriores del mismo submitter. Usa solo el último signing_url que recibiste.
• El enlace deja de funcionar cuando vence, cuando se emite uno nuevo o cuando la empresa desactiva la función. Al desactivarla, Signa revoca los enlaces vivos de la empresa.
• Trata el signing_url como un secreto: no lo registres en logs ni lo expongas en el frontend. La respuesta lleva Cache-Control: no-store.
• Cada emisión queda registrada en la auditoría de la empresa (signing_link_issued) sin guardar el código ni el enlace.

Límites:

• Máximo 5 emisiones por submitter por hora. La sexta responde 429.
• No se puede emitir si el submitter ya firmó o fue rechazado (estados completed, signed_awaiting_kyc, kyc_verified, kyc_failed o declined).

Errores

7.5 Firma Pública

Endpoints del firmante - solo requieren identificadores slug, sin bearer tokens.

7.8 Firmantes (Signers)

Funcionalidad de libreta de direcciones para perfiles de firmantes reutilizables.

7.7 Empresas (Companies)

Gestión de clientes B2B con IDs fiscales, información de contacto.

7.10 Certificados

Almacenamiento y validación de certificados digitales para firmas FIEL/PSC.

7.11 Almacenamiento (Storage)

Gestión de archivos con URLs firmadas, descargas y generación de rastros de auditoría.

7.13 Cuotas (Quotas)

Rastreo de consumo del plan y verificación de disponibilidad de funciones.

7.17 Webhooks

Notificaciones de terceros para cambios de estado KYC.

Flujo de Trabajo Típico

1. Autenticación → /api/v1/sign-in
2. Crear plantilla → POST /api/v1/templates (desde PDF)
3. Crear submission → Distribuir a múltiples firmantes
4. Invitaciones por email enviadas automáticamente
5. Firmantes acceden a páginas personalizadas (slugs únicos)
6. Para firmas avanzadas: verificación OTP requerida
7. Firmantes envían firmas digitales
8. Documentos descargados con rastros completos de auditoría

Paginación

• Basada en offset: Parámetros page y limit
• Basada en cursor: Parámetros after/before para listado de plantillas

Códigos de Error