Integrá tu sistema con f· firma
Creá solicitudes de firma, consultá su estado y descargá sus documentos desde tu servidor.
1. Creá una API Key
Ingresá al panel y abrí Menú de tu cuenta → Perfil → API Key. Elegí un nombre y la vigencia. Copiá la clave: se muestra una sola vez. Si la perdés, usá Renovar y actualizala en tu sistema.
Guardala en una variable de entorno del backend. No la publiques en GitHub, en el navegador ni en la URL. En producción usá HTTPS. La API no utiliza las cookies de acceso del panel y no habilita llamadas CORS desde sitios externos.
Authorization: Bearer TU_API_KEYCada integración accede solo a los documentos que creó. Renovar conserva ese acceso e invalida la clave anterior. Revocar o dejar vencer una clave bloquea la API; no cancela los documentos ni sus enlaces de firma. No da acceso al panel, a sus configuraciones ni a expedientes privados.
2. Creá una solicitud
POST /api/v1/documents · Formulario multipart/form-data con pdf y settings. Solo PDF, hasta 15 MB y 80 páginas sin rotaciones o recortes especiales. No se aceptan URLs de archivos ni documentos Word.
Guardá este ejemplo en settings.json. Podés agregar de 1 a 12 firmantes; cada uno firma por su enlace, sin esperar a los demás.
{
"name": "Contrato de prueba.pdf",
"signers": [
{"name": "Juan", "surname": "Pérez", "dni": "12345678", "phone": "+5493415551234"}
],
"validationMode": "signature",
"signAllPages": true,
"expiresInDays": 7,
"sendWhatsApp": false
}Configurá la variable FIRMA_API_KEY en tu terminal o servidor con tu clave. Después ejecutá:
curl --request POST 'BASE_URL/api/v1/documents' \
--header "Authorization: Bearer $FIRMA_API_KEY" \
--header 'Idempotency-Key: contrato-prueba-0001' \
--form 'pdf=@contrato.pdf;type=application/pdf' \
--form 'settings=<settings.json'
Idempotency-Key es obligatoria. Usá un identificador único por solicitud. Ante un corte de conexión, repetí el mismo PDF y settings con la misma clave. Se devolverá el documento existente (HTTP 200, Idempotency-Replayed: true) y no se repetirá el envío de WhatsApp. Una creación devuelve HTTP 201. Si cambiás el contenido con la misma clave, recibirás 409; usá una clave nueva solo si querés otra solicitud. Si el documento se eliminó, recibirás 410 sin crear una copia.
| Campo de settings | Uso |
|---|---|
| signers | Obligatorio. name, surname y dni; phone y role opcionales. Teléfono internacional con +, de 8 a 15 dígitos. |
| validationMode | signature (predeterminado), photos (selfie + DNI) o didit (requiere proveedor configurado). |
| signAllPages | true o false. Predeterminado: false. |
| expiresInDays | Entero entre 1 y 30. Predeterminado: 7. |
| sendWhatsApp | Predeterminado: false. true solicita el envío según la configuración de WhatsApp del servidor; no garantiza entrega. Con false podés compartir los signingUrl por tu propio canal. |
| name / requester | Nombre del documento y email del solicitante, opcionales. Se usan los valores del archivo y del perfil si se omiten. |
La respuesta incluye id, status, contador de firmas y signers[].signingUrl. Estos enlaces permiten firmar: compartilos únicamente con el destinatario correspondiente.
3. Consultá el estado y descargá el PDF
curl 'BASE_URL/api/v1/documents/ID_DEL_DOCUMENTO' \
--header "Authorization: Bearer $FIRMA_API_KEY"status puede ser pending, completed, cancelled, declined o expired. signatures muestra signed y total. Cuando todos firman, status pasa a completed; el cierre criptográfico puede seguir procesándose.
Esperá finalization.state: "ready" y un valor en links.finalPdf antes de descargar el final. Un cierre pendiente devuelve 409 al intentar descargar; eso no cancela las firmas. Una confirmación blockchain pendiente no bloquea un PDF cuyo cierre ya está listo.
curl 'BASE_URL/api/v1/documents/ID_DEL_DOCUMENTO/pdf' \
--header "Authorization: Bearer $FIRMA_API_KEY" \
--output documento-firmado.pdfEl original está en GET /api/v1/documents/ID/original. Ambas descargas requieren Bearer. La API devuelve el mismo PDF final protegido que el panel; no genera una copia sin protección.
originalSha256 identifica el original. baseFinalSha256 corresponde al PDF base anterior al sello de la plataforma, no al archivo final protegido que se descarga.
Listar documentos
GET /api/v1/documents?limit=20 devuelve data y nextCursor. Para la página siguiente, agregá cursor=NEXT_CURSOR. El límite máximo es 100. Solo aparecen documentos de esa integración y fuera de Papelera. La lista no verifica el cierre: consultá el documento individual para conocer finalization y finalPdf.
Podés recibir avisos mediante webhooks. Si preferís consultar estados periódicamente, dejá al menos 30 segundos entre intentos.
Webhooks: avisos a tu sistema
En Perfil → API Key → Webhook, configurá una URL HTTPS pública (puerto 443), elegí eventos y guardá el secreto que se muestra una vez. Es distinto de la API Key. Los avisos incluyen sólo identificadores, estado y contadores de documentos de esa integración; no contienen enlaces de firma, fotos ni datos de identidad.
Eventos: document.created, signer.signed, document.completed, document.ready, document.cancelled, document.declined y document.expired. El botón Enviar prueba genera webhook.test.
document.completed indica que terminaron las firmas. Esperá document.ready para descargar el PDF final mediante la API autenticada. Los avisos no garantizan el orden de llegada: consultá el documento si necesitás confirmar su estado actual.
{
"id": "ID_UNICO_DEL_EVENTO",
"type": "document.ready",
"createdAt": "2026-11-09T16:00:00.000Z",
"data": {
"documentId": "ID_DEL_DOCUMENTO",
"status": "completed",
"signatures": {"signed": 1, "total": 1},
"finalPdfPath": "/api/v1/documents/ID_DEL_DOCUMENTO/pdf"
}
}Encabezados: X-Firma-Delivery (ID estable), X-Firma-Event, X-Firma-Timestamp (segundos Unix) y X-Firma-Signature. Verificá HMAC-SHA256 del texto timestamp + "." + cuerpo_original usando el secreto completo, incluido el prefijo whsec_. La firma usa el formato sha256=HEX. Comparala en tiempo constante antes de procesar el JSON; rechazá timestamps con más de 5 minutos de diferencia.
Respondé 2xx rápidamente después de guardar el evento. Puede llegar más de una vez: deduplicá por id. Se hacen hasta 5 intentos por evento: después del primero, esperas de 10 segundos, 1 minuto, 5 minutos y 30 minutos. Se reintentan cortes de red, 408, 429 y 5xx. Otros 4xx y redirecciones fallan sin seguir otro destino. No se reenvían eventos históricos al activar un webhook.
El secreto y los tokens de conexión se guardan cifrados. Renovar la API Key conserva el webhook; revocarla o dejarla vencer detiene sus avisos. Cambiar de URL o renovar el secreto cancela los reintentos de la configuración anterior. Las entregas terminales recientes se conservan hasta 30 días y 100 registros por cuenta; los pendientes se mantienen hasta agotar sus intentos.
Límites y errores
La cuenta dispone de 100 firmas por mes calendario (hora de Argentina), compartidas entre panel, carga masiva y API. Cada firmante consume una firma al completar su acción; enviar una solicitud reserva las firmas pendientes. Cancelar, rechazar o dejar vencer libera las reservas sin usar. No se acumulan firmas sin usar. El error 409 signature_quota_exceeded indica cupo insuficiente; repetir o cambiar Idempotency-Key no lo evita.
- 60 consultas por minuto por integración.
- 5 POST por minuto por integración, incluidos reintentos.
- 10 descargas por minuto por integración.
- Una carga simultánea por servidor para cuidar los recursos.
- También aplica el límite general de operaciones por IP.
- Hasta 10 integraciones sin revocar y 100 registros de integraciones en esta versión. Renovar permite reutilizar una integración.
HTTP 429 incluye Retry-After: esperá esos segundos y reintentá con la misma Idempotency-Key. No generes reintentos en bucle.
| HTTP | Significado |
|---|---|
| 400 | Archivo, configuración, firmantes o paginación inválidos. |
| 401 | Clave ausente, vencida, renovada o revocada. |
| 403 | Origen no permitido; usá tu backend. |
| 404 | Documento no encontrado o sin acceso. |
| 408 | La carga tardó demasiado. |
| 409 | Idempotency-Key usada con otro contenido, cupo insuficiente o PDF final aún no disponible. |
| 410 | La solicitud de un reintento fue eliminada o está en Papelera. |
| 429 | Límite de uso o carga simultánea alcanzado. |
| 503 | Falta configurar un servicio requerido, por ejemplo Didit. |
Los errores devuelven JSON con error y, cuando está disponible, code. Las claves no dan acceso a la API administrativa, a fotos de identidad, informes privados, configuración ni carga masiva.