{"openapi":"3.0.3","info":{"title":"f·firma · API externa","version":"1.1.0","description":"API de servidor a servidor. Cada integración accede únicamente a documentos que creó. Autenticación Bearer, claves de 1 a 365 días, renovación y revocación en Perfil. Límites por integración: 60 consultas/minuto, 5 POST/minuto y 10 descargas/minuto; una carga simultánea en todo el servidor. También aplica el límite global de mutaciones por IP. Respetar Retry-After y consultar estados como máximo cada 30 segundos. No incluye API de administración, fotos, informes privados, carga masiva. No habilita CORS ni claves en URL. Webhooks configurables en Perfil por integración, firmados con HMAC-SHA256 y reintentos limitados. Cupo de 100 firmas por cuenta y mes calendario (Argentina); emitir reserva firmas y firmar las consume. 409 signature_quota_exceeded indica cupo insuficiente."},"security":[{"apiKey":[]}],"paths":{"/api/v1/documents":{"post":{"operationId":"createDocument","summary":"Crear y enviar una solicitud de firma","description":"Carga PDF (hasta 15 MB y 80 páginas) y settings JSON. Requiere Idempotency-Key; reintentar el mismo PDF y settings con la misma clave devuelve la solicitud existente. No vuelve a enviar WhatsApp. Campos desconocidos se rechazan. La API no acepta archivos Word ni URLs remotas.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9._:-]{8,100}$"},"example":"contrato-2026-0001"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["pdf","settings"],"properties":{"pdf":{"type":"string","format":"binary"},"settings":{"type":"string","description":"JSON serializado según DocumentSettings.","example":"{\"signers\": [{\"name\": \"Juan\", \"surname\": \"Pérez\", \"dni\": \"12345678\", \"phone\": \"+5493415551234\"}], \"validationMode\": \"signature\", \"signAllPages\": true, \"expiresInDays\": 7, \"sendWhatsApp\": false}"}}}}}},"responses":{"200":{"description":"Solicitud existente: reintento idempotente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}},"headers":{"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]}}}},"201":{"description":"Solicitud creada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}},"headers":{"Location":{"schema":{"type":"string"}},"Idempotency-Replayed":{"schema":{"type":"string","enum":["false"]}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Clave inválida, vencida o revocada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Origen no permitido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Documento no encontrado o sin acceso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicto de idempotencia o cierre pendiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Solicitud original ya no disponible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite alcanzado. Respetar Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Servicio requerido no configurado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listDocuments","summary":"Listar documentos de esta integración","description":"Solo los creados por esta integración y fuera de Papelera. La lista no verifica el cierre criptográfico. Para conocer finalization y habilitar finalPdf consultá el documento individual.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string","format":"uuid"},"description":"Usar nextCursor de la respuesta anterior. Si ese documento fue eliminado, reiniciar la paginación."}],"responses":{"200":{"description":"Página de resultados","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"nextCursor":{"type":"string","format":"uuid","nullable":true}}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Clave inválida, vencida o revocada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Origen no permitido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Documento no encontrado o sin acceso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicto de idempotencia o cierre pendiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Solicitud original ya no disponible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite alcanzado. Respetar Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Servicio requerido no configurado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/documents/{id}":{"get":{"operationId":"getDocument","summary":"Consultar firmas y cierre del documento","responses":{"200":{"description":"Estado actual","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Clave inválida, vencida o revocada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Origen no permitido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Documento no encontrado o sin acceso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicto de idempotencia o cierre pendiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Solicitud original ya no disponible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite alcanzado. Respetar Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Servicio requerido no configurado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]},"/api/v1/documents/{id}/original":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"downloadOriginal","summary":"Descargar PDF original","description":"Requiere Authorization: Bearer. El PDF final se habilita cuando todas las firmas y el cierre criptográfico con TSA están completos. La confirmación blockchain es independiente.","responses":{"200":{"description":"Archivo PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Clave inválida, vencida o revocada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Origen no permitido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Documento no encontrado o sin acceso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicto de idempotencia o cierre pendiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Solicitud original ya no disponible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite alcanzado. Respetar Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Servicio requerido no configurado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/documents/{id}/pdf":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"downloadFinal","summary":"Descargar PDF final protegido","description":"Requiere Authorization: Bearer. El PDF final se habilita cuando todas las firmas y el cierre criptográfico con TSA están completos. La confirmación blockchain es independiente.","responses":{"200":{"description":"Archivo PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Clave inválida, vencida o revocada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Origen no permitido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Documento no encontrado o sin acceso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicto de idempotencia o cierre pendiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Solicitud original ya no disponible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite alcanzado. Respetar Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Servicio requerido no configurado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"sfk_...","description":"Clave creada en Perfil. Nunca incluir en la URL o código de navegador."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string"}}},"SignerInput":{"type":"object","additionalProperties":false,"required":["name","surname","dni"],"properties":{"name":{"type":"string","maxLength":120},"surname":{"type":"string","maxLength":120},"dni":{"type":"string","maxLength":30},"phone":{"type":"string","maxLength":40},"role":{"type":"string","maxLength":120}}},"DocumentSettings":{"type":"object","additionalProperties":false,"required":["signers"],"properties":{"name":{"type":"string","maxLength":160},"requester":{"type":"string","format":"email","maxLength":254},"signers":{"type":"array","minItems":1,"maxItems":12,"items":{"$ref":"#/components/schemas/SignerInput"}},"validationMode":{"type":"string","enum":["signature","photos","didit"],"default":"signature"},"signAllPages":{"type":"boolean","default":false},"expiresInDays":{"type":"integer","minimum":1,"maximum":30,"default":7},"sendWhatsApp":{"type":"boolean","default":false,"description":"Solicita el envío según la configuración del servidor; no confirma entrega. Requiere integración WhatsApp habilitada."}},"example":{"signers":[{"name":"Juan","surname":"Pérez","dni":"12345678","phone":"+5493415551234"}],"validationMode":"signature","signAllPages":true,"expiresInDays":7,"sendWhatsApp":false}},"Document":{"type":"object","required":["id","name","status","signatures","signers","links"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["pending","completed","cancelled","declined","expired"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"validationMode":{"type":"string"},"originalSha256":{"type":"string"},"signatures":{"type":"object","properties":{"signed":{"type":"integer"},"total":{"type":"integer"}}},"signers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"surname":{"type":"string"},"status":{"type":"string","enum":["pending","signed"]},"signedAt":{"type":"string","nullable":true},"signingUrl":{"type":"string","format":"uri"}}}},"finalization":{"type":"object","description":"Se incluye al consultar un documento individual. completed no implica que el cierre criptográfico ya esté listo.","properties":{"state":{"type":"string","enum":["not_started","pending","ready","blocked"]},"stage":{"type":"string"},"message":{"type":"string"}}},"links":{"type":"object","properties":{"self":{"type":"string","format":"uri"},"originalPdf":{"type":"string","format":"uri"},"finalPdf":{"type":"string","format":"uri","nullable":true,"description":"Disponible en la consulta individual cuando finalization.state es ready. Las descargas requieren Bearer."}}},"baseFinalSha256":{"type":"string","nullable":true,"description":"Hash del PDF base anterior al sello criptográfico de la plataforma. No es el hash del PDF final protegido descargado."}}},"WebhookEvent":{"type":"object","required":["id","type","createdAt","data"],"properties":{"id":{"type":"string","format":"uuid","description":"Identificador estable para deduplicar entregas."},"type":{"type":"string","enum":["document.created","signer.signed","document.completed","document.ready","document.cancelled","document.declined","document.expired","webhook.test"]},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"documentId":{"type":"string"},"status":{"type":"string"},"signerId":{"type":"string"},"signatures":{"type":"object","properties":{"signed":{"type":"integer"},"total":{"type":"integer"}}},"finalPdfPath":{"type":"string","description":"Disponible en document.ready. Descarga con la API Key, no con el secreto del webhook."},"test":{"type":"boolean"}}}}}}},"x-outbound-webhooks":{"setup":"Perfil → API Key → Webhook","method":"POST","contentType":"application/json","schema":{"$ref":"#/components/schemas/WebhookEvent"},"headers":["X-Firma-Delivery","X-Firma-Event","X-Firma-Timestamp","X-Firma-Signature"],"signature":"sha256=HMAC_SHA256(secret, timestamp + \".\" + rawBody)","delivery":"Hasta 5 intentos. Deduplicar id; no asumir orden. Destino HTTPS público en puerto 443; no se siguen redirecciones."},"servers":[{"url":"https://soldanifirma.alwaysdata.net"}]}