Envío de una solicitud de firma

Esta guía cubre la creación de una solicitud de firma, la incorporación de una plantilla o documento, y la invitación de destinatarios a firmar.

Crear vs. crear y enviar

POST /signing-requests crea únicamente un borrador - nunca envía un correo electrónico, sin importar qué configuración pases. Para notificar a los destinatarios de inmediato, usa POST /signing-requests/create-and-send en su lugar, o llama a .../send sobre el borrador después. Esta es la causa más común de los reportes “creé una solicitud de firma pero no se envió nada”.

Firma ofrece dos formas de iniciar una solicitud de firma, y elegir la incorrecta es el error de integración más común:

	`POST /signing-requests` (crear)	`POST /signing-requests/create-and-send`
Resultado	Un borrador (`status: "draft"`). No se envía nada.	La solicitud se crea y se envía, de forma atómica, en una sola llamada.
¿Se notifica a los destinatarios?	Nunca - sin importar `send_signing_email` ni ninguna otra configuración.	Por defecto, sí. Consulta `send_signing_email` más abajo.
¿Se cobra crédito / se establece `sent_on`?	No	Sí, de inmediato.
¿Sigue siendo editable mediante PATCH/PUT?	Sí, hasta que llames a `/send`	No - la solicitud ya está en estado enviado.
Ideal para	Un flujo de borrador y luego edición: construir la solicitud, ajustar destinatarios o campos, que se revise internamente y luego enviarla cuando esté lista.	Una llamada de enviar y olvidar cuando ya tienes todo lo que necesitas.

Usa create cuando tu flujo de trabajo necesite un paso de revisión o edición antes de que algo llegue a un destinatario. Usa create-and-send cuando quieras que la solicitud quede activa y los destinatarios notificados en una sola llamada.

El indicador `send_signing_email`

Este indicador vive en settings.send_signing_email, pero significa algo distinto según el endpoint que llames:

Endpoint	Efecto de `send_signing_email: false`
`POST /signing-requests` (crear)	Ninguno. Este endpoint nunca envía un correo por sí solo, así que el indicador simplemente se almacena para más tarde - solo tiene efecto una vez que el borrador se envía realmente.
`POST /signing-requests/create-and-send`	La solicitud igual se crea y se envía: se cobra el crédito, se establece `sent_on`, se dispara el webhook `signing_request.sent`, y el enlace de firma queda activo. Solo se suprime el correo electrónico de notificación al destinatario.

send_signing_email: false en create-and-send no es un borrador silencioso - es una solicitud de firma completamente enviada y facturada, sin correo electrónico adjunto. Úsalo cuando planees entregar tú mismo el enlace de firma (incrustándolo, o enviando tu propia notificación). Si quieres algo que aún puedas cancelar o editar antes de que se vuelva definitivo, usa create (el endpoint de borrador) en su lugar.

El indicador `allow_presigning_download`

Controla si los destinatarios pueden descargar el documento sin firmar antes de completar su parte del flujo de firma. Se comporta igual en ambos endpoints:

Si lo estableces explícitamente en settings, ese valor se almacena en la solicitud de firma.
Si lo omites, se resuelve en el momento de visualización/descarga a través de una cadena de herencia: solicitud de firma → espacio de trabajo → configuración de la empresa, con un valor predeterminado de no permitido si ninguno de esos está configurado.
Al crear desde una plantilla y omitirlo, la solicitud hereda el propio valor allow_presigning_download de la plantilla.

El esquema OpenAPI público de create-and-send actualmente no incluye allow_presigning_download dentro de su objeto settings, pero el endpoint lo acepta y lo aplica de forma idéntica a POST /signing-requests.

Pasos

Crea o selecciona una plantilla
Crea una solicitud de firma que haga referencia a la plantilla
Agrega destinatarios con la información requerida (nombre, apellido, correo electrónico)
Opcionalmente, agrega campos de formulario con posicionamiento basado en porcentajes
Envía la solicitud por correo electrónico o incrusta la vista de firma

Esquema del destinatario (campos obligatorios)

Los destinatarios requieren first_name y last_name como campos separados - no existe un único campo name.

Cada destinatario debe incluir:

first_name (obligatorio) - Nombre del destinatario
last_name (opcional) - Apellido del destinatario (obligatorio solo al crear mediante POST /signing-requests con un documento sin procesar)
email (obligatorio) - Dirección de correo electrónico (create advierte sobre formato inválido; create-and-send y /send lo rechazan)
designation (obligatorio) - Rol: "Signer", "CC" o "Approver". Los aprobadores revisan y aprueban el documento (sin firma) mediante los tipos de campo approval_* que se describen más abajo
order (opcional) - Orden de firma para flujos de trabajo secuenciales

Campos opcionales:

phone_number, street_address, city, state_province, postal_code, country, title, company
custom_fields - Objeto con pares clave-valor personalizados

Crear una solicitud de firma a partir de una plantilla (API)

Endpoint: POST /signing-requests

Ejemplo de curl (crear solicitud a partir de una plantilla):

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'

Una respuesta exitosa (201) devuelve un recurso Document que incluye id (el signing_request_id) y document_url cuando corresponda.

Crear una solicitud de firma (ejemplo de servidor) - Node (fetch)

const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}

Crear una solicitud de firma (ejemplo de servidor) - Python (requests)

import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()

Crear una solicitud de firma a partir de un documento

En lugar de usar una plantilla, puedes crear una solicitud de firma subiendo directamente un documento PDF o DOCX. Elige el método según el tamaño de tu archivo:

El base64 en línea (document) funciona para archivos pequeños, pero enviar un documento grande de esta forma puede fallar con un 502 antes de que tu solicitud llegue siquiera a la validación de la aplicación - la carga útil alcanza un límite de tamaño a nivel de plataforma, no un error que puedas capturar y reintentar de forma limpia. Si un documento está cerca de los 5MB, usa el flujo de carga en dos pasos (document_id) que se describe abajo en lugar de base64 en línea, aunque implique escribir más código.

Archivos pequeños (menos de 5MB)
Archivos grandes (hasta 50MB)

Para documentos de menos de 5MB, incluye el archivo codificado en base64 directamente en el cuerpo de la solicitud:

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'

Para documentos de más de 5MB, usa el flujo de carga en dos pasos:Paso 1: Solicita una URL de carga

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'

Respuesta:

{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}

Paso 2: Sube el archivo

curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf

Paso 3: Crea la solicitud de firma

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'

La URL de carga expira después de 1 hora y solo puede usarse una vez. Cada document_id solo puede usarse en una solicitud de firma.

Debes proporcionar exactamente uno de estos: document, document_id o template_id. Son mutuamente excluyentes.

Agregar campos de formulario (posicionamiento basado en porcentajes)

Importante: Todas las coordenadas de posición de los campos (x, y, width, height) deben ser porcentajes (0-100) relativos a las dimensiones de la página, no píxeles. El campo page_number es obligatorio.

¿Quieres que un campo muestre un valor antes de que el firmante lo toque - un valor fijo que ya conoces, o los propios datos de perfil del destinatario? Consulta la guía de Prellenado de campos. variable_name por sí solo no hace esto.

Al crear una solicitud de firma directamente (POST /signing-requests) o al actualizar una, puedes agregar campos de formulario:

Ejemplo de posicionamiento de campos

{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}

Tipos de campo

signature - Campo de firma
text - Entrada de texto de una línea
date - Selector de fecha
checkbox - Casilla de verificación
dropdown - Selector desplegable (requiere dropdown_options)
initial - Campo de iniciales (también acepta initials como alias)
approval_signature - Sello de APROBADO (solo Aprobador)
approval_checkmark - Marca de aprobación (solo Aprobador)
approval_date - Fecha de aprobación (solo Aprobador)

Los tipos de campo approval_* solo pueden asignarse a un destinatario cuya designation sea "Approver" (asignar uno a un Firmante devuelve un 400). Su valor se genera del lado del servidor cuando el aprobador completa su revisión, por lo que no necesitas enviar un valor para ellos, y el sello de aprobación se representa en el certificado de finalización.

Guías de posicionamiento

El sistema de coordenadas usa porcentajes para escalado responsivo:

x: 0 (borde izquierdo) a 100 (borde derecho)
y: 0 (borde superior) a 100 (borde inferior)
width: porcentaje del ancho de la página (por ejemplo, 30 = 30% de ancho)
height: porcentaje del alto de la página (por ejemplo, 8 = 8% de alto)

Para una página de tamaño carta de EE. UU. (8.5” × 11”), usa estas conversiones aproximadas:

1 pulgada ≈ 11.76% de ancho
1 pulgada ≈ 9.09% de alto

Actualización de solicitudes de firma

Antes de que se envíe una solicitud de firma, puedes actualizar sus detalles mediante la API. La API ofrece dos métodos:

No se puede actualizar después de enviar: Una vez que se envía una solicitud de firma, no se puede modificar. Las actualizaciones solo funcionan para solicitudes con estado not_sent.

Actualización integral (PUT)

Usa comprehensive-update-signing-request para actualizaciones complejas que involucren varias secciones. Cuándo usarlo:

Actualizar varios destinatarios a la vez
Eliminar destinatarios (con reasignación/eliminación de campos)
Actualizar campos y recordatorios juntos
Realizar cambios coordinados en varias secciones

Estructura: Todas las secciones son opcionales, pero se debe proporcionar al menos una:

signing_request_properties - Actualiza el nombre, la descripción, el documento, la expiración y la configuración
recipients - Inserta o actualiza destinatarios (incluye id para actualizar, omítelo para crear)
deleted_recipients - Elimina destinatarios con field_action (eliminar o reasignar campos)
fields - Inserta o actualiza campos (incluye id para actualizar, omítelo para crear)
reminders - Inserta o actualiza recordatorios (incluye id para actualizar, omítelo para crear)

Requisitos:

✅ Puede actualizar varias secciones en una sola solicitud
✅ Admite la eliminación de destinatarios con manejo de campos
✅ Solo funciona antes de que se envíe la solicitud

Ejemplo (Node.js):

const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    fields: [
      {
        id: 'field1-e89b-12d3-a456-426614174000',
        type: 'signature',
        position: { x: 15, y: 85, width: 30, height: 10 },
        page_number: 1,
        required: true,
        recipient_id: 'rec1-e89b-12d3-a456-426614174000'
      }
    ]
  })
});

const updatedRequest = await response.json();

Actualización parcial (PATCH)

Usa partially-update-signing-request cuando actualices propiedades específicas o un solo destinatario. Cuándo usarlo:

Actualizar el nombre, la descripción o la configuración
Agregar o actualizar un destinatario a la vez
Realizar cambios puntuales sin afectar otros datos

Importante: No se pueden actualizar propiedades Y un destinatario en la misma solicitud. Elige una opción:

Actualizar solo propiedades (name, description, document, expiration_hours, settings)
O actualizar/crear un solo destinatario

Beneficios:

✅ Envía solo los campos que quieres cambiar
✅ Más eficiente para cambios pequeños
✅ Los demás campos permanecen sin cambios
✅ Más seguro para ediciones concurrentes

Ejemplo (Node.js):

// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();

Ejemplo (Python):

import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()

Cómo elegir entre PUT y PATCH

Escenario	Usar	Motivo
Reconstrucción completa de la solicitud de firma	PUT	Reemplazo completo con todas las secciones (propiedades, destinatarios, campos, recordatorios)
Actualizar solo el nombre o la configuración	PATCH	Más eficiente, conserva destinatarios y campos
Agregar/actualizar un destinatario	PATCH	Modo de destinatario único, los demás destinatarios no se modifican
Actualizar varios destinatarios	PUT	Puede insertar o actualizar varios destinatarios en una sola solicitud
Eliminar destinatarios con reasignación de campos	PUT	Admite deleted_recipients con field_action
Cambiar el documento y todos los campos	PUT	Cambios estructurales importantes
Actualizar campos personalizados	PATCH	Conserva la solicitud de firma principal
Reemplazar todos los destinatarios	PUT	Enfoque de tabla rasa

Importante: Ambos métodos de actualización solo funcionan antes de que se envíe la solicitud de firma. Una vez enviada, la solicitud de firma se vuelve inmutable para evitar manipulaciones en flujos de trabajo de firma activos.

Prácticas recomendadas:

Actualiza las solicitudes de firma antes de llamar a /send
Valida los datos del destinatario antes de actualizar
Usa PATCH para cambios incrementales
Implementa lógica de reintento con retroceso exponencial

Envío (invitaciones por correo electrónico)

Una vez que tengas un ID de solicitud de firma (y hayas hecho las actualizaciones necesarias), llama a POST /signing-requests/{signing_request_id}/send para enviar correos electrónicos a todos los destinatarios.

Ejemplo

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'

El endpoint /send valida que todos los destinatarios tengan la información requerida (first_name y email - last_name es opcional) y que los campos prellenados tengan los datos correspondientes del destinatario.

Incrustación de la vista de firma

Para incrustar la experiencia de firma en tu propia aplicación, obtén el id del destinatario desde GET /signing-requests/{id}/users y construye la URL de firma:

https://app.firma.dev/signing/{recipient_id}

Renderiza esta URL en un iframe. Para conocer la configuración completa de incrustación - incluidos los eventos postMessage, el dimensionamiento del iframe y los permisos de cámara/portapapeles - consulta la guía de Firma incrustable.

Casos particulares y consejos

Orden de firma: Asegúrate de que los destinatarios tengan valores de order secuenciales (1, 2, 3…) para flujos de trabajo de firma secuenciales
Registro de auditoría: Descarga el registro de auditoría mediante GET /signing-requests/{id}/tracking para ver todas las acciones de los usuarios
Descargar el PDF completado: Usa GET /signing-requests/{id}/download después de la finalización
Webhooks: Suscríbete a eventos como signing_request.completed en lugar de hacer polling (consulta la guía de Webhooks)

Próximos pasos

Prellena campos con datos del destinatario o datos estáticos antes de enviar
Configura webhooks para recibir notificaciones de eventos en tiempo real (60 req/min)
Agrega recordatorios automáticos para los destinatarios pendientes
Incrusta el editor de plantillas con autenticación JWT (120 req/min)
Configura los ajustes del espacio de trabajo para plantillas de correo electrónico personalizadas (100-200 req/min)
Editor de plantillas incrustable con autenticación JWT para flujos de trabajo incrustados seguros

Para flujos de trabajo de firma secuencial con varios firmantes, asegúrate de que cada destinatario tenga un valor de order secuencial (1, 2, 3…).
Para auditoría y cumplimiento, descarga el PDF final mediante GET /signing-requests/signing_request_id/download después de la finalización.
Usa webhooks (consulta la Guía de Webhooks) para reaccionar a los eventos de firma en lugar de hacer polling.

Guías de Inicio

Guías avanzadas

Envío de una solicitud de firma

Envío de una solicitud de firma

Crear vs. crear y enviar

El indicador `send_signing_email`

El indicador `allow_presigning_download`

Pasos

Esquema del destinatario (campos obligatorios)

Crear una solicitud de firma a partir de una plantilla (API)

Crear una solicitud de firma (ejemplo de servidor) - Node (fetch)

Crear una solicitud de firma (ejemplo de servidor) - Python (requests)

Crear una solicitud de firma a partir de un documento

Agregar campos de formulario (posicionamiento basado en porcentajes)

Ejemplo de posicionamiento de campos

Tipos de campo

Guías de posicionamiento

Actualización de solicitudes de firma

Actualización integral (PUT)

Actualización parcial (PATCH)

Cómo elegir entre PUT y PATCH

Envío (invitaciones por correo electrónico)

Ejemplo

Incrustación de la vista de firma

Casos particulares y consejos

Próximos pasos

​Envío de una solicitud de firma

​Crear vs. crear y enviar

​El indicador send_signing_email

​El indicador allow_presigning_download

​Pasos

​Esquema del destinatario (campos obligatorios)

​Crear una solicitud de firma a partir de una plantilla (API)

​Crear una solicitud de firma (ejemplo de servidor) - Node (fetch)

​Crear una solicitud de firma (ejemplo de servidor) - Python (requests)

​Crear una solicitud de firma a partir de un documento

​Agregar campos de formulario (posicionamiento basado en porcentajes)

​Ejemplo de posicionamiento de campos

​Tipos de campo

​Guías de posicionamiento

​Actualización de solicitudes de firma

​Actualización integral (PUT)

​Actualización parcial (PATCH)

​Cómo elegir entre PUT y PATCH

​Envío (invitaciones por correo electrónico)

​Ejemplo

​Incrustación de la vista de firma

​Casos particulares y consejos

​Próximos pasos

Envío de una solicitud de firma

Crear vs. crear y enviar

El indicador `send_signing_email`

El indicador `allow_presigning_download`

Pasos

Esquema del destinatario (campos obligatorios)

Crear una solicitud de firma a partir de una plantilla (API)

Crear una solicitud de firma (ejemplo de servidor) - Node (fetch)

Crear una solicitud de firma (ejemplo de servidor) - Python (requests)

Crear una solicitud de firma a partir de un documento

Agregar campos de formulario (posicionamiento basado en porcentajes)

Ejemplo de posicionamiento de campos

Tipos de campo

Guías de posicionamiento

Actualización de solicitudes de firma

Actualización integral (PUT)

Actualización parcial (PATCH)

Cómo elegir entre PUT y PATCH

Envío (invitaciones por correo electrónico)

Ejemplo

Incrustación de la vista de firma

Casos particulares y consejos

Próximos pasos