Protocolo HTTP PAdES
La función AL FirmarPdf coordina este protocolo. Si solo necesitas consumirla, empieza por Firmar desde AL. Aquí se describe la integración HTTP y sus estados.
Secuencia
| Paso | Operación | Resultado |
|---|---|---|
| 1 | BC resuelve alias para empresa/usuario | Certificado autorizado |
| 2 | POST /v1/pades-signature-requests/prepare |
requestId, atributos DER y caducidad |
| 3 | BC firma los bytes DER decodificados | Firma RSA cruda |
| 4 | POST /v1/pades-signature-requests/{requestId}/complete |
Estado firmado y hash |
| 5 | GET /v1/pades-signature-requests/{requestId}/result |
PDF binario |
Todas las rutas HTTP usan bearer BC. La consulta de estado es GET /v1/pades-signature-requests/{requestId}. complete no devuelve los bytes del PDF; la descarga es una petición separada.
Preparar
prepare requiere Idempotency-Key y JSON con pdfBase64, externalRef, certificateAlias y certificateBase64. Puede recibir certificateChainBase64, documentName, signingMetadata y expiresAt; los campos exactos están en openapi.yaml.
El certificado hoja y cada elemento de la cadena son X.509 DER públicos en Base64. El backend no recibe PFX, contraseña ni clave privada. El alias es metadato de auditoría; el servicio no lo resuelve ni autoriza usuarios individuales.
Enviar solo la hoja está soportado. Omite certificateChainBase64 si no tienes los emisores: la API los resuelve mediante AIA DER/PEM/PKCS#7, catálogo público y raíces del sistema, independientemente de la entidad. Ejemplo mínimo, sustituyendo los marcadores por datos reales:
{
"pdfBase64": "<PDF_ORIGINAL_EN_BASE64>",
"externalRef": "CHECKIN-001",
"certificateAlias": "recepcion",
"certificateBase64": "<CERTIFICADO_HOJA_DER_EN_BASE64>"
}
La imagen API incluye UANATACA CA1 2021 y ROOT 2016 desde 0.2.14; para esa CA, actualizar/redesplegar la API no requiere subir intermedios, configurar variables nuevas ni cambiar BC. Para otras entidades se usa el mismo mecanismo automático; un catálogo adicional es solo un respaldo operativo cuando no hay AIA accesible. Consulta Configuración.
Respuesta nueva 201; una repetición idéntica devuelve 200 con la misma solicitud. Guarda requestId, toBeSignedBase64, certificateThumbprint y expiresAt. No cambies clave de idempotencia ni payload al recuperar una respuesta perdida.
Firmar y completar
BC decodifica toBeSignedBase64 y firma esos bytes binarios exactos con SHA-256 y RSA PKCS#1 v1.5. No se firma el PDF, el texto Base64 ni un hash calculado por el cliente.
Entrada de complete:
{"signatureValueBase64":"<FIRMA_RSA_REAL_EN_BASE64>"}
La API verifica la firma, ensambla CMS CAdES detached, lo inserta en el PDF preparado y publica el resultado. Una repetición con la misma firma recupera el resultado; una distinta produce conflicto.
El CMS de las nuevas operaciones contiene los intermedios verificados y omite la raíz. Tras actualizar, firma el PDF original con una operación nueva para obtener un nuevo resultado: una descarga o recuperación de una operación anterior no reescribe su PDF. Cadena completa no equivale a confianza reconocida por Adobe u otro lector; consulta Errores y avisos del lector.
Estados y recuperación
| Estado | Significado | Acción |
|---|---|---|
prepared |
Espera la firma | Completar antes de expiresAt |
completing |
Otro intento mantiene el lease | Consultar estado y esperar |
signed |
Resultado registrado | Descargar si disponible |
expired |
Preparación vencida | Crear una operación nueva |
error |
Incidencia | Revisar código, logs e integridad |
El mantenimiento puede liberar un lease abandonado y volver a prepared, o llevarlo a expired si ya venció. Ante 409, consulta estado: puede ser concurrencia o reutilización incompatible. Ante 410, revisa el código: SIGNATURE_REQUEST_EXPIRED y SIGNED_RESULT_PURGED requieren acciones distintas.
En AL, conserva el mismo OperationId, PDF, alias, empresa, usuario y certificado para recuperar. La extensión deriva una clave incluyendo empresa/usuario/operación. El backend actual tiene un único ámbito de integración por bearer.
Retención e integridad
La consulta informa hashes y resultAvailable. Una purga legítima mantiene signed e informa resultPurgedAt; la descarga y el reintento de completado devuelven 410 SIGNED_RESULT_PURGED. Un archivo ausente o alterado sin purga registrada devuelve 422 SIGNED_PDF_CORRUPT.
Perfil y límites
PAdES Baseline B-B, RSA ≥2048, SHA-256 y PKCS#1 v1.5. El backend resuelve emisores automáticamente mediante catálogo público y AIA HTTP(S) controlado; verifica la cadena y congela su instantánea antes de preparar. BC puede enviar solo la hoja. Emisores no resolubles, falsificados o ajenos devuelven 422 CERTIFICATE_CHAIN_INVALID. No hay TSA, perfiles B-T/LT/LTA ni afirmación de confianza pública/OCSP/CRL. Se rechazan PDFs cifrados y documentos con firma/ByteRange previos; no se admiten firmas incrementales múltiples. La reserva CMS es de 32 KiB y se comprueba con los intermedios antes de preparar.
Swagger permite preparar/consultar, pero no accede a la clave privada de BC. Para certificados y rotación, usa Configurar certificados.
Firma visible con certificado
El objeto opcional visibleSignature de prepare amplía el contrato y contiene las cinco propiedades obligatorias: pageNumber (empieza en 1), x, y, width y height. Omítelo o envía null para una firma invisible. Usa el espacio de coordenadas de usuario predeterminado del PDF original sin rotación, con origen en la esquina inferior izquierda e incluyendo los desplazamientos de recorte y página. PDF.js convierte el rectángulo mostrado mediante convertToPdfPoint; no envíes píxeles CSS. El rectángulo debe caber en la intersección de CropBox y MediaBox y medir al menos 180 × 72 puntos en la orientación mostrada, después de aplicar la rotación y /UserUnit. Se toleran redondeos numéricos de hasta 0.000001. La ausencia de propiedades devuelve 400; la geometría inválida o un texto ilegible devuelve 422 SIGNATURE_PLACEMENT_INVALID antes de guardar datos.
La presentación visible usa el titular real del certificado y su emisor, junto con la hora de preparación fijada en UTC. Se crea antes de calcular el hash, con una fuente incrustada, y queda protegida por la firma CMS. No añade páginas. Conserva exactamente el mismo PDF, posición, certificado, alias y metadatos al reutilizar Idempotency-Key; cambiar o eliminar la posición devuelve 409. La huella de las solicitudes invisibles anteriores permanece igual. Consulta OpenAPI para ver el esquema completo.