Firma Electrónica Avanzada

Este capítulo explica cómo integrar Firma Electrónica Avanzada (FEA) en tu aplicación: qué construyes tú, qué hace Legaldoc, y qué le entregas a tu usuario al final. Se apoya en el flujo general que ya viste en la Guía de Integración — crear un envelope, agregar firmantes y campos, distribuirlo — y describe qué cambia cuando ese envelope necesita FEA.

Si nunca has creado un documento con la API, empieza por la Guía de Integración. Este capítulo asume que ya sabes crear un envelope, agregar firmantes y campos, y distribuirlo.

---

1. Qué es FEA y qué cambia

La Firma Electrónica Avanzada certifica la identidad del firmante contra una entidad certificadora autorizada, usando el RUT como credencial. A diferencia de la firma simple, el firmante debe verificar su identidad y confirmar con un segundo factor antes de que la firma quede aplicada.

Para tu integración, esto significa tres diferencias concretas respecto a un envelope normal:

• El firmante necesita un RUT válido.
• El orden de firma debe ser secuencial, aunque tengas un solo firmante.
• Cada firmante tiene exactamente un campo de firma.

El resto del ciclo de vida —crear, distribuir, monitorear, completar— es igual al de cualquier documento. La preparación del documento (sección 3 de la Guía de Integración) también aplica igual: con FEA, con más razón, el PDF debe estar en su versión final antes de crear el envelope.

---

2. Crear el envelope y los firmantes

Sobre el ejemplo general, un envelope con FEA agrega el RUT del firmante y fuerza el orden secuencial:

{
  "type": "DOCUMENT",
  "globalActionAuth": ["FAO_HASH"],
  "recipients": [
    {
      "name": "Nombre del firmante",
      "email": "[email protected]",
      "rut": "12345678-9",
      "role": "SIGNER",
      "signingOrder": 1
    }
  ],
  "meta": {
    "signingOrder": "SEQUENTIAL"
  }
}

El nombre que envías y el nombre verificado

El campo name que envías es informativo: identifica al destinatario para efectos de envío de correos y presentación en tu propia interfaz. No es la identidad legal de la firma.

Cuando el firmante completa la verificación con su entidad certificadora, Legaldoc obtiene el nombre completo asociado a ese RUT y es ese el que queda estampado en el documento y en el certificado de firma. Si el nombre que enviaste difiere del verificado, el certificado de firma muestra ambos, para que quede explícito cuál es cuál.

Qué hacer

No asumas que el nombre visible en el documento final es el mismo que enviaste. Si tu aplicación necesita mostrar “quién firmó” después del hecho, consulta el certificado de firma (sección 4) en vez de tu propio registro.

Validaciones que ocurren al distribuir

Legaldoc valida las reglas de FEA (RUT, orden secuencial, un campo por firmante, roles permitidos) en el momento de distribuir el envelope, no al crearlo. Si tu integración construye el envelope en varios pasos, verifica estas condiciones en tu propio código antes de intentar distribuir, para darle a tu usuario un error temprano y claro en vez de uno tardío.

Ubicación del campo de firma

La Guía de Integración explica las dos formas de indicar dónde va un campo: placeholder o coordenadas. Con FEA, el riesgo de usar coordenadas es distinto —y menor— gracias a la misma validación al distribuir que se menciona arriba.

En un envelope estándar, un page inválido en una llamada por coordenadas no falla hasta que se sella el documento, con el firmante ya habiendo firmado. Con FEA, Legaldoc prepara el documento completo —marca de agua, QR y los campos de firma ya ubicados— en el momento de POST /envelope/distribute, no al sellar. Si una coordenada no calza, distribute falla ahí mismo, todavía sin firmantes. Sigue siendo un error evitable —el placeholder lo elimina antes incluso de llegar a distribuir— pero si tu PDF es fijo y ya mediste la posición a mano, usar coordenadas en FEA no tiene el riesgo catastrófico que tiene en el flujo estándar.

Un detalle propio de FEA: recuerda que cada firmante debe tener exactamente un campo de firma (sección 1). Si usas matchAll: true con un placeholder que aparece más de una vez en el documento, se crea un campo por cada aparición — evita matchAll en FEA a menos que el placeholder aparezca una sola vez por firmante.

---

3. La experiencia de firma

Una vez distribuido, redirige a tu usuario a la URL de firma que devuelve la API (recipients[].signingUrl), igual que en el flujo general.

A partir de ahí, todo el proceso de verificación de identidad y confirmación ocurre dentro de la página de Legaldoc: el enrolamiento con la entidad certificadora (si es la primera vez) y el segundo factor de autenticación. Tu aplicación no participa en ese intercambio y no necesita construir ninguna pantalla para él.

Si tu usuario cierra el navegador antes de completar el enrolamiento o la firma, el envelope queda PENDING y puede retomarlo volviendo a la misma URL de firma, si aún es válida, o solicitando que reenvíes la notificación.

---

4. Entregar la evidencia

Cuando el envelope está COMPLETED, con FEA hay tres artefactos disponibles, no uno:

Artefacto	Endpoint	Contenido
Documento firmado	GET /envelope/item/{envelopeItemId}/download?version=signed	El PDF con las firmas aplicadas.
Certificado de firma	GET /envelope/{envelopeId}/certificate/download	Quién firmó, con qué identidad verificada, cuándo, y con qué nivel de autenticación.
Registro de auditoría	GET /envelope/{envelopeId}/audit-log/download	La traza completa de eventos del proceso (envío, visualización, firma, finalización).

Por qué son archivos separados

En un flujo de firma simple, el certificado y la auditoría pueden anexarse como páginas adicionales del mismo PDF, porque se agregan antes de que exista ninguna firma.

Con FEA eso no es posible: el certificado describe información que solo existe después de que el firmante firmó (su identidad verificada, la hora exacta). No hay forma de anexarlo al documento sin invalidar, en la práctica, la firma que ya se aplicó.

Qué hacer

Ofrece los tres como descargas independientes en tu interfaz. No intentes combinarlos en un solo archivo. El documento firmado es tu entregable principal; el certificado y la auditoría son su respaldo, y conviene presentarlos como tales —por ejemplo, como acciones secundarias junto a la descarga principal.

Si necesitas la auditoría en formato de datos en vez de PDF (para integrarla a tu propio sistema en vez de mostrarla), está disponible también como JSON en GET /envelope/{envelopeId}/audit-log.

---

5. Rechazo

Un firmante puede rechazar el documento en lugar de firmarlo. Cuando eso ocurre:

• El envelope pasa a estado REJECTED.
• Recibes el evento DOCUMENT_REJECTED por webhook.
• El documento y el certificado de firma (si corresponde) quedan disponibles reflejando el rechazo y su motivo.

Si el rechazo ocurre antes de que exista alguna firma, no hay evidencia de firma que preservar. Si ocurre después de que otro firmante ya firmó (en un flujo con múltiples firmantes), esa firma previa se conserva intacta como parte del historial del documento.

---

6. Resumen de endpoints

Además de los endpoints generales (crear, agregar campos, distribuir, consultar estado — ver la Guía de Integración), FEA agrega la descarga del certificado y la auditoría:

Acción	Endpoint
Descargar certificado de firma	GET /envelope/{envelopeId}/certificate/download
Descargar auditoría (PDF)	GET /envelope/{envelopeId}/audit-log/download
Consultar auditoría (JSON)	GET /envelope/{envelopeId}/audit-log

---

Errores frecuentes

Situación	Causa habitual
La distribución falla con un error de validación	Falta el RUT de un firmante, el orden de firma no es secuencial, o hay más de un campo de firma por firmante.
La descarga del certificado o la auditoría devuelve error	El envelope todavía no está en estado COMPLETED.
El nombre en el documento no coincide con el que envié	Es esperable: el documento y el certificado muestran la identidad verificada, no la enviada. Ver sección 2.