Guía de integración para un front de administración¶
Esta guía recorre, paso a paso, todo lo que necesita un front de administración para integrarse contra esta API: desde el login del ADMIN hasta la descarga del documento firmado. Cada paso trae el curl real (reemplazá $TOKEN por el accessToken que recibiste en el login) y la respuesta que deberías esperar.
Se asume que ya tenés al menos un proceso de firma configurado del lado de ssigner-server (eso lo hace soporte técnico manualmente, no es parte de esta API — ver Arquitectura y flujo).
1. Login como ADMIN¶
curl -X POST https://agente.plussigner.com/api/v1/usuarios/login \
-H "Content-Type: application/json" \
-d '{"username": "admin-ssigner-server", "password": "saet@2026"}'
Guardá el accessToken — todas las llamadas siguientes lo necesitan en el header Authorization: Bearer <token>.
2. Crear el cliente (la organización)¶
curl -X POST https://agente.plussigner.com/api/v1/clientes \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"nombre": "OEFA", "razonSocial": "Organismo de Evaluación y Fiscalización Ambiental"}'
Guardá el id (3 en este ejemplo) — lo necesitás para crear el firmante.
3. Crear el usuario firmante¶
curl -X POST https://agente.plussigner.com/api/v1/usuarios \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"nombre": "Sara Firmante", "username": "sfirmante", "password": "cambiar123", "clienteId": 3}'
{ "id": 7, "nombre": "Sara Firmante", "username": "sfirmante", "rol": "FIRMANTE", "clienteId": 3, "clienteNombre": "OEFA", "activo": true, "fechaCreacion": "..." }
4. Averiguar qué procesos existen¶
[
{ "id": 5, "nombre": "Contratos OEFA", "activo": true, "clienteId": 3, "clienteNombre": "OEFA", "certificado": { "alias": "...", "serial": "...", "commonName": "...", "fechaExpiracion": "..." } }
]
El proceso 5 ya lo configuró soporte manualmente para el cliente OEFA. Anotá su id.
5. Asignar el proceso al firmante¶
curl -X POST https://agente.plussigner.com/api/v1/usuarios/7/procesos \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"procesoIds": [5]}'
204 No Content. Recordá: esto reemplaza la lista completa — si más adelante querés agregarle otro proceso a Sara sin quitarle el 5, tenés que mandar {"procesoIds": [5, <el-nuevo-id>]}, con ambos juntos.
6. El firmante inicia sesión¶
A partir de acá, cambia quién llama — es la cuenta de Sara, no la del admin.
curl -X POST https://agente.plussigner.com/api/v1/usuarios/login \
-H "Content-Type: application/json" \
-d '{"username": "sfirmante", "password": "cambiar123"}'
7. El firmante ve lo que le asignaron¶
[
{ "id": 5, "nombre": "Contratos OEFA", "activo": true, "certificado": { "alias": "...", "serial": "...", "commonName": "...", "fechaExpiracion": "..." } }
]
Este es el listado que tu front debería mostrarle a Sara para que elija a qué proceso mandar su documento — no el de GET /api/v1/procesos (ese es solo para el ADMIN).
8. Enviar el documento¶
curl -X POST https://agente.plussigner.com/api/v1/documentos \
-H "Authorization: Bearer $TOKEN_SARA" \
-F "pdf=@contrato.pdf" \
-F "idProcesoFirma=5"
{ "trackingId": "a1b2c3d4-...", "idProcesoFirma": 5, "estado": "EN_PROCESO", "nombreArchivoOriginal": "contrato.pdf", "fechaRecibido": "...", "fechaFirmado": null, "fechaEntregado": null, "mensajeError": null }
Guardá el trackingId — es el identificador que vas a usar en los dos pasos siguientes.
9. Consultar el estado (polling desde tu front)¶
El documento no se firma en la misma llamada — tu front necesita consultar periódicamente hasta que el estado cambie. Un intervalo de 2-5 segundos es razonable para la mayoría de los casos.
curl https://agente.plussigner.com/api/v1/documentos/a1b2c3d4-... \
-H "Authorization: Bearer $TOKEN_SARA"
Mientras sigue en proceso:
Cuando ya se firmó:
Si en algún momento ves "estado": "ERROR", mostrale al usuario que algo falló (el campo mensajeError trae un mensaje genérico) y no sigas al paso 10 — no hay archivo que descargar.
10. Descargar el documento firmado (el final del flujo)¶
curl https://agente.plussigner.com/api/v1/documentos/a1b2c3d4-.../archivo \
-H "Authorization: Bearer $TOKEN_SARA" \
-o contrato-firmado.pdf
Esto devuelve el PDF directamente (Content-Type: application/pdf). La primera vez que se descarga con éxito, el documento pasa a estado ENTREGADO — no hace falta que tu front haga ninguna llamada extra para marcarlo así, pasa automáticamente en esta misma request.
Con esto termina el ciclo completo de un documento: desde que se creó el cliente y el firmante, hasta que el PDF firmado llegó a manos del usuario final.
Resumen del flujo, de un vistazo¶
flowchart LR
A[Login ADMIN] --> B[Crear cliente]
B --> C[Crear firmante]
C --> D[Ver procesos disponibles]
D --> E[Asignar proceso al firmante]
E --> F[Login del firmante]
F --> G[Ver sus procesos]
G --> H[Enviar documento]
H --> I[Consultar estado -- polling]
I -->|FIRMADO| J[Descargar]
I -->|ERROR| K[Mostrar error]
Errores que tu front debería manejar explícitamente¶
403 PROCESO_NO_AUTORIZADOal enviar/consultar/descargar: el front no debería ni mostrarle al firmante procesos que no le fueron asignados — usá siempreGET /api/v1/mis-procesospara poblar esa lista, nuncaGET /api/v1/procesos(ese es solo para el panel de ADMIN).409 DOCUMENTO_NO_LISTOal intentar descargar antes de tiempo: es un error esperable si tu front no está sincronizado bien con el polling — no debería pasar si seguís el paso 9 antes del 10.409 DOCUMENTO_CON_ERROR: mostrale al usuario que la firma falló y que probablemente necesite reintentar el envío (paso 8) — no hay forma de "reintentar" un documento que ya entró en error, hay que mandarlo de nuevo.
Para el resto de los códigos, ver el Catálogo de errores completo.