Saltar a contenido

Referencia de API

Base URL: https://agente.plussigner.com (producción). Todas las rutas empiezan con /api/v1. Todos los cuerpos son JSON salvo el envío de documentos (multipart/form-data) y la descarga (application/pdf).

Para el detalle de autenticación, ver Autenticación y roles. Para el significado de cada código de error, ver Catálogo de errores. También está disponible como spec OpenAPI y como colección de Postman.

Autenticación

Login de cliente API

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

Body 

{
  "clientId": "saeta-prod-01",
  "clientSecret": "7s_vtHa6pHH5OLNk80u9hpRn6xQW3ZJiMblJiPxz4sM"
}

200 OK 

{
  "accessToken": "eyJhbGciOiJIUzUxMiJ9...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

Errores: 401 CREDENCIALES_INVALIDAS.

Login de usuario (persona)

POST /api/v1/usuarios/login
Content-Type: application/json

Body 

{
  "username": "sfirmante",
  "password": "cambiar123"
}

200 OK: mismo formato que el login de cliente API.

Errores: 401 CREDENCIALES_INVALIDAS.

Administración de clientes (rol ADMIN)

Crear cliente

POST /api/v1/clientes
Authorization: Bearer <token de ADMIN>
Content-Type: application/json

Body 

{
  "nombre": "OEFA",
  "razonSocial": "Organismo de Evaluación y Fiscalización Ambiental"
}
razonSocial es opcional.

201 Created 

{
  "id": 3,
  "nombre": "OEFA",
  "razonSocial": "Organismo de Evaluación y Fiscalización Ambiental",
  "activo": true,
  "fechaCreacion": "2026-08-14T15:30:00Z"
}

Errores: 401 TOKEN_INVALIDO, 403 ACCESO_DENEGADO.

Listar clientes

GET /api/v1/clientes
Authorization: Bearer <token de ADMIN>

200 OK 

[
  {
    "id": 3,
    "nombre": "OEFA",
    "razonSocial": "Organismo de Evaluación y Fiscalización Ambiental",
    "activo": true,
    "fechaCreacion": "2026-08-14T15:30:00Z"
  }
]

Administración de usuarios (rol ADMIN)

Crear usuario (firmante)

POST /api/v1/usuarios
Authorization: Bearer <token de ADMIN>
Content-Type: application/json

Body 

{
  "nombre": "Sara Firmante",
  "username": "sfirmante",
  "password": "cambiar123",
  "clienteId": 3
}
Todos los campos son obligatorios. clienteId debe existir. El usuario siempre se crea con rol FIRMANTE — no existe forma de crear un ADMIN por API.

201 Created 

{
  "id": 7,
  "nombre": "Sara Firmante",
  "username": "sfirmante",
  "rol": "FIRMANTE",
  "clienteId": 3,
  "clienteNombre": "OEFA",
  "activo": true,
  "fechaCreacion": "2026-08-14T15:31:00Z"
}

Errores: 409 USUARIO_YA_EXISTE, 404 CLIENTE_NO_ENCONTRADO.

Listar usuarios

GET /api/v1/usuarios
Authorization: Bearer <token de ADMIN>

200 OK 

[
  {
    "id": 7,
    "nombre": "Sara Firmante",
    "username": "sfirmante",
    "rol": "FIRMANTE",
    "clienteId": 3,
    "clienteNombre": "OEFA",
    "activo": true,
    "fechaCreacion": "2026-08-14T15:31:00Z"
  }
]

Asignar procesos a un usuario (ADMIN)

POST /api/v1/usuarios/{id}/procesos
Authorization: Bearer <token de ADMIN>
Content-Type: application/json

Body 

{
  "procesoIds": [5, 8]
}

Importante: esto reemplaza la lista completa de procesos asignados a ese usuario — no es un "agregar a lo que ya tenía". Si el usuario tenía el proceso 2 asignado y mandás {"procesoIds": [5, 8]}, el proceso 2 queda desasignado.

204 No Content (sin body).

Errores: 404 USUARIO_NO_ENCONTRADO, 404 PROCESO_NO_ENCONTRADO (si alguno de los ids de la lista no existe).

Procesos

Listar todos los procesos (ADMIN)

GET /api/v1/procesos
Authorization: Bearer <token de ADMIN>

Pensado para saber qué id asignarle a un usuario — devuelve todos los procesos configurados en el sistema, sin importar el cliente.

200 OK 

[
  {
    "id": 5,
    "nombre": "Contratos OEFA",
    "activo": true,
    "clienteId": 3,
    "clienteNombre": "OEFA",
    "certificado": {
      "alias": "Firma OEFA 2026",
      "serial": "42F92542734EF9FB89",
      "commonName": "JORGE STALYN VICENTE PIÑAN GOMEZ",
      "fechaExpiracion": "2027-06-01T00:00:00Z"
    }
  }
]

Mis procesos (FIRMANTE)

GET /api/v1/mis-procesos
Authorization: Bearer <token de FIRMANTE>

Devuelve solo los procesos que el ADMIN le asignó a este firmante — no toda la lista.

200 OK 

[
  {
    "id": 5,
    "nombre": "Contratos OEFA",
    "activo": true,
    "certificado": {
      "alias": "Firma OEFA 2026",
      "serial": "42F92542734EF9FB89",
      "commonName": "JORGE STALYN VICENTE PIÑAN GOMEZ",
      "fechaExpiracion": "2027-06-01T00:00:00Z"
    }
  }
]

Nota que esta respuesta no trae clienteId/clienteNombre (un firmante ya sabe a qué cliente pertenece, es implícito en su propia cuenta) — a diferencia de la respuesta de GET /api/v1/procesos, pensada para el ADMIN que administra varios clientes a la vez.

Documentos

Enviar un PDF para firmar

POST /api/v1/documentos
Authorization: Bearer <token>
Content-Type: multipart/form-data

Form-data | Campo | Tipo | Descripción | |---|---|---| | pdf | file | El PDF a firmar | | idProcesoFirma | text | El id del proceso de firma a usar |

Ejemplo con curl: 

curl -X POST https://agente.plussigner.com/api/v1/documentos \
  -H "Authorization: Bearer $TOKEN" \
  -F "pdf=@contrato.pdf" \
  -F "idProcesoFirma=5"

Si el token es de un FIRMANTE, idProcesoFirma debe estar entre sus procesos asignados — si no, 403 PROCESO_NO_AUTORIZADO. Un token de cliente API no tiene esa restricción.

201 Created 

{
  "trackingId": "a1b2c3d4-...",
  "idProcesoFirma": 5,
  "estado": "EN_PROCESO",
  "nombreArchivoOriginal": "contrato.pdf",
  "fechaRecibido": "2026-08-14T15:35:00Z",
  "fechaFirmado": null,
  "fechaEntregado": null,
  "mensajeError": null
}

Errores: 400 ARCHIVO_INVALIDO (falta el PDF, o no es un PDF válido), 404 PROCESO_NO_ENCONTRADO, 409 PROCESO_INACTIVO, 403 PROCESO_NO_AUTORIZADO, 413 ARCHIVO_MUY_GRANDE (más de 25MB).

Consultar el estado de un documento

GET /api/v1/documentos/{trackingId}
Authorization: Bearer <token>

200 OK (mismo formato que la respuesta de envío, con el estado actualizado) 

{
  "trackingId": "a1b2c3d4-...",
  "idProcesoFirma": 5,
  "estado": "FIRMADO",
  "nombreArchivoOriginal": "contrato.pdf",
  "fechaRecibido": "2026-08-14T15:35:00Z",
  "fechaFirmado": "2026-08-14T15:35:12Z",
  "fechaEntregado": null,
  "mensajeError": null
}

Errores: 404 DOCUMENTO_NO_ENCONTRADO, 403 PROCESO_NO_AUTORIZADO (si un FIRMANTE consulta un documento que no pertenece a un proceso suyo).

Descargar el archivo firmado

GET /api/v1/documentos/{trackingId}/archivo
Authorization: Bearer <token>

200 OK — Content-Type: application/pdf, con header Content-Disposition: attachment; filename="contrato.pdf". La primera vez que se descarga exitosamente, el documento pasa a estado ENTREGADO (las descargas posteriores no cambian el estado, ya quedó marcado).

Errores: 404 DOCUMENTO_NO_ENCONTRADO, 409 DOCUMENTO_NO_LISTO (todavía no está firmado), 409 DOCUMENTO_CON_ERROR (el documento pasó a estado ERROR), 403 PROCESO_NO_AUTORIZADO.