# Firma Electrónica Avanzada
> Qué agrega la Firma Electrónica Avanzada (FEA) sobre el flujo general de la API v2 de Legaldoc.io, y cómo orquestarlo.
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](/guides/integration-guide/) — 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](/guides/integration-guide/). 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:
```jsonc
{
"type": "DOCUMENT",
"globalActionAuth": ["FAO_HASH"],
"recipients": [
{
"name": "Nombre del firmante",
"email": "firmante@ejemplo.cl",
"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.
### 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](/guides/integration-guide/#2-agregar-campos-de-firma) 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ó.
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](/guides/integration-guide/#10-resumen-de-endpoints)), 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](#2-crear-el-envelope-y-los-firmantes). |