# 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.
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:
```http
Authorization: {API_KEY}
Content-Type: application/json
```
---
## Flujo de Integración
---
## 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
```http
GET https://app.legaldoc.io/api/v1/templates/18
```
### Response (simplificado)
```json
{
"id": 18,
"title": "Mi Contrato.pdf",
"recipients": [
{
"id": 52,
"name": "Destinatario",
"email": "destinatario@legaldoc.io",
"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
```http
POST https://app.legaldoc.io/api/v1/templates/18/generate-document
```
### Body
```json
{
"title": "Contrato - Cliente ABC",
"recipients": [
{
"id": 52,
"name": "Juan Pérez",
"email": "juan.perez@empresa.com"
}
]
}
```
### Response
```json
{
"documentId": 153,
"recipients": [
{
"recipientId": 174,
"name": "Juan Pérez",
"email": "juan.perez@empresa.com",
"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`:
```json
{
"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
```http
POST https://app.legaldoc.io/api/v1/templates/19/generate-document
```
```json
{
"title": "Contrato Boletín Comercial",
"recipients": [
{
"id": 144,
"name": "Juan Pérez",
"email": "juan.perez@empresa.com"
}
],
"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
```http
POST https://app.legaldoc.io/api/v1/documents/153/send
```
### Response
```json
{
"message": "Document sent for signing successfully",
"id": 153,
"status": "PENDING",
"recipients": [
{
"id": 174,
"name": "Juan Pérez",
"email": "juan.perez@empresa.com",
"token": "abc123XYZ",
"signingUrl": "https://app.legaldoc.io/sign/abc123XYZ"
}
]
}
```
---
## Paso 5: Widget Embebido
### 5.1 Incluir el Script
```html
```
### 5.2 Agregar el Componente
```html
```
### 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:**
```html
```
**Componente:**
```typescript
@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
```jsx
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 Cargando...
;
return (
);
};
```
---
## Personalización del Widget
### Variables CSS
```javascript
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 |