Guía de Integración

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.

---

Flujo de Integración

1. Crearel envelope
2. Agregarcampos de firma
3. Distribuiry firmar
4. Consultarel estado
5. Descargarel resultado

---

1. Crear el envelope y los firmantes

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.

{
  "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.

---

2. Agregar campos de firma

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 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:

{
  "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.

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), potencialmente con el firmante ya interactuando con el documento. Verifica tú mismo el número de páginas antes de crear campos por coordenadas.

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.

---

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.

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.

---

4. Distribuir y la experiencia de firma

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.

---

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:

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.

Ver la especificación completa de este endpoint en la Referencia de la API.

---

6. Descargar el documento firmado

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.

---

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.

---

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 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.