Endpoints de la API REST¶

Autenticación¶

Registrar usuario¶

POST /auth/registrar

Crea una nueva cuenta de usuario en el sistema.

Datos requeridos: - email - Correo electrónico - password - Contraseña - name - Nombre completo

Respuesta exitosa: - jwtToken - Token de acceso (24 horas de validez) - refreshToken - Token para renovar el acceso (7 días de validez)

Iniciar sesión¶

POST /auth/acceder

Obtén tokens de acceso usando credenciales existentes.

Datos requeridos: - email - Tu correo electrónico - password - Tu contraseña

Renovar token¶

POST /auth/refrescar

Obtén nuevos tokens cuando el access token expire.

Header requerido:

Authorization: Bearer <refresh_token>

Grupos de Proceso de Firma¶

Un grupo de firma es un contenedor que agrupa varios documentos para firmarlos juntos. Todos los endpoints de grupos requieren autenticación.

Iniciar grupo de firma¶

POST /api/v2/grupo-proceso-firma/iniciar-grupo

Crea un nuevo grupo y sube los documentos a firmar.

Datos requeridos: - idFirmante - Identificador único del firmante (DNI, RUC, etc.) - idProceso - ID del proceso de negocio - documentos - Lista de documentos a firmar

Cada documento incluye: - nombre - Nombre del archivo PDF - codigo - Código interno de referencia - contenido - Archivo PDF en Base64 - configuraciones - Configuraciones específicas de firma (opcional) - imagen - Imagen de firma en Base64 (opcional)

Respuesta: - gruProFirId - ID del grupo creado (guarda este valor) - propiedades - Configuración aplicada al grupo

Iniciar grupo (versión formulario)¶

POST /api/v2/grupo-proceso-firma/iniciar-grupo-v2

Igual que el anterior pero usando multipart/form-data en lugar de JSON.

Útil cuando necesitas subir archivos grandes sin codificarlos en Base64.

Partes esperadas por el controlador: - idFirmante como parametro de formulario. - idProceso como parametro de formulario. - nombres como lista de nombres de documentos. - configuraciones como lista de configuraciones por documento. - archivos como lista de PDFs. - imagen opcional, con limite de 2 MB.

Consultar estado del grupo¶

GET /api/v2/grupo-proceso-firma/{id}/estado

Revisa cómo va el proceso de firma de un grupo.

Respuesta incluye: - estadoGrupo - Estado actual (INITIATED, DICHARGED, UPLOADED, etc.) - totalDocs - Total de documentos - docsListos - Documentos ya firmados - docsPendientes - Documentos pendientes - readyToDownload - Si los documentos están listos para descargar

Verificar si está firmado¶

GET /api/v2/grupo-proceso-firma/verificar-grupo-firmado/{idGP}

Confirma si todos los documentos del grupo fueron firmados correctamente.

Solo funciona cuando el grupo está en estado UPLOADED.

Respuesta incluye: - gpf.documentos - Lista de documentos con su estado de firma - documento.contenido - Archivo firmado en Base64 (descargable)

Ver documentos del grupo¶

GET /api/v2/grupo-proceso-firma/{idGP}/documentos

Obtén la lista de documentos asociados a un grupo.

Respuesta incluye: - Nombre original y nombre del archivo firmado - URL de descarga para cada documento - Estado de confirmación

Cancelar grupo¶

GET /api/v2/grupo-proceso-firma/cancelar-grupo/{idGP}

Cancela un grupo de firma que aún está en proceso.

Solo funciona si el grupo está en estado INITIATED o DICHARGED.

SSigner (Motor de Firma)¶

Estos endpoints interactúan con el motor de firma digital.

Generar hashes de prefirma¶

POST /api/v2/ssigner/generar-hash

Genera los hashes que el cliente debe firmar con su certificado digital.

Datos requeridos: - idGP - ID del grupo de proceso - idFirmante - Identificador del firmante - certifcadoPublicoFirmante - Certificado público del firmante en Base64 - userMotivo - Motivo de la firma (opcional) - userLocacion - Ubicación de la firma (opcional)

Respuesta incluye: - hashes - Lista de hashes a firmar (en Base64) - algoritmo - Algoritmo de hash usado (ej: SHA256) - nombresDocumentos - Nombres de los documentos - propiedades - Configuración de firma a aplicar

¿Qué sigue? El cliente debe firmar estos hashes localmente con su certificado y luego enviar los hashes firmados.

Insertar hashes firmados¶

POST /api/v2/ssigner/insertar-hash-firmado

Envía los hashes ya firmados por el cliente para insertarlos en los documentos.

Datos requeridos: - idpg - ID del grupo de proceso - hashesFirmados - Lista de hashes firmados en Base64

¿Qué hace? El motor combina los hashes firmados con los documentos originales y genera los PDF finales.

Obtener configuración¶

POST /api/v2/ssigner/obtener-configuracion

Recupera la configuración de firma definida para un firmante.

Datos requeridos: - idFirmante - Identificador del firmante

Respuesta incluye: - propiedades - Configuración completa del firmante - idGrupo - ID del grupo asociado

Documentos¶

Descargar documento firmado¶

GET /api/v2/documento/descargar-firmado-blob/{id}

Descarga un documento ya firmado.

Respuesta: - Flujo binario del PDF - Content-Type: application/pdf - Content-Disposition: attachment; filename="documento.pdf"

Tambien existe:

GET /api/v2/documento/descargar-firmado/{id}

Ese endpoint devuelve una respuesta JSON con el documento firmado codificado en Base64.

La entrega del flujo no marca por sí sola una descarga como exitosa. Después de validar el archivo recibido, el cliente debe confirmar el resultado:

POST /api/v2/documento/{id}/confirmar-descarga
Content-Type: application/json

{
  "resultado": "OK",
  "sha256Cliente": "<sha256_del_archivo>",
  "sizeCliente": 123456
}

Una confirmación OK o SUCCESS registra la primera fecha/hora de descarga exitosa. Todos los intentos, incluidos los fallidos, actualizan la fecha del último intento y el contador de descargas.

Usuarios¶

Listar usuarios¶

GET /api/v2/users

Devuelve todos los usuarios registrados en el sistema.

Clientes¶

Listar clientes¶

GET /api/v2/clientes

Devuelve todos los clientes del sistema.

Crear cliente¶

POST /api/v2/clientes

Registra un nuevo cliente.

Datos requeridos: - name - Nombre del cliente - email - Correo electrónico - password - Contraseña inicial

Cambiar estado del cliente¶

PATCH /api/v2/clientes/{id}/estado

Activa o desactiva un cliente.

Datos: - enabled - true/false (cuenta activa) - authorized - true/false (autorizado para operar)

Obtener cliente¶

GET /api/v2/clientes/{id}

Devuelve un cliente por ID.

Actualizar cliente¶

PUT /api/v2/clientes/{id}

Actualiza los datos editables de un cliente.

Resumen de Rutas Protegidas¶

Todas las rutas excepto las de autenticación requieren el header:

Authorization: Bearer <jwt_token>

Estados de Respuesta HTTP¶