Guía de Integración API

Guía para implementar un flujo de firma electrónica usando la API de Legaldoc.io y el widget embebido.

---

Requisitos Previos

• API Key: Token de autenticación para la API
• Plantilla configurada: Una plantilla creada en el portal de Legaldoc.io

Autenticación

Todas las peticiones deben incluir:

Authorization: {API_KEY}
Content-Type: application/json

---

Flujo de Integración

1. Obtener IDde la Plantilla
2. Consultarla Plantilla
3. Generarel Documento
4. Enviara firma
5. Widgeto URL de firma

---

Paso 1: Obtener el ID de la Plantilla

El ID se obtiene desde la URL al editar una plantilla:

https://app.legaldoc.io/t/mi-equipo/templates/18
                                               ↑
                                         Template ID = 18

Configuración de Opciones de Email

Si no deseas que se envíen correos automáticos a los firmantes, debes configurar las Opciones de Email en la edición de la plantilla:

1. En el editor de plantilla, en General
2. En la sección Opciones de Email, desactivar todos los checkboxes de envío de correo:
   • ❌ Enviar correo electrónico firma completa del destinatario
   • ❌ Enviar correo electrónico de solicitud de firma del destinatario
   • ❌ Enviar correo electrónico de destinatario eliminado
   • ❌ Enviar correo electrónico de documento pendiente
   • ❌ Enviar correo electrónico de documento completado
   • ❌ Enviar correo electrónico de documento borrado
   • ❌ Enviar correo electrónico de documento completado al propietario

Nota: Con estas opciones desactivadas, deberás distribuir manualmente los enlaces de firma usando la API o el widget embebido.

---

Paso 2: Consultar la Plantilla

Obtener el ID del firmante configurado en la plantilla.

Request

GET https://app.legaldoc.io/api/v1/templates/18

Response (simplificado)

{
  "id": 18,
  "title": "Mi Contrato.pdf",
  "recipients": [
    {
      "id": 52,
      "name": "Destinatario",
      "email": "[email protected]",
      "role": "SIGNER"
    }
  ]
}

Importante: Guardar el recipients[].id (en este ejemplo: 52) para el siguiente paso.

---

Paso 3: Generar el Documento

Crear un documento a partir de la plantilla con los datos reales del firmante.

Request

POST https://app.legaldoc.io/api/v1/templates/18/generate-document

Body

{
  "title": "Contrato - Cliente ABC",
  "recipients": [
    {
      "id": 52,
      "name": "Juan Pérez",
      "email": "[email protected]"
    }
  ]
}

Response

{
  "documentId": 153,
  "recipients": [
    {
      "recipientId": 174,
      "name": "Juan Pérez",
      "email": "[email protected]",
      "token": "abc123XYZ",
      "role": "SIGNER",
      "signingUrl": "https://app.legaldoc.io/sign/abc123XYZ"
    }
  ]
}

Importante: Guardar el token (abc123XYZ) para usar en el widget embebido.

3.1 Pre-llenar Campos del Documento (Opcional)

Si necesitas que ciertos campos aparezcan con valores predeterminados, puedes usar prefillFields.

Ejemplo: Pre-llenar un campo de texto con número de cuenta corriente.

Paso previo: Identificar el campo

Del response del Paso 2 (Consultar Plantilla), busca el campo que deseas prellenar en el array fields:

{
  "id": 526,
  "type": "TEXT",
  "recipientId": 144,
  "fieldMeta": {
    "label": "Cta Corriente",
    "type": "text",
    "required": true
  }
}

Nota: Guarda el id del campo (en este ejemplo: 526).

Request con campos prellenados

POST https://app.legaldoc.io/api/v1/templates/19/generate-document

{
  "title": "Contrato Boletín Comercial",
  "recipients": [
    {
      "id": 144,
      "name": "Juan Pérez",
      "email": "[email protected]"
    }
  ],
  "prefillFields": [
    {
      "id": 526,
      "type": "text",
      "label": "Cta Corriente",
      "value": "12323123"
    }
  ]
}

El documento generado tendrá el campo “Cta Corriente” ya completado con el valor 12323123.

Hacer el campo de solo lectura

Si deseas que el firmante no pueda modificar el valor prellenado:

1. En el editor de plantilla de app.legaldoc.io, selecciona el campo, ingresa a ajustes avanzados
2. Activa la opción “Sólo lectura” en las propiedades del campo
3. Guarda la plantilla

De esta forma, el campo aparecerá prellenado y bloqueado para edición.

---

Paso 4: Enviar el Documento

Activar el documento para firma.

Request

POST https://app.legaldoc.io/api/v1/documents/153/send

Response

{
  "message": "Document sent for signing successfully",
  "id": 153,
  "status": "PENDING",
  "recipients": [
    {
      "id": 174,
      "name": "Juan Pérez",
      "email": "[email protected]",
      "token": "abc123XYZ",
      "signingUrl": "https://app.legaldoc.io/sign/abc123XYZ"
    }
  ]
}

---

Paso 5: Widget Embebido

5.1 Incluir el Script

<script src="https://cdn.legaldoc.io/v1.0/embed.js"></script>

5.2 Agregar el Componente

<legaldoc-embed-sign-document
  token="abc123XYZ"
  host="https://app.legaldoc.io"
  css="width: 100%; height: 890px; border: none; border-radius: 8px;"
>
</legaldoc-embed-sign-document>

Atributos Disponibles

Atributo	Tipo	Descripción
token	string	Requerido. Token del firmante
host	string	URL de Legaldoc.io
lockName	boolean	Bloquea el campo nombre
lockEmail	boolean	Bloquea el campo email
darkModeDisabled	boolean	Deshabilita modo oscuro
css	string	Estilos CSS del iframe

5.3 Ejemplo en Angular

Template:

<legaldoc-embed-sign-document
  *ngIf="legaldocToken"
  id="legaldoc-component"
  [attr.token]="legaldocToken"
  host="https://app.legaldoc.io"
  css="width: 100%; height: 890px; border: none; border-radius: 8px;"
>
</legaldoc-embed-sign-document>

Componente:

@Component({
  selector: "app-firma-documento",
  templateUrl: "./firma-documento.component.html",
})
export class FirmaDocumentoComponent implements OnChanges, AfterViewInit {
  @Input() empresaData: any;
  legaldocToken: string = "";

  constructor(private _cdr: ChangeDetectorRef) {}

  ngOnChanges(changes: SimpleChanges): void {
    if (changes["empresaData"]?.currentValue?.token) {
      this.legaldocToken = changes["empresaData"].currentValue.token;
      this._cdr.detectChanges();
      setTimeout(() => this.configureLegaldocComponent(), 200);
    }
  }

  ngAfterViewInit(): void {
    if (this.empresaData?.token) {
      this.legaldocToken = this.empresaData.token;
      setTimeout(() => this.configureLegaldocComponent(), 100);
    }
  }

  private configureLegaldocComponent(): void {
    const element = document.getElementById("legaldoc-component") as any;
    if (element) {
      element.darkModeDisabled = true;
      element.lockName = true;
      element.lockEmail = true;
      element.cssVars = {
        background: "#ffffff",
        foreground: "#2c3e50",
        primary: "#60B22E",
      };
    }
  }
}

5.4 Ejemplo en React

import { useEffect, useRef } from 'react';

export const FirmaDocumento = ({ token }) => {
  const widgetRef = useRef(null);

  useEffect(() => {
    // Cargar script de Legaldoc
    const script = document.createElement('script');
    script.src = 'https://cdn.legaldoc.io/v1.0/embed.js';
    script.async = true;
    document.body.appendChild(script);

    return () => document.body.removeChild(script);
  }, []);

  useEffect(() => {
    if (!token || !widgetRef.current) return;

    const element = widgetRef.current;
    element.darkModeDisabled = true;
    element.lockName = true;
    element.lockEmail = true;
    element.cssVars = {
      background: '#ffffff',
      foreground: '#2c3e50',
      primary: '#60B22E',
    };

    element.onDocumentCompleted = () => {
      console.log('Documento firmado exitosamente');
    };
  }, [token]);

  if (!token) return <div>Cargando...</div>;

  return (
    <legaldoc-embed-sign-document
      ref={widgetRef}
      token={token}
      host="https://app.legaldoc.io"
      style={{ width: '100%', height: '890px', border: 'none', borderRadius: '8px' }}
    />
  );
};

---

Personalización del Widget

Variables CSS

element.cssVars = {
  background: "#ffffff", // Fondo
  foreground: "#2c3e50", // Texto
  primary: "#60B22E", // Color principal (botones)
};

Eventos

Evento	Descripción
onDocumentReady	Documento listo para firmar
onDocumentCompleted	Firma completada
onDocumentError	Error en el proceso