> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firma.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Marca Blanca

> Configura marca personalizada, dominios de correo, plantillas de correo y experiencias incrustadas para crear una experiencia de firma totalmente personalizada para tus clientes.

Firma ofrece funciones completas de marca blanca que te permiten crear una experiencia de firma electrónica totalmente personalizada. Desde logotipos y temas de color personalizados hasta interfaces incrustadas, puedes asegurarte de que tus clientes interactúen con tu marca durante todo el proceso de firma.

## Descripción general

La marca blanca en Firma involucra varios componentes:

1. **Marca personalizada** - Sube logotipos, define temas de color y oculta la marca de Firma por completo
2. **Términos personalizados para firmantes** - Exige a los firmantes que acepten tus propios términos de servicio
3. **Etiquetas de los botones de firma** - Personaliza el texto de los botones de firma por idioma
4. **Dominios de correo personalizados** - Envía correos de solicitudes de firma desde tu propio dominio
5. **Dirección de remitente de correo personalizada** - Controla la dirección "de" en todos los correos salientes
6. **Plantillas de correo personalizadas** - Personaliza el contenido y la marca de los correos de notificación de firma
7. **Desactivar los correos de Firma** - Desactiva los correos automáticos por solicitud de firma y envía los tuyos propios
8. **Experiencias incrustadas** - Incrusta los editores de firma y de plantillas directamente en tu aplicación

<Note>
  Todos los ejemplos de la API usan tu clave API directamente en el encabezado `Authorization`. No uses el prefijo `Bearer`.
</Note>

***

## Marca personalizada

Personaliza logotipos, colores y la visibilidad de la marca tanto a nivel de empresa como de espacio de trabajo. La configuración del espacio de trabajo tiene prioridad sobre la de la empresa, lo que te permite crear experiencias de marca distintas para cada uno de tus clientes.

### Logotipo de la empresa

Sube un logotipo para toda tu cuenta de Firma. Este logotipo aparece en los correos de firma y en la experiencia de firma.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@/path/to/logo.png"
```

**Requisitos:**

* Formato: solo PNG o JPEG
* Tamaño máximo: 2 MB

Para eliminar el logotipo de la empresa:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
  -H "Authorization: YOUR_API_KEY"
```

### Logotipo del espacio de trabajo

Sobrescribe el logotipo de la empresa para un espacio de trabajo específico:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@/path/to/workspace-logo.png"
```

Para eliminar el logotipo de un espacio de trabajo (recurre al logotipo de la empresa):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
  -H "Authorization: YOUR_API_KEY"
```

### Temas de color

Personaliza la paleta de colores de la experiencia de firma usando valores de color hexadecimales. Los colores se pueden definir tanto a nivel de empresa como de espacio de trabajo.

| Configuración de color | Descripción                                  | Valor predeterminado de Firma |
| ---------------------- | -------------------------------------------- | ----------------------------- |
| `color_primary`        | Color de acento principal (botones, enlaces) | `#c285ff`                     |
| `color_primary_fg`     | Color de texto en elementos primarios        | `#ffffff`                     |
| `color_background`     | Fondo de la página                           | `#1c1c21`                     |
| `color_foreground`     | Color de texto principal                     | `#ffffff`                     |
| `color_card`           | Fondo de tarjeta/panel                       | `#22222a`                     |
| `color_border`         | Color de borde                               | `#3b3b3b`                     |
| `color_accent`         | Color de acento secundario                   | `#c285ff`                     |
| `color_accent_fg`      | Color de texto en elementos de acento        | `#ffffff`                     |
| `color_canvas`         | Fondo del lienzo/visor de documentos         | `#1c1c21`                     |
| `color_muted`          | Áreas de fondo atenuadas/sutiles             | `#22222a`                     |
| `color_muted_fg`       | Color de texto en áreas atenuadas            | `#a1a1aa`                     |

**Definir colores a nivel de empresa:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Definir colores a nivel de espacio de trabajo** (sobrescribe los colores de la empresa para este espacio de trabajo):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Los colores deben ser valores hexadecimales de 6 dígitos (por ejemplo, `#0066cc`). Define un color como `null` para eliminarlo y recurrir al siguiente nivel de la jerarquía.

### Ocultar la marca de Firma

Elimina toda la marca de Firma de la experiencia de firma habilitando `show_custom_branding_only` a nivel de empresa:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "show_custom_branding_only": true
  }'
```

### Configuraciones de visualización adicionales

Ajusta la experiencia de firma con estas configuraciones, disponibles tanto a nivel de empresa como de espacio de trabajo:

| Configuración               | Descripción                                                         | Valor predeterminado |
| --------------------------- | ------------------------------------------------------------------- | -------------------- |
| `show_signature_frame`      | Muestra el marco/borde de dibujo de la firma                        | `true`               |
| `show_partial_watermark`    | Muestra una marca de agua en documentos parcialmente firmados       | `false`              |
| `show_qr_code`              | Incluye un código QR que enlaza a la página de firma en los correos | `false`              |
| `require_otp_verification`  | Exige verificación OTP por correo antes de firmar                   | `false`              |
| `require_terms_acceptance`  | Exige a los firmantes aceptar los términos antes de firmar          | `true`               |
| `disable_guided_navigation` | Desactiva la navegación guiada paso a paso por los campos           | `false`              |
| `allow_presigning_download` | Permite a los firmantes descargar el documento antes de firmar      | `false`              |

A nivel de espacio de trabajo, define estos valores como `null` para heredar la configuración a nivel de empresa.

### Jerarquía de configuración

La configuración de marca sigue una jerarquía en cascada:

1. **Configuración del espacio de trabajo** (máxima prioridad)
2. **Configuración de la empresa**
3. **Valor predeterminado de Firma** (mínima prioridad)

Esto te permite definir valores predeterminados a nivel de toda la empresa y sobrescribirlos por espacio de trabajo. A nivel de espacio de trabajo, definir un valor como `null` significa "heredar de la empresa".

Consulta la [Referencia de la API de configuración de espacio de trabajo](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) para ver la lista completa de configuraciones disponibles.

***

## Términos personalizados para firmantes

Exige a los firmantes que acepten tus propios términos de servicio o acuerdo legal antes de firmar. Los términos se configuran por idioma y siguen la misma cascada empresa/espacio de trabajo que otras configuraciones.

### Cómo funciona

Cuando `require_terms_acceptance` está habilitado (el valor predeterminado), los firmantes ven una casilla de aceptación de términos antes de poder firmar. Puedes personalizar el texto de la declaración y, opcionalmente, enlazar a un documento de términos completo.

Los términos se almacenan por idioma para que los firmantes vean los términos en el idioma de su espacio de trabajo, recurriendo a la siguiente cascada:

1. **Términos del espacio de trabajo** para el idioma del firmante (máxima prioridad)
2. **Términos de la empresa** para el idioma del firmante
3. **Términos predeterminados de Firma** (mínima prioridad)

### Definir términos a nivel de empresa

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Definir términos a nivel de espacio de trabajo

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Campos:**

* `statement_text` (obligatorio): texto HTML que se muestra junto a la casilla de aceptación. Se permiten etiquetas HTML básicas (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (opcional): URL al documento de términos completo.

### Listar términos

Recupera todos los términos configurados para una empresa o espacio de trabajo:

```bash theme={null}
# Términos de la empresa
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
  -H "Authorization: YOUR_API_KEY"

# Términos del espacio de trabajo
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
  -H "Authorization: YOUR_API_KEY"
```

### Eliminar términos

Elimina los términos personalizados para un idioma específico para recurrir al siguiente nivel de la cascada:

```bash theme={null}
# Eliminar términos de la empresa en inglés
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
  -H "Authorization: YOUR_API_KEY"

# Eliminar términos del espacio de trabajo en inglés
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
  -H "Authorization: YOUR_API_KEY"
```

### Desactivar la aceptación de términos

Para desactivar por completo el requisito de aceptación de términos:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "require_terms_acceptance": false
  }'
```

Idiomas admitidos: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

Consulta la [Referencia de la API de términos para firmantes](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) para la documentación completa de los endpoints.

***

## Etiquetas personalizadas de los botones de firma

Personaliza el texto de los botones de firma por espacio de trabajo y por idioma. Esto te permite ajustar las etiquetas de los botones a la terminología o localización de tu producto.

### Definir anulaciones de etiquetas de botones

Las etiquetas de los botones se definen como un objeto JSONB en la configuración del espacio de trabajo, organizado por idioma y luego por clave de botón:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signing_button_label_overrides": {
      "en": {
        "sign": "Approve and Sign",
        "next": "Continue",
        "finish": "Complete Signing"
      },
      "es": {
        "sign": "Aprobar y Firmar",
        "next": "Continuar",
        "finish": "Completar Firma"
      }
    }
  }'
```

### Eliminar anulaciones de etiquetas de botones

Define el valor como `null` para volver a las etiquetas de botones predeterminadas de Firma:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signing_button_label_overrides": null
  }'
```

**Validación:**

* Cada etiqueta debe ser una cadena de texto, máximo 500 caracteres
* Las claves de idioma deben ser códigos de idioma válidos (máximo 10 caracteres)
* Las etiquetas HTML y los caracteres de control se eliminan automáticamente

<Note>
  Las anulaciones de etiquetas de botones son una configuración solo a nivel de espacio de trabajo. No existe una anulación a nivel de empresa.
</Note>

***

## Dominios de correo personalizados

De forma predeterminada, los correos de solicitud de firma se envían desde el dominio de Firma. Con dominios de correo personalizados, los correos parecen provenir directamente de tu empresa o de las empresas de tus clientes.

### Dominios de correo a nivel de cuenta (empresa)

Configura un dominio de correo personalizado para toda tu cuenta de Firma. Todos los espacios de trabajo usarán este dominio de forma predeterminada, a menos que se sobrescriba.

#### Paso 1: Agrega tu dominio

Usa la API para agregar un dominio de correo personalizado:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "acme.com"
  }'
```

**Respuesta (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "firma-verify=abc123xyz",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "firma-verify=abc123xyz",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Paso 2: Agrega el registro TXT de verificación

Agrega el registro TXT de verificación a tu DNS:

| Tipo | Nombre                         | Valor                    |
| ---- | ------------------------------ | ------------------------ |
| TXT  | `_firma-verification.acme.com` | `firma-verify=abc123xyz` |

<Note>
  La propagación del DNS normalmente tarda unos minutos, pero puede tardar hasta 48 horas.
</Note>

#### Paso 3: Verifica la propiedad del dominio

Una vez agregado el registro TXT, verifica la propiedad:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
  -H "Authorization: YOUR_API_KEY"
```

**Respuesta**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Paso 4: Finaliza la configuración del dominio

Una vez verificada la propiedad, finaliza el dominio para recibir los registros DNS de envío de correo:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
  -H "Authorization: YOUR_API_KEY"
```

**Respuesta**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Paso 5: Agrega los registros DNS

Agrega los tres registros DNS a tu dominio:

| Tipo  | Nombre              | Valor                               |
| ----- | ------------------- | ----------------------------------- |
| TXT   | `@`                 | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com`   |
| TXT   | `_dmarc`            | `v=DMARC1; p=none;`                 |

#### Paso 6: Verifica los registros DNS

Una vez agregados los registros DNS, verifícalos:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
  -H "Authorization: YOUR_API_KEY"
```

**Respuesta (todo verificado)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Paso 7: Definir como dominio principal (opcional)

Si tienes varios dominios, define uno como predeterminado:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
  -H "Authorization: YOUR_API_KEY"
```

### Dominios de correo a nivel de espacio de trabajo

Para aplicaciones SaaS multiempresa, puedes configurar dominios de correo distintos por espacio de trabajo. Los dominios del espacio de trabajo sobrescriben el dominio a nivel de empresa.

El flujo es idéntico al de los dominios de empresa, pero usa endpoints con alcance de espacio de trabajo:

| Acción                  | Endpoint                                                       |
| ----------------------- | -------------------------------------------------------------- |
| Listar dominios         | `GET /workspace/{workspace_id}/domains`                        |
| Agregar dominio         | `POST /workspace/{workspace_id}/domains`                       |
| Obtener dominio         | `GET /workspace/{workspace_id}/domains/{id}`                   |
| Eliminar dominio        | `DELETE /workspace/{workspace_id}/domains/{id}`                |
| Verificar propiedad     | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalizar configuración | `POST /workspace/{workspace_id}/domains/{id}/finalize`         |
| Verificar DNS           | `POST /workspace/{workspace_id}/domains/{id}/verify-dns`       |
| Definir como principal  | `POST /workspace/{workspace_id}/domains/{id}/set-primary`      |

**Ejemplo: agregar un dominio de espacio de trabajo**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "sign.acmecorp.com"
  }'
```

Consulta la [Referencia de la API de dominios de correo](/api-reference/v01.27.00/email-domains/list-company-domains) para la documentación completa de los endpoints.

***

## Dirección de remitente de correo personalizada

Controla la dirección "de" en todos los correos salientes combinando un dominio personalizado con una parte local personalizada.

### Cómo se resuelven las direcciones de correo

Cuando Firma envía un correo, la dirección del remitente se construye a partir de tres componentes:

```
{sender_name} <{local_part}@{domain}>
```

Cada componente se resuelve mediante una cadena de respaldo:

**Resolución del dominio:**

1. Dominio verificado del espacio de trabajo (se prefiere el principal)
2. Dominio verificado de la empresa
3. `updates.firma.dev` (predeterminado)

**Resolución de la parte local** (solo aplica cuando se usa un dominio personalizado):

1. Configuración `email_local_part` del espacio de trabajo
2. Configuración `email_local_part` de la empresa
3. `support` (predeterminado)

**El nombre del remitente** es el nombre del usuario que envió la solicitud de firma.

Por ejemplo, si defines `email_local_part` como `noreply` y tu dominio verificado es `sign.acmecorp.com`, los correos se enviarán desde:

```
Jane Smith <noreply@sign.acmecorp.com>
```

### Configurar la parte local del correo

**Nivel de empresa** (predeterminado para todos los espacios de trabajo):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email_local_part": "noreply"
  }'
```

**Nivel de espacio de trabajo** (sobrescribe la configuración de la empresa):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email_local_part": "signing"
  }'
```

**Reglas de validación:**

* De 1 a 64 caracteres, letras minúsculas, números, puntos, guiones bajos y guiones
* Debe comenzar y terminar con una letra o número
* Sin puntos consecutivos
* No se permiten valores reservados (`postmaster`, `abuse`, `mailer-daemon`)

Define el valor como `null` a nivel de espacio de trabajo para heredar de la configuración de la empresa.

***

## Plantillas de correo personalizadas

Personaliza los correos de notificación que Firma envía en tu nombre para que coincidan con la voz y el estilo de tu marca. Puedes definir plantillas tanto a nivel de empresa como de espacio de trabajo, con las plantillas del espacio de trabajo sobrescribiendo las predeterminadas de la empresa.

### Tipos de correo personalizables

| Tipo de correo            | Cuándo se envía                                                                  |
| ------------------------- | -------------------------------------------------------------------------------- |
| `signing_invite`          | Cuando se envía una solicitud de firma a un destinatario                         |
| `next_signer`             | Cuando le toca el turno al siguiente firmante en un orden de firma               |
| `resend_notification`     | Cuando el remitente reenvía manualmente una invitación de firma                  |
| `reminder_default`        | Cuando se envía un recordatorio automático para una firma pendiente              |
| `signing_expired`         | Cuando una solicitud de firma expira                                             |
| `signing_cancelled`       | Cuando se cancela una solicitud de firma                                         |
| `signing_declined`        | Cuando un firmante rechaza (enviado a los demás firmantes)                       |
| `signing_declined_admin`  | Cuando un firmante rechaza (enviado al remitente, incluye el motivo del rechazo) |
| `signing_completed`       | Cuando todos los firmantes han completado la firma                               |
| `signer_identity_changed` | Cuando un firmante cambia su nombre durante la firma                             |

### Marcadores de posición disponibles

Las plantillas admiten cuerpos HTML con marcadores de posición dinámicos usando la sintaxis `{{placeholder}}`.

**Marcadores de posición del firmante:**

| Marcador de posición    | Descripción                       |
| ----------------------- | --------------------------------- |
| `{{signer_first_name}}` | Nombre del firmante               |
| `{{signer_last_name}}`  | Apellido del firmante             |
| `{{signer_name}}`       | Nombre completo del firmante      |
| `{{signer_email}}`      | Dirección de correo del firmante  |
| `{{signer_title}}`      | Cargo del firmante                |
| `{{signer_company}}`    | Nombre de la empresa del firmante |

**Marcadores de posición del documento:**

| Marcador de posición       | Descripción                                         |
| -------------------------- | --------------------------------------------------- |
| `{{signing_request_name}}` | Nombre de la solicitud de firma                     |
| `{{signing_link}}`         | URL para que el firmante firme                      |
| `{{expiration_date}}`      | Cuándo expira la solicitud de firma                 |
| `{{download_link}}`        | Enlace para descargar el documento firmado          |
| `{{decliner_name}}`        | Nombre del firmante que rechazó                     |
| `{{decline_reason}}`       | Motivo proporcionado al rechazar                    |
| `{{signing_qr_code}}`      | Imagen de código QR que enlaza a la página de firma |

**Marcadores de posición del equipo:**

| Marcador de posición | Descripción                               |
| -------------------- | ----------------------------------------- |
| `{{team_name}}`      | Nombre del espacio de trabajo/equipo      |
| `{{team_email}}`     | Correo de contacto del espacio de trabajo |
| `{{company_name}}`   | Nombre de la empresa                      |
| `{{company_logo}}`   | Imagen del logotipo de la empresa         |

También puedes recuperar esta lista mediante programación:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
  -H "Authorization: YOUR_API_KEY"
```

### Ver plantillas predeterminadas

Recupera las plantillas predeterminadas integradas de Firma para cualquier idioma admitido para usarlas como punto de partida:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
  -H "Authorization: YOUR_API_KEY"
```

Idiomas admitidos: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

### Definir una plantilla de correo a nivel de espacio de trabajo

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validación:**

* `subject`: obligatorio, máximo 500 caracteres
* `body`: obligatorio, máximo 50,000 caracteres

### Definir una plantilla de correo a nivel de empresa

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Eliminar una plantilla personalizada

Elimina una plantilla personalizada para volver al siguiente nivel de la jerarquía:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
  -H "Authorization: YOUR_API_KEY"
```

### Jerarquía de plantillas

Las plantillas de correo siguen una jerarquía en cascada:

1. **Plantilla del espacio de trabajo** (máxima prioridad)
2. **Plantilla de la empresa**
3. **Predeterminada integrada** para el idioma del espacio de trabajo (mínima prioridad)

Esto te permite definir una plantilla de marca a nivel de toda la empresa y sobrescribirla para espacios de trabajo específicos cuando sea necesario. Eliminar una plantilla en cualquier nivel hace que se recurra al siguiente nivel.

<Warning>
  Se devuelve una advertencia si el cuerpo de una plantilla no contiene el marcador de posición `{{signing_link}}`, ya que los destinatarios necesitan un enlace para acceder al flujo de firma.
</Warning>

Consulta la [Referencia de la API de plantillas de correo](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) para la documentación completa de los endpoints.

***

## Desactivar los correos de Firma

Para tener control total sobre las comunicaciones con los clientes, puedes desactivar los correos automáticos de Firma por solicitud de firma. Esto te permite:

* Enviar enlaces de solicitudes de firma a través de tu propio sistema de correo
* Integrarte con tus flujos de notificación existentes
* Personalizar el momento de envío de los correos y las secuencias de seguimiento
* Usar tu propia infraestructura de entrega de correo

### Configuración de correo en las solicitudes de firma

Cada solicitud de firma tiene configuraciones que controlan qué correos se envían:

| Configuración             | Descripción                                                          | Valor predeterminado |
| ------------------------- | -------------------------------------------------------------------- | -------------------- |
| `send_signing_email`      | Envía correos de notificación de solicitud de firma a los firmantes  | `true`               |
| `send_finish_email`       | Envía un correo de finalización cuando todos los firmantes terminan  | `true`               |
| `send_expiration_email`   | Envía una notificación de expiración cuando la solicitud expira      | `true`               |
| `send_cancellation_email` | Envía una notificación de cancelación cuando se cancela la solicitud | `true`               |

### Crear una solicitud de firma con los correos desactivados

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Obtener URLs de firma para distribución manual

Cuando los correos están desactivados, recupera las URLs de firma desde la API y envíalas a través de tus propios canales:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Experiencias incrustadas

La función de marca blanca más potente es incrustar las interfaces de Firma directamente en tu aplicación. Esto elimina toda la marca de Firma y crea una experiencia fluida dentro de tu producto.

### Firma incrustada

Incrusta el flujo de firma para que los destinatarios firmen documentos sin salir de tu aplicación:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Guía de firma incrustada](embeddable-signing) - Detalles completos de implementación

### Editor de plantillas incrustado

Permite a los usuarios crear y editar plantillas dentro de tu aplicación usando autenticación JWT:

```js theme={null}
// Generate JWT token from your backend
const token = await generateTemplateToken(templateId)

// Embed the template editor
const editorUrl = `https://app.firma.dev/template-editor?token=${token}`
```

```html theme={null}
<iframe 
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

[Guía del editor de plantillas incrustado](embeddable-template-editor) - Autenticación JWT e implementación completa

### Editor de solicitudes de firma incrustado

Ofrece una interfaz para configurar los destinatarios y las opciones de las solicitudes de firma:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing-request-editor?token={jwt_token}"
  style="width:100%;height:700px;border:0;"
  title="Configure Signing Request"
></iframe>
```

[Guía del editor de solicitudes de firma incrustado](embeddable-signing-request-editor) - Guía de implementación completa

***

## Configuración completa de marca blanca

Aquí tienes un ejemplo completo de cómo configurar un espacio de trabajo totalmente personalizado para un cliente:

### 1. Crear el espacio de trabajo

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Subir un logotipo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configurar la marca

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Ocultar la marca de Firma (a nivel de empresa)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Configurar un dominio de correo personalizado (opcional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Personalizar plantillas de correo (opcional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Incrustar las experiencias

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Prácticas recomendadas

### Marca

* Usa una paleta de colores consistente en logotipos, plantillas de correo y experiencias incrustadas
* Sube los logotipos en formato PNG con fondo transparente para obtener mejores resultados
* Habilita `show_custom_branding_only` para eliminar por completo la marca de Firma
* Define la marca a nivel de empresa como base y luego sobrescríbela por espacio de trabajo cuando sea necesario
* Prueba el flujo de firma completo desde la perspectiva de tus clientes

### Configuración de dominio de correo

* Usa un subdominio (por ejemplo, `sign.yourcompany.com`) en lugar de tu dominio principal
* Configura todos los registros DNS (SPF, DKIM, DMARC) para una entregabilidad óptima
* Monitorea las tasas de rebote de correo y ajusta según sea necesario
* Prueba la entrega de correo antes de pasar a producción con clientes

### Plantillas de correo

* Usa el [endpoint de valores predeterminados](#view-default-templates) para ver las plantillas integradas de Firma como punto de partida
* Incluye siempre `{{signing_link}}` en las plantillas de invitación y recordatorio
* Define una plantilla a nivel de empresa como base de marca y luego sobrescríbela por espacio de trabajo cuando sea necesario
* Usa `{{company_logo}}` en las plantillas para incluir el logotipo del espacio de trabajo o de la empresa

### Seguridad

* Genera siempre los tokens JWT en tu backend
* Nunca expongas claves API en código del lado del cliente
* Usa tiempos de expiración de token cortos (recomendado: 1 a 4 horas)
* Valida los orígenes de postMessage al manejar eventos de iframe

***

## Solución de problemas

### Falló la verificación de propiedad del dominio

**Posibles causas**:

* Los registros DNS no se han propagado (espera hasta 48 horas)
* Nombre o valor de registro TXT incorrecto
* Registro TXT agregado a la zona equivocada

**Solución**: Verifica que tu configuración de DNS coincida con las `verification_instructions` devueltas al agregar el dominio

### Los registros DNS no se verifican

**Posibles causas**:

* Los registros aún no se han propagado
* Valores de registro incorrectos
* Faltan registros

**Solución**: Llama a `GET /company/domains/{id}` o `verify-dns` para ver qué registros específicos están pendientes

### El iframe de firma no carga

**Posibles causas**:

* ID de usuario de solicitud de firma inválido
* Solicitud de firma expirada o cancelada
* La política de seguridad de contenido está bloqueando el iframe

**Solución**: Verifica el estado de la solicitud de firma y revisa la consola del navegador en busca de errores de CSP

### El token JWT expiró

**Posibles causas**:

* TTL del token demasiado corto para el caso de uso
* Desfase de reloj entre servidores

**Solución**: Genera tokens con una expiración adecuada y considera renovar los tokens de forma proactiva

### Los colores no se aplican

**Posibles causas**:

* Formato hexadecimal inválido (debe ser de 6 dígitos, por ejemplo, `#0066cc`, no de 3 dígitos `#06c`)
* La configuración se aplicó a nivel de empresa, pero el espacio de trabajo tiene su propia anulación

**Solución**: Revisa primero la configuración del espacio de trabajo y luego la de la empresa. Usa `null` a nivel de espacio de trabajo para eliminar una anulación.

***

## Guías relacionadas

* [Firma incrustada](embeddable-signing) - Incrusta la experiencia de firma en tu aplicación
* [Editor de plantillas incrustado](embeddable-template-editor) - Permite a los usuarios editar plantillas con autenticación JWT
* [Editor de solicitudes de firma incrustado](embeddable-signing-request-editor) - Configura solicitudes de firma en tu interfaz
* [Creación de espacios de trabajo](creating-workspaces) - Configura entornos aislados para tus clientes
* [Webhooks](webhooks) - Rastrea eventos de firma en tiempo real