Marca Blanca

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:

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

Todos los ejemplos de la API usan tu clave API directamente en el encabezado Authorization. No uses el prefijo Bearer.

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.

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:

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:

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

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:

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

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:

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:

Configuración del espacio de trabajo (máxima prioridad)
Configuración de la empresa
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 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:

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

Definir términos a nivel de empresa

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

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:

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

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

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

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:

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

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.

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:

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

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

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

Paso 3: Verifica la propiedad del dominio

Una vez agregado el registro TXT, verifica la propiedad:

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

Respuesta:

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

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

Respuesta:

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

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

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

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

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

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

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

Configuración email_local_part del espacio de trabajo
Configuración email_local_part de la empresa
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):

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

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:

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:

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

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

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:

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:

Plantilla del espacio de trabajo (máxima prioridad)
Plantilla de la empresa
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.

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.

Consulta la Referencia de la API de plantillas de correo 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

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:

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

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

// 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}`

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

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

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

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

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)

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)

// 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)

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

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 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 - Incrusta la experiencia de firma en tu aplicación
Editor de plantillas incrustado - Permite a los usuarios editar plantillas con autenticación JWT
Editor de solicitudes de firma incrustado - Configura solicitudes de firma en tu interfaz
Creación de espacios de trabajo - Configura entornos aislados para tus clientes
Webhooks - Rastrea eventos de firma en tiempo real

Espacios de Trabajo Localización

⌘I

​Descripción general

​Marca personalizada

​Logotipo de la empresa

​Logotipo del espacio de trabajo

​Temas de color

​Ocultar la marca de Firma

​Configuraciones de visualización adicionales

​Jerarquía de configuración

​Términos personalizados para firmantes

​Cómo funciona

​Definir términos a nivel de empresa

​Definir términos a nivel de espacio de trabajo

​Listar términos

​Eliminar términos

​Desactivar la aceptación de términos

​Etiquetas personalizadas de los botones de firma

​Definir anulaciones de etiquetas de botones

​Eliminar anulaciones de etiquetas de botones

​Dominios de correo personalizados

​Dominios de correo a nivel de cuenta (empresa)

​Paso 1: Agrega tu dominio

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

​Paso 3: Verifica la propiedad del dominio

​Paso 4: Finaliza la configuración del dominio

​Paso 5: Agrega los registros DNS

​Paso 6: Verifica los registros DNS

​Paso 7: Definir como dominio principal (opcional)

​Dominios de correo a nivel de espacio de trabajo

​Dirección de remitente de correo personalizada

​Cómo se resuelven las direcciones de correo

​Configurar la parte local del correo

​Plantillas de correo personalizadas

​Tipos de correo personalizables

​Marcadores de posición disponibles

​Ver plantillas predeterminadas

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

​Definir una plantilla de correo a nivel de empresa

​Eliminar una plantilla personalizada

​Jerarquía de plantillas

​Desactivar los correos de Firma

​Configuración de correo en las solicitudes de firma

​Crear una solicitud de firma con los correos desactivados

​Obtener URLs de firma para distribución manual

​Experiencias incrustadas

​Firma incrustada

​Editor de plantillas incrustado

​Editor de solicitudes de firma incrustado

​Configuración completa de marca blanca

​1. Crear el espacio de trabajo

​2. Subir un logotipo

​3. Configurar la marca

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

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

​6. Personalizar plantillas de correo (opcional)

​7. Incrustar las experiencias

​Prácticas recomendadas

​Marca

​Configuración de dominio de correo

​Plantillas de correo

​Seguridad

​Solución de problemas

​Falló la verificación de propiedad del dominio

​Los registros DNS no se verifican

​El iframe de firma no carga

​El token JWT expiró

​Los colores no se aplican

​Guías relacionadas

Descripción general

Marca personalizada

Logotipo de la empresa

Logotipo del espacio de trabajo

Temas de color

Ocultar la marca de Firma

Configuraciones de visualización adicionales

Jerarquía de configuración

Términos personalizados para firmantes

Cómo funciona

Definir términos a nivel de empresa

Definir términos a nivel de espacio de trabajo

Listar términos

Eliminar términos

Desactivar la aceptación de términos

Etiquetas personalizadas de los botones de firma

Definir anulaciones de etiquetas de botones

Eliminar anulaciones de etiquetas de botones

Dominios de correo personalizados

Dominios de correo a nivel de cuenta (empresa)

Paso 1: Agrega tu dominio

Paso 2: Agrega el registro TXT de verificación

Paso 3: Verifica la propiedad del dominio

Paso 4: Finaliza la configuración del dominio

Paso 5: Agrega los registros DNS

Paso 6: Verifica los registros DNS

Paso 7: Definir como dominio principal (opcional)

Dominios de correo a nivel de espacio de trabajo

Dirección de remitente de correo personalizada

Cómo se resuelven las direcciones de correo

Configurar la parte local del correo

Plantillas de correo personalizadas

Tipos de correo personalizables

Marcadores de posición disponibles

Ver plantillas predeterminadas

Definir una plantilla de correo a nivel de espacio de trabajo

Definir una plantilla de correo a nivel de empresa

Eliminar una plantilla personalizada

Jerarquía de plantillas

Desactivar los correos de Firma

Configuración de correo en las solicitudes de firma

Crear una solicitud de firma con los correos desactivados

Obtener URLs de firma para distribución manual

Experiencias incrustadas

Firma incrustada

Editor de plantillas incrustado

Editor de solicitudes de firma incrustado

Configuración completa de marca blanca

1. Crear el espacio de trabajo

2. Subir un logotipo

3. Configurar la marca

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

5. Configurar un dominio de correo personalizado (opcional)

6. Personalizar plantillas de correo (opcional)

7. Incrustar las experiencias

Prácticas recomendadas

Marca

Configuración de dominio de correo

Plantillas de correo

Seguridad

Solución de problemas

Falló la verificación de propiedad del dominio

Los registros DNS no se verifican

El iframe de firma no carga

El token JWT expiró

Los colores no se aplican

Guías relacionadas