Cómo integrar la firma digital en tu sistema: guía técnica con la API
Hay un punto en el que la firma deja de ser una plataforma que alguien abre y pasa a ser una llamada que hace tu backend. Esta guía recorre ese camino: arquitectura, autenticación, el flujo mínimo endpoint por endpoint, los estados de una solicitud, webhooks con reintentos e idempotencia, y el checklist de lo que suele romperse en producción.
Integrar la firma por API son tres llamadas después de autenticarse: crear el documento, declarar los firmantes y enviarlo a firmar. El resultado no se consulta, llega: tu backend expone un endpoint que recibe el evento document.signed y descarga el documento firmado con su evidencia. Todo lo demás son detalles de robustez.
Los ejemplos de esta guía son ilustrativos: muestran la forma del flujo, no el contrato exacto de la API. Los nombres de campos, rutas y respuestas reales están en la documentación Swagger y en el manual de Integraciones y API. Si buscás el por qué antes del cómo, empezá por firma electrónica y digital con la API de VaFirma.
¿Cómo se acomoda la firma en tu arquitectura?
Tu sistema conserva el control del proceso; la plataforma se encarga del acto de firma y de la evidencia legal. Esa división es lo que hace que la integración sea corta: no hay que replicar nada del circuito de firma del lado tuyo.
Hay una decisión de diseño que conviene tomar temprano: quién es el dueño del documento. Si tu backend lo genera —a partir de una plantilla, de un formulario o de datos del CRM—, la API recibe un archivo ya armado y tu sistema mantiene la trazabilidad completa desde el origen. Es el camino que menos sorpresas trae.
- Credenciales de API
- Cliente HTTP autenticado
- Endpoint público para webhooks
- Almacenamiento del firmado y su evidencia
Del lado del firmante no hace falta nada: recibe un enlace y firma desde el navegador, sin instalar software ni tener un certificado propio.
El flujo mínimo, endpoint por endpoint
Cinco pasos. Los tres del medio son las únicas llamadas obligatorias para poner un documento en circulación.
1. Autenticarse y obtener el token
La API usa autenticación por token: tu backend se autentica una vez, guarda el token y lo manda en cada request posterior.
// 1. obtener el token POST /auth/login { "email": "usuario_de_integracion", "password": "..." } // respuesta { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6..." } // 2. en cada request posterior Authorization: Bearer {access_token}
Dos cosas que evitan dolores de cabeza más adelante: usá un usuario de integración dedicado, no la cuenta de una persona —los tokens de una cuenta personal se caen cuando esa persona cambia la contraseña o deja la empresa—, y cacheá el token en lugar de pedir uno nuevo en cada llamada, contemplando su renovación cuando expira.
2. Crear el documento
Se envía el archivo junto con los metadatos propios de tu negocio. Ese campo de metadatos es más importante de lo que parece: es lo que después permite reconciliar un webhook con la entidad correcta de tu base.
POST /documents
{
"name": "Contrato Cliente 12345",
"file": "<pdf en base64>",
"metadata": {
"cliente_id": "12345",
"operacion_id": "OP-2026-0417"
}
}
Poné en metadata la clave con la que tu sistema identifica la operación. Cuando llegue el webhook vas a poder resolver "de qué contrato me están hablando" sin buscar por nombre de archivo ni por mail del firmante.
3. Definir los firmantes
Acá se declara quién firma, en qué orden, con qué tipo de firma y con qué método de autenticación. Es el punto donde la política de firma de la empresa se vuelve código.
POST /documents/{id}/signers
[
{ "name": "Juan Pérez", "email": "juan@ejemplo.com", "order": 1, "type": "electronic" },
{ "name": "María Gómez", "email": "maria@ejemplo.com", "order": 2, "type": "electronic" }
]
El campo order define si la firma es secuencial o si todos reciben el documento a la vez. Cuándo conviene cada modo está desarrollado en la checklist de flujos de firma electrónica; la regla corta es que el orden secuencial solo se justifica cuando una firma depende de la anterior.
4. Enviar a firmar
Una sola llamada dispara las notificaciones, los enlaces de firma y el proceso de validación. A partir de ahí el circuito corre sin tu sistema en el medio.
POST /documents/{id}/send
Es también el punto donde conviene guardar el estado del lado tuyo: tu base debería saber que el documento está "en circulación", para no volver a enviarlo si el usuario aprieta dos veces el botón.
5. Procesar el webhook y descargar el firmado
Cuando el documento se firma, la plataforma le avisa a tu endpoint. Tu backend descarga el firmado con su evidencia y continúa el proceso de negocio: activar el servicio, dar el alta, emitir la factura.
GET /documents/{id}/download
// devuelve el PDF firmado y la evidencia del acto:
// identidad verificada, fecha y hora, IP, dispositivo, hash
Archivá las dos cosas, no solo el PDF. La evidencia es lo que sostiene el documento frente a una auditoría o un juicio, y está desglosada en qué guarda un contrato digital por dentro.
Creá una cuenta, generá las credenciales y corré las tres llamadas del flujo mínimo contra un PDF real.
¿Qué estados tiene una solicitud de firma?
Un documento creado se envía, y desde ahí termina firmado, rechazado o vencido. Modelar esos cuatro caminos en tu base es lo que evita el clásico "quedó colgado y nadie se enteró".
| Evento | Cuándo llega | Acción típica en tu sistema |
|---|---|---|
document.sent | El documento salió a firmar. | Marcar la operación como "en circulación". |
document.signed | Se completaron todas las firmas. | Descargar el firmado y avanzar el proceso de negocio. |
document.rejected | Un firmante rechazó el documento. | Notificar al responsable y frenar el circuito. |
document.expired | Venció el plazo sin completarse. | Reabrir, reenviar o cerrar la operación. |
Los nombres exactos de los eventos disponibles están en la documentación de la API. La lista de arriba cubre el circuito básico.
Webhooks: ¿por qué no conviene consultar el estado periódicamente?
Porque el polling agrega latencia, gasta llamadas y escala mal. Con cien documentos abiertos, consultar cada uno cada cinco minutos son miles de requests por día para enterarse de unos pocos cambios.
El webhook invierte la relación: tu endpoint se entera en el momento en que algo pasa. Pero al invertirla aparece un requisito nuevo, y es el que más integraciones rompe.
POST /tu-endpoint/firma
{
"event": "document.signed",
"document_id": "abc123",
"timestamp": "2026-04-20T15:00:00Z"
}
Tres reglas que hacen la diferencia entre una integración que aguanta y una que hay que rehacer:
- Respondé rápido y procesá después. Validá, guardá el evento, devolvé 200 y hacé el trabajo pesado en una cola. Si descargás el PDF antes de responder, el timeout te va a generar un reintento innecesario.
- Hacelo idempotente. Guardá el identificador del evento y descartá los repetidos. Sin esto, un reintento puede activar un servicio dos veces o emitir una factura duplicada.
- Verificá el origen. Tu endpoint es público: comprobá que el evento viene de la plataforma antes de actuar sobre él, y nunca confíes solo en el
document_idque trae el body.
Y un detalle de operación: logueá los eventos crudos que recibís. El día que una operación quede a medias, el log del webhook es lo único que va a decirte si el evento llegó y qué hizo tu sistema con él.
¿Qué revisar antes de salir a producción?
Casi todos los problemas de una integración de firma aparecen en los caminos que no son el feliz. Esta es la lista de lo que suele romperse, con el síntoma que se ve del lado del negocio.
| Lo que falta | Cómo se ve desde el negocio | Qué hacer |
|---|---|---|
| Endpoint no idempotente | Servicios activados dos veces, facturas duplicadas. | Guardar el id del evento y descartar repetidos. |
| Estados terminales sin manejar | Operaciones "en circulación" para siempre. | Modelar rechazado y vencido, y decidir qué pasa con cada uno. |
| Ambientes compartidos | Pruebas que mandan mails a clientes reales. | Credenciales separadas para pruebas y producción. |
| Sin metadatos propios | Webhooks que nadie sabe a qué operación corresponden. | Enviar tu identificador en metadata al crear el documento. |
| Evidencia no archivada | Se guarda el PDF, pero no cómo se firmó. | Persistir el firmado y su evidencia juntos. |
| Token de una cuenta personal | La integración se cae cuando alguien cambia su contraseña. | Usar un usuario de integración dedicado. |
| Sin logs de webhook | Nadie puede reconstruir qué pasó con un documento. | Loguear el evento crudo y el resultado del procesamiento. |
Si esta lista se lee como una lista de proceso y no de código, es porque lo es: la parte difícil de integrar la firma no es el HTTP. Es el mismo diagnóstico de los siete puntos de un flujo de firma, visto desde el backend.
¿Cambia algo al firmar en varios países?
La integración no cambia: cambia el nivel de firma que conviene declarar en cada documento. Es un parámetro del request, no una integración distinta.
Lo que varía entre países es el tipo de firma exigido según el acto, el régimen de certificados y las normas aplicables. Argentina, por ejemplo, habilitó la validación remota de identidad para certificados digitales en 2025; el panorama completo está en qué cambió en la firma electrónica de LATAM, y la diferencia conceptual entre niveles en firma digital vs firma electrónica.
Del lado del código eso se traduce en una decisión de configuración: qué type de firma y qué método de autenticación pedirle a cada firmante según el documento. Si tu empresa opera en varios países con circuitos distintos, lo que conviene unificar es la plataforma, no la exigencia: es el enfoque del servicio de firma digital y electrónica.
Preguntas frecuentes
¿Qué necesito para integrar la firma digital por API?
Tres cosas: credenciales de la API, un backend capaz de emitir requests HTTP autenticados y un endpoint público donde recibir los webhooks. No hace falta nada del lado del firmante: recibe un enlace y firma desde el navegador, sin instalar software ni tener un certificado propio.
¿Cuántas llamadas hacen falta para poner un documento a firmar?
El flujo mínimo son tres llamadas después de autenticarse: crear el documento, declarar los firmantes y enviar a firmar. A partir de ese punto el circuito corre solo y tu sistema se entera del resultado por webhook, sin volver a preguntar.
¿Conviene usar webhooks o consultar el estado periódicamente?
Webhooks. El polling agrega latencia, gasta llamadas y escala mal: con cien documentos abiertos, consultar cada uno cada cinco minutos son miles de requests diarios para enterarse de unos pocos cambios. Los webhooks avisan en el momento y dejan el resto del tiempo libre.
¿Por qué mi endpoint de webhooks tiene que ser idempotente?
Porque el mismo evento puede llegar más de una vez: si tu endpoint tarda o devuelve un error, el sistema reintenta. Si cada llegada dispara una acción de negocio, un reintento puede activar un servicio dos veces o emitir una factura duplicada. La solución es guardar el identificador del evento y descartar los repetidos.
¿Se puede probar la integración sin afectar datos reales?
Sí, y es la práctica recomendada: mantener ambientes separados, con credenciales distintas para pruebas y para producción, y no compartir tokens entre los dos. Antes de salir a producción conviene probar además los caminos que no son el feliz: rechazo, vencimiento y firmante que nunca abre el documento.
¿Qué devuelve la descarga de un documento firmado?
El PDF firmado y su evidencia asociada: identidad verificada, fecha y hora, IP, dispositivo y hash del archivo. Esa evidencia es lo que se presenta en una auditoría o en un juicio, así que conviene archivarla junto con el documento y no solo el PDF.
¿Cambia la integración si firmo en varios países de LATAM?
La integración no cambia: se sigue usando la misma API. Lo que cambia es el tipo de firma que conviene declarar en cada documento, porque el nivel exigido depende del país y del riesgo del acto. Es un parámetro del request, no una integración distinta.
Referencias
- Documentación Swagger de la API de VaFirma: rutas, parámetros y respuestas reales.
- Manual de Integraciones y API: guías de implementación y ejemplos.
- Argentina — Ley 25.506 de Firma Digital (InfoLEG).
- Uruguay — Ley 18.600 de Documento Electrónico y Firma Electrónica (IMPO).
Los payloads, rutas y nombres de campos de esta guía son ilustrativos y buscan mostrar la forma del flujo de integración: el contrato vigente de la API es el de la documentación Swagger. Esta guía tampoco constituye asesoramiento legal.
Francisco escribe sobre firma electrónica, firma digital y digitalización de procesos documentales en LATAM. En VaFirma acompaña a equipos de legales, RRHH y operaciones a llevar sus circuitos de firma a producción, y traduce el marco legal de cada país en decisiones concretas de proceso.