# Guía de Integración

> Guía para implementar un flujo de firma electrónica usando la API v2 de Legaldoc.io.

Guía para implementar un flujo de firma electrónica usando la API v2 de Legaldoc.io: crear un documento (envelope), agregar firmantes y campos, distribuirlo, y obtener el resultado firmado. Este flujo aplica a cualquier tipo de firma. Si tu caso de uso requiere verificar la identidad del firmante contra una entidad certificadora, ver el capítulo de [Firma Electrónica Avanzada](/guides/fea-orquestacion/).

---

## Flujo de Integración

---

## 1. Crear el envelope y los firmantes

```http
POST /envelope/create
```

Un **envelope** es el objeto central de la API: representa el documento (o conjunto de documentos) que vas a hacer firmar, junto con sus destinatarios, sus campos y su estado actual. Todo el flujo de firma gira en torno a un envelope — se crea una sola vez, y el resto de las llamadas (agregar campos, distribuir, consultar estado, descargar) actúan sobre el `id` que devuelve esta creación.

```jsonc
{
  "type": "DOCUMENT",
  "recipients": [
    {
      "name": "Nombre del firmante",
      "email": "firmante@ejemplo.cl",
      "role": "SIGNER",
      "signingOrder": 1
    }
  ]
}
```

`role` acepta `SIGNER`, `VIEWER`, `APPROVER`, `CC` o `ASSISTANT`, según qué participación tenga ese destinatario en el documento. `signingOrder` es opcional para firma simple — si no lo defines, los firmantes pueden firmar en cualquier orden.

Ver la especificación completa de este endpoint en la [Referencia de la API](/api/operations/envelope-create/).

---

## 2. Agregar campos de firma

```http
POST /envelope/field/create-many
```

Cada firmante necesita al menos un campo para poder firmar. Además de `SIGNATURE`, la API soporta campos de texto, fecha, checkbox, radio, dropdown y otros — ver la [Referencia de la API](/api/) para el detalle de cada tipo.

### Dónde ubicar el campo en el PDF

Hay dos formas de indicarle a Legaldoc dónde va cada campo, y son excluyentes entre sí:

| Forma | Campos | Cuándo usarla |
|---|---|---|
| **Placeholder** (recomendada) | `placeholder`, opcionalmente `width`, `height` | Siempre que puedas insertar un texto ancla en el PDF. |
| Coordenadas | `page`, `positionX`, `positionY`, `width`, `height` (en porcentaje) | Solo cuando no tienes control sobre el contenido del PDF. |

Con **placeholder**, le das a Legaldoc un texto ancla que buscar dentro del PDF:

```jsonc
{
  "recipientId": 456,
  "type": "SIGNATURE",
  "placeholder": "{{FIRMA_MANDANTE}}",
  "width": 30,
  "height": 8
}
```

Legaldoc busca ese texto en el documento, ubica el campo en su posición exacta y tapa el texto original con un rectángulo blanco antes de guardar. No necesitas calcular en qué página cae ni medir coordenadas, y si el documento cambia de largo entre una generación y otra —una plantilla con párrafos variables, por ejemplo— el campo se sigue ubicando correctamente sin que toques nada.

Si el placeholder no aparece en el PDF, la creación del campo falla de inmediato con un error claro (`Placeholder "..." not found in PDF`), antes de distribuir el documento y antes de que exista ningún firmante.

Con **coordenadas**, en cambio, indicas directamente la página y la posición como porcentaje del ancho/alto de la página. Úsalas solo cuando no puedas insertar un texto ancla en el PDF —por ejemplo, un documento escaneado o de un tercero.

<Aside type="caution" title="Coordenadas: valida la página antes de distribuir">
	Legaldoc no valida que la página exista al crear el campo — si indicas `page: 4` en un documento de 3 páginas, la llamada de creación no falla. El error recién aparece más adelante (el momento exacto depende del tipo de flujo — ver el detalle en el capítulo de [Firma Electrónica Avanzada](/guides/fea-orquestacion/#ubicación-del-campo-de-firma)), potencialmente con el firmante ya interactuando con el documento. Verifica tú mismo el número de páginas antes de crear campos por coordenadas.
</Aside>

Si usas placeholder, ponlo en su propia línea de texto, sin justificar el párrafo y sin espaciado extra entre letras o palabras: si el motor que genera tu PDF lo parte en varios fragmentos de texto, Legaldoc no lo reconoce como una sola cadena.

Ver la especificación completa de este endpoint en la [Referencia de la API](/api/operations/envelope-field-createmany/).

---

## 3. Preparar el documento

Antes de crear el envelope, decide el contenido final de tu PDF. **El documento no admite cambios de diseño una vez que empieza a firmarse**: no se pueden agregar páginas, marcas de agua, sellos ni ningún otro elemento visual después de la primera firma.

Esto no es una limitación de Legaldoc: es una propiedad de cómo funcionan las firmas digitales sobre PDF. Una firma cubre criptográficamente los bytes del documento en el momento en que se aplica; cualquier cambio posterior —aunque no toque el contenido firmado— hace que lectores como Adobe Acrobat reporten la firma como inválida o el documento como modificado.

<Aside type="tip" title="Qué hacer">
	Asegúrate de que tu PDF esté en su versión final —con toda la maquetación, numeración de páginas y contenido que quieras que el firmante vea— antes de crearlo en Legaldoc. Legaldoc aplica su propia marca de agua legal y el código de verificación antes de que exista cualquier firma, así que esa parte no requiere que hagas nada.
</Aside>

---

## 4. Distribuir y la experiencia de firma

```http
POST /envelope/distribute
```

Una vez distribuido, redirige a tu usuario a la URL de firma que devuelve la API (`recipients[].signingUrl`). Tu responsabilidad termina en redirigir al usuario, y vuelve a empezar cuando el usuario regresa a tu aplicación (mediante el `redirectUrl` que configuraste) o cuando recibes la notificación de que el documento cambió de estado.

Ver la especificación completa de este endpoint en la [Referencia de la API](/api/operations/envelope-distribute/).

---

## 5. Saber cuándo terminó

Usa **webhooks** para enterarte de cambios de estado sin tener que consultar activamente. Los eventos relevantes son `DOCUMENT_COMPLETED` y `DOCUMENT_REJECTED`.

Si prefieres o necesitas confirmar el estado de forma síncrona, consulta:

```http
GET /envelope/{envelopeId}
```

y revisa el campo `status`:

| Estado | Significado |
|---|---|
| `PENDING` | Aún faltan firmas o el proceso está en curso. |
| `COMPLETED` | Todos los firmantes completaron. El documento está disponible. |
| `REJECTED` | Un firmante rechazó firmar. Ver [sección 7](#7-rechazo). |

Ver la especificación completa de este endpoint en la [Referencia de la API](/api/operations/envelope-get/).

---

## 6. Descargar el documento firmado

```http
GET /envelope/item/{envelopeItemId}/download?version=signed
```

El PDF devuelto incluye las firmas aplicadas y la traza de auditoría del proceso.

Ver la especificación completa de este endpoint en la [Referencia de la API](/api/operations/envelope-item-download/).

---

## 7. Rechazo

Un firmante puede rechazar el documento en lugar de firmarlo. Cuando eso ocurre, el envelope pasa a estado `REJECTED` y recibes el evento `DOCUMENT_REJECTED` por webhook. El documento queda disponible reflejando el rechazo y su motivo.

---

## 8. Verificación por terceros

Todo documento generado por Legaldoc incluye un código QR y un código de verificación alfanumérico visibles en el documento. Cualquier persona que reciba una copia del documento —dentro o fuera de tu aplicación— puede escanear el código o visitar la página pública de verificación para confirmar su autenticidad, sin necesitar acceso a tu sistema ni al de Legaldoc. No necesitas construir nada para habilitar esto: viene incluido en el documento desde su creación.

---

## 9. Firma Electrónica Avanzada

Si tu caso de uso necesita certificar la identidad del firmante —por ejemplo, contratos que requieren validez legal reforzada— usa **Firma Electrónica Avanzada (FEA)**. Sobre el flujo que acabas de ver, FEA agrega: RUT del firmante, orden de firma secuencial, y evidencia adicional (certificado y auditoría) como descargas independientes.

Ver el capítulo completo: [Firma Electrónica Avanzada](/guides/fea-orquestacion/).

---

## 10. Resumen de endpoints

| Acción | Endpoint |
|---|---|
| Crear envelope | `POST /envelope/create` |
| Agregar campos de firma | `POST /envelope/field/create-many` |
| Distribuir | `POST /envelope/distribute` |
| Consultar estado | `GET /envelope/{envelopeId}` |
| Descargar documento firmado | `GET /envelope/item/{envelopeItemId}/download?version=signed` |

### Otros recursos de la API v2

Esta guía cubre el flujo mínimo de creación y firma. La API v2 expone además otros recursos — ver la [Referencia de API](/api/) para el detalle completo de cada uno:

| Recurso | Para qué sirve |
|---|---|
| `Envelope` (list, get-many, use, update, delete, cancel, duplicate, redistribute) | Gestión del ciclo de vida completo del envelope más allá de crear/distribuir/consultar: listar, cancelar, duplicar, reenviar, etc. |
| `Envelope Recipients` (get, create-many, update-many, delete, reject-on-behalf-of) | Gestión de firmantes después de creado el envelope, incluyendo rechazar en nombre de un firmante. |
| `Envelope Fields` (get, update-many, delete) | Gestión de campos individuales más allá de la creación masiva inicial. |
| `Envelope Items` (create-many, update-many, delete) | Gestión de los documentos/archivos dentro de un envelope. |
| `Envelope Attachments` | Adjuntos asociados a un envelope, independientes de los documentos a firmar. |
| `Folder` | Organización de envelopes en carpetas. |
| `Embedding` (presign tokens) | Generar y verificar tokens de firma para incrustar la experiencia de firma en tu propia aplicación, en vez de redirigir a `signingUrl`. |

---

## Errores frecuentes

| Situación | Causa habitual |
|---|---|
| La distribución falla con un error de validación | Falta un campo requerido, o un firmante no tiene ningún campo de firma asignado. |
| La creación del campo falla con `Placeholder "..." not found in PDF` | El texto ancla no existe tal cual en el PDF, o quedó partido en varios fragmentos por el motor de generación (justificado, espaciado de letras). |
| La descarga del documento devuelve error | El envelope todavía no está en estado `COMPLETED`. |