> ## 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.
# Crear y Enviar Solicitud de Firma (Atómico)
> Crea y envía inmediatamente una solicitud de firma en una única operación atómica. Este endpoint combina la funcionalidad de POST /signing-requests y POST /signing-requests/{id}/send.
**Beneficios Clave:**
- Una sola llamada a la API en lugar de dos solicitudes separadas
- Valida todos los requisitos de envío ANTES de crear la solicitud de firma
- Deducción de créditos atómica: solo cobra si todo tiene éxito
- Devuelve status: 'sent' inmediatamente con los detalles del primer firmante
- Más eficiente (ahorra 1 llamada a la API + tiempo de ida y vuelta)
**Validación:**
- Todas las validaciones de creación estándar (document/template, recipients, fields)
- Validaciones de envío adicionales:
- Todos los firmantes deben tener first_name y un email válido
- Los campos de solo lectura requeridos deben tener final_value completado
- Los campos de datos prellenados (variable_name) deben tener los datos de usuario correspondientes
- La empresa debe tener créditos suficientes (≥1)
**Atomicidad:**
- Si alguna validación falla, no se crea nada
- El crédito solo se deduce después de una creación exitosa y antes del envío del email
- Si el envío del email falla después de la creación, la solicitud de firma permanece en estado 'draft' y el crédito NO se deduce
**Patrón de ID Temporal:** Para la creación basada en documento, usa IDs temporales (formato: 'temp_X') para referenciar destinatarios antes de la creación. La API valida todas las referencias y mapea automáticamente los IDs temporales a UUID reales.
**Límite de Tasa:** 120 solicitudes/minuto (igual que las operaciones de escritura)
## OpenAPI
````yaml api-reference/v01.30.00/openapi-v01.30.00.es.json post /signing-requests/create-and-send
openapi: 3.0.3
info:
title: API de Socios de Firma
description: >-
API RESTful para firma de documentos y gestión de plantillas.
**Autenticación**: Todos los endpoints requieren autenticación mediante
clave API a través del encabezado `Authorization`. Usa tu clave API
directamente sin ningún prefijo (por ejemplo, `your-api-key`). El prefijo
Bearer es opcional pero no obligatorio.
**Características de Seguridad**:
- Validación de entrada usando esquemas Zod con mensajes de error detallados
a nivel de campo
- Tokens JWT firmados con RSA-256 para el acceso al Editor de Plantillas
incrustado
**Límite de Solicitudes**: Los límites de solicitudes están escalonados
según el tipo de operación:
- Operaciones de lectura (GET): 200 solicitudes por minuto
- Operaciones de escritura (POST/PUT/PATCH/DELETE): 120 solicitudes por
minuto
- Operaciones CRUD de webhooks: 60 solicitudes por minuto
- Prueba de webhook: 10 solicitudes por minuto
- Regeneración/expiración de clave API: 1 solicitud por minuto
- Rotación de secreto de webhook: 1 solicitud por minuto
Cuando se superan los límites de solicitudes, la API devuelve una respuesta
`429 Too Many Requests` con los encabezados:
- `X-RateLimit-Limit`: Máximo de solicitudes por minuto para este endpoint
- `X-RateLimit-Remaining`: Solicitudes restantes en la ventana actual
- `X-RateLimit-Reset`: Marca de tiempo Unix de cuándo se restablece el
límite
- `Retry-After`: Segundos hasta que se permita reintentar
**Manejo de Errores**: Todos los errores devuelven respuestas JSON
estructuradas con `error` (mensaje legible para humanos), `code`
(identificador legible por máquina) y `details` (errores de validación a
nivel de campo cuando corresponda).
**Integración del Editor de Plantillas Incrustado**: El Editor de Plantillas
de Firma se puede incrustar en tu aplicación usando una biblioteca
JavaScript independiente.
```html
```
version: 01.30.00
contact:
name: API Support
url: https://firma.com/support
servers:
- url: https://api.firma.dev/functions/v1/signing-request-api
description: API de Producción - Recomendada (Actual)
- url: https://api.firma.dev/api/v1
description: API de Producción - Planeada
security:
- ApiKeyAuth: []
tags:
- name: Company
description: Información y configuración de la empresa
- name: Workspaces
description: Operaciones de gestión de espacios de trabajo
- name: Templates
description: Operaciones de gestión de plantillas
- name: Signing Requests
description: Operaciones de solicitudes de firma de documentos
- name: Custom Fields
description: >-
Gestión de definiciones de campos personalizados para espacios de trabajo,
plantillas y solicitudes de firma
- name: Webhooks
description: Configuración y gestión de webhooks
- name: JWT Management
description: Generación y revocación de tokens JWT para plantillas incrustadas
- name: Workspace Settings
description: Configuración y ajustes del espacio de trabajo
- name: Email Domains
description: >-
Configuración y verificación de dominios de correo electrónico para enviar
correos de solicitudes de firma desde dominios personalizados
- name: Email Templates
description: >-
Gestión de plantillas de correo electrónico para personalización de
notificaciones de solicitudes de firma a nivel de espacio de trabajo y de
empresa
- name: Signer Terms
description: >-
Términos de servicio / declaraciones de consentimiento personalizadas del
firmante, a nivel de empresa con anulaciones por espacio de trabajo según
el idioma
paths:
/signing-requests/create-and-send:
post:
tags:
- Signing Requests
summary: Crear y Enviar Solicitud de Firma (Atómico)
description: >-
Crea y envía inmediatamente una solicitud de firma en una única
operación atómica. Este endpoint combina la funcionalidad de POST
/signing-requests y POST /signing-requests/{id}/send.
**Beneficios Clave:**
- Una sola llamada a la API en lugar de dos solicitudes separadas
- Valida todos los requisitos de envío ANTES de crear la solicitud de
firma
- Deducción de créditos atómica: solo cobra si todo tiene éxito
- Devuelve status: 'sent' inmediatamente con los detalles del primer
firmante
- Más eficiente (ahorra 1 llamada a la API + tiempo de ida y vuelta)
**Validación:**
- Todas las validaciones de creación estándar (document/template,
recipients, fields)
- Validaciones de envío adicionales:
- Todos los firmantes deben tener first_name y un email válido
- Los campos de solo lectura requeridos deben tener final_value completado
- Los campos de datos prellenados (variable_name) deben tener los datos de usuario correspondientes
- La empresa debe tener créditos suficientes (≥1)
**Atomicidad:**
- Si alguna validación falla, no se crea nada
- El crédito solo se deduce después de una creación exitosa y antes del
envío del email
- Si el envío del email falla después de la creación, la solicitud de
firma permanece en estado 'draft' y el crédito NO se deduce
**Patrón de ID Temporal:** Para la creación basada en documento, usa IDs
temporales (formato: 'temp_X') para referenciar destinatarios antes de
la creación. La API valida todas las referencias y mapea automáticamente
los IDs temporales a UUID reales.
**Límite de Tasa:** 120 solicitudes/minuto (igual que las operaciones de
escritura)
operationId: createAndSendSigningRequest
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
maxLength: 255
description: Nombre de la solicitud de firma
example: Employment Contract - John Doe
description:
type: string
description: Descripción de la solicitud de firma
example: Full-time employment contract for Software Engineer position
document:
type: string
format: byte
description: >-
Documento PDF o DOCX codificado en base64 (mutuamente
excluyente con template_id y document_id). Los archivos DOCX
se convierten automáticamente a PDF. Tamaño máximo: 50MB.
example: >-
JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c...
template_id:
type: string
format: uuid
description: >-
ID de la plantilla a usar (mutuamente excluyente con
document y document_id)
example: 123e4567-e89b-12d3-a456-426614174000
expiration_hours:
type: integer
minimum: 1
default: 168
description: >-
Horas hasta que expira la solicitud de firma (por defecto:
168 = 7 días)
example: 168
recipients:
type: array
description: >-
Array de destinatarios. Al menos uno debe ser un Firmante.
Para creación basada en documento: obligatorio. Para
creación basada en plantilla: opcional (usa los
destinatarios de la plantilla si se omite). Usa
template_user_id (preferido) u order (alternativa) para
hacer coincidir con los usuarios de la plantilla.
minItems: 1
items:
$ref: '#/components/schemas/Recipient'
fields:
type: array
description: >-
Array de campos a completar (solo para creación basada en
documento)
items:
type: object
required:
- type
- page
- x
- 'y'
properties:
recipient_id:
type: string
description: >-
ID temporal o UUID del destinatario asignado a este
campo
example: temp_signer_1
type:
type: string
enum:
- signature
- initial
- text
- date
- checkbox
- dropdown
- radio_buttons
- text_area
- url
- file
- stamp
- approval_signature
- approval_checkmark
- approval_date
description: >-
Tipo de campo. Acepta alias: "initials" (normalizado a
"initial"), "textarea" (normalizado a "text_area"),
"radio" (normalizado a "radio_buttons").
example: signature
page:
type: integer
minimum: 1
description: Número de página del PDF (indexado desde 1)
example: 1
x:
type: number
description: Coordenada X en la página
example: 100
'y':
type: number
description: Coordenada Y en la página
example: 200
width:
type: number
default: 200
example: 200
height:
type: number
default: 50
example: 50
variable_name:
type: string
description: >-
Nombre de variable para datos precargados (por
ejemplo, 'phone_number', 'company'). Si se establece,
el campo correspondiente del destinatario debe estar
completado.
enum:
- first_name
- last_name
- full_name
- email
- phone_number
- street_address
- city
- state_province
- postal_code
- country
- title
- company
example: phone_number
variable_defined_name:
type: string
maxLength: 100
nullable: true
description: >-
Nombre legible del campo personalizado. Se puede usar
como alternativa a variable_name para apuntar a campos
en la creación basada en plantilla.
required:
type: boolean
default: false
description: Si el campo es obligatorio
read_only:
type: boolean
default: false
description: Si el campo es de solo lectura (precargado)
final_value:
type: string
description: >-
Valor precargado para campos de solo lectura
(obligatorio si read_only=true y required=true)
example: Software Engineer
background_color:
type: string
nullable: true
pattern: ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$
description: Color de fondo en hexadecimal (por ejemplo, '#FFFDE7')
example: '#FFFDE7'
dropdown_options:
description: >-
Opciones para campos desplegables. Obligatorio cuando
type es "dropdown".
example:
- Option A
- Option B
- Option C
oneOf:
- type: array
items:
type: string
- type: object
anchor_tags:
type: array
maxItems: 100
items:
$ref: '#/components/schemas/AnchorTag'
description: >-
Etiquetas de anclaje para la colocación automática de
campos. Se localizan marcadores de texto en el PDF y se
convierten en campos posicionados. El texto de anclaje se
elimina del PDF después del procesamiento. Los campos
creados a partir de etiquetas de anclaje se agregan junto a
cualquier campo especificado manualmente. Solo disponible
para creación basada en documento (no para creación basada
en plantilla).
reminders:
type: array
description: Array de configuraciones de recordatorios
items:
type: object
required:
- hours_before_expiration
properties:
hours_before_expiration:
type: integer
minimum: 1
description: >-
Horas antes de la expiración para enviar el
recordatorio
example: 24
settings:
type: object
description: Configuración de la solicitud de firma
properties:
use_signing_order:
type: boolean
default: true
description: >-
Aplica el orden de firma según recipient.order. Cuando
es false, todos los firmantes reciben el documento
simultáneamente.
allow_download:
type: boolean
default: true
description: Permite a los destinatarios descargar el documento
attach_pdf_on_finish:
type: boolean
default: true
description: Adjunta el PDF completado al correo de finalización
send_signing_email:
type: boolean
default: true
description: Envía notificación por correo a los firmantes
send_finish_email:
type: boolean
default: true
description: Envía un correo cuando se completan todas las firmas
send_expiration_email:
type: boolean
default: true
description: Envía un correo cuando expira la solicitud
send_cancellation_email:
type: boolean
default: true
description: Envía un correo cuando se cancela la solicitud
hand_drawn_only:
type: boolean
default: false
description: >-
Exige a los firmantes dibujar su firma a mano en lugar
de usar firmas escritas
identity_editable_fields:
type: array
nullable: true
items:
type: string
enum:
- name
- company
- title
- phone
- address
description: >-
Campos de identidad que los firmantes pueden editar
antes de firmar. null = deshabilitado. Cuando se
configura, aparece un diálogo de confirmación que
permite a los firmantes editar los campos especificados.
example:
- name
- company
notify_identity_change_webhook:
type: boolean
default: false
description: >-
Envía un evento de webhook cuando un firmante cambia su
identidad
notify_identity_change_email:
type: boolean
default: false
description: >-
Envía notificación por correo cuando un firmante cambia
su identidad
document_id:
type: string
format: uuid
description: >-
ID de un documento subido previamente (mutuamente excluyente
con document y template_id). Se obtiene llamando primero a
POST /documents.
example: 123e4567-e89b-12d3-a456-426614174000
oneOf:
- required:
- document
- required:
- template_id
examples:
document-based:
summary: Crear y enviar con documento
value:
name: Employment Contract - John Doe
description: Contrato de empleo a tiempo completo
document: JVBERi0xLjQKJeLjz9MK...
expiration_hours: 168
recipients:
- id: temp_signer_1
first_name: John
last_name: Doe
email: john.doe@example.com
designation: Signer
order: 1
phone_number: +1-555-0123
company: Acme Corp
title: Ingeniero de Software
fields:
- recipient_id: temp_signer_1
type: signature
page: 1
x: 100
'y': 500
width: 200
height: 50
- recipient_id: temp_signer_1
type: text
page: 1
x: 100
'y': 400
width: 150
height: 30
variable_name: phone_number
required: true
read_only: true
settings:
use_signing_order: true
send_signing_email: true
template-based:
summary: Crear y enviar desde plantilla
value:
name: NDA - Jane Smith
template_id: 123e4567-e89b-12d3-a456-426614174000
recipients:
- first_name: Jane
last_name: Smith
email: jane.smith@example.com
designation: Signer
order: 1
company: Tech Startup Inc
expiration_hours: 72
responses:
'201':
description: Solicitud de Firma creada y enviada correctamente
headers:
X-RateLimit-Limit:
schema:
type: integer
description: 'Límite de tasa: 120 solicitudes por minuto'
X-RateLimit-Remaining:
schema:
type: integer
X-RateLimit-Reset:
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAndSendResponse'
example:
id: 550e8400-e29b-41d4-a716-446655440000
name: Employment Contract - John Doe
description: Contrato de empleo a tiempo completo
status: sent
document_url: https://storage.supabase.co/...
page_count: 3
expiration_hours: 168
settings:
use_signing_order: true
allow_download: true
attach_pdf_on_finish: true
send_signing_email: true
send_finish_email: true
send_expiration_email: true
send_cancellation_email: true
hand_drawn_only: false
created_date: '2026-01-12T10:30:00Z'
sent_date: '2026-01-12T10:30:00Z'
template_id: null
first_signer:
id: rec456-e89b-12d3-a456-426614174000
name: John Doe
email: john.doe@example.com
signing_link: >-
https://app.firma.dev/signing/rec456-e89b-12d3-a456-426614174000
recipients:
- id: rec456-e89b-12d3-a456-426614174000
first_name: John
last_name: Doe
name: John Doe
email: john.doe@example.com
designation: Signer
order: 1
fields:
- id: field123-e89b-12d3-a456-426614174000
type: signature
page: 1
x: 100
'y': 500
width: 200
height: 50
required: true
recipient_id: rec456-e89b-12d3-a456-426614174000
credits_remaining: 99
'400':
description: >-
Error de validación: entrada inválida o faltan datos obligatorios
del firmante
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAndSendValidationError'
examples:
missing-recipient-data:
value:
error: >-
One or more signers are missing required information for
sending
phase: send_validation
validation_errors:
- recipient_index: 1
recipient_email: john@example.com
missing_fields:
- phone_number
- company
invalid-document:
value:
error: Document must be valid base64-encoded PDF
phase: create_validation
'401':
$ref: '#/components/responses/UnauthorizedError'
'402':
description: Créditos insuficientes
content:
application/json:
schema:
$ref: '#/components/schemas/InsufficientCreditsError'
'404':
description: Plantilla no encontrada o no pertenece al espacio de trabajo
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: >-
La dirección de correo del destinatario está suprimida (rebotó
anteriormente o fue marcada como spam) y no se le puede enviar
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
'429':
$ref: '#/components/responses/RateLimitError'
'500':
description: >-
Error inesperado del servidor. Cualquier Solicitud de Firma creada
parcialmente se revierte, por lo que no queda ningún borrador. Los
errores del paso de envío accionables por el cliente devuelven 400,
402 o 422 en su lugar.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: TypeScript
label: '@firma-dev/sdk'
source: >-
import { FirmaClient } from "@firma-dev/sdk";
const firma = new FirmaClient({ apiKey: "YOUR_API_KEY" });
const response = await
firma.signingRequests.createAndSendSigningRequest({
"name": "Employment Contract - John Doe",
"description": "Full-time employment contract",
"document": "JVBERi0xLjQKJeLjz9MK...",
"expiration_hours": 168,
"recipients": [
{
"id": "temp_signer_1",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"designation": "Signer",
"order": 1,
"phone_number": "+1-555-0123",
"company": "Acme Corp",
"title": "Software Engineer"
}
],
"fields": [
{
"recipient_id": "temp_signer_1",
"type": "signature",
"page": 1,
"x": 100,
"y": 500,
"width": 200,
"height": 50
},
{
"recipient_id": "temp_signer_1",
"type": "text",
"page": 1,
"x": 100,
"y": 400,
"width": 150,
"height": 30,
"variable_name": "phone_number",
"required": true,
"read_only": true
}
],
"settings": {
"use_signing_order": true,
"send_signing_email": true
}
});
console.log(response);
components:
schemas:
Recipient:
type: object
required:
- first_name
- email
- designation
description: >-
Esquema de Destinatario con comportamientos de auto-construcción y
mapeo. **Campo Name**: Se construye automáticamente a partir de
first_name y last_name ('First Last' si ambos están presentes, de lo
contrario 'First'). Los valores de name ingresados manualmente se
sobrescriben. **Asignación de order**: TODOS los destinatarios DEBEN
tener un valor de order explícito. Order determina la secuencia de
firma, que siempre se aplica. Los destinatarios deben firmar en orden,
firmando primero los números más bajos. **Campos personalizados**:
Admite tanto la estructura plana (por ejemplo, company_name en la raíz)
como la estructura anidada (objeto custom_fields). Ambos formatos se
normalizan internamente. **Mapeo de campos de plantilla**: Al crear a
partir de una plantilla con destinatarios personalizados, use
template_user_id u order para hacer coincidir a los usuarios de la
plantilla. Solo se puede actualizar la información del usuario (name,
email, phone, etc.); order y designation se heredan de la plantilla.
**IDs temporales**: Para la creación basada en documentos, use IDs
temporales (formato: 'temp_1', 'temp_2', etc.) para hacer referencia a
los destinatarios en fields y reminders antes de que se creen.
**Destinatarios CC**: Los destinatarios en CC reciben una copia
completada pero no pueden firmar ni tener campos asignados. Se requiere
al menos un Firmante.
properties:
id:
type: string
description: >-
Identificador único. Para actualizaciones: use el UUID existente.
Para la creación basada en documentos: opcionalmente use un ID
temporal (formato: 'temp_1', 'temp_2', etc.) para hacer referencia a
los destinatarios en fields y reminders antes de la creación. Los
IDs temporales se resuelven automáticamente a UUIDs reales en la
respuesta.
_temp_id:
type: string
description: >-
Identificador temporal para destinatarios nuevos en solicitudes PUT
(actualización integral) (por ejemplo, 'temp_1'). Úselo al crear
destinatarios nuevos junto con destinatarios existentes en
actualizaciones integrales. Debe comenzar con 'temp_' y ser único
dentro de la solicitud. No se usa para solicitudes POST (creación);
use el campo 'id' en su lugar.
template_user_id:
type: string
format: uuid
description: >-
Al crear desde una plantilla, el ID del usuario de plantilla a
actualizar. Si se proporciona, los datos de este destinatario
actualizarán al usuario de plantilla correspondiente. Si no se
proporciona, se recurre a la coincidencia por orden. Solo se puede
actualizar la información del usuario (nombre, email, teléfono,
dirección, cargo, empresa) - el orden y la designación siempre se
heredan de la plantilla.
first_name:
type: string
maxLength: 100
description: Nombre del destinatario
last_name:
type: string
maxLength: 100
description: >-
Apellido del destinatario (opcional, pero requerido si se usan las
variables prellenadas full_name o last_name)
email:
type: string
format: email
maxLength: 255
description: Dirección de email del destinatario
designation:
type: string
enum:
- Signer
- Approver
- CC
description: >-
Rol del destinatario. Signer firma el documento, Approver aprueba
con campos de aprobación, CC recibe una copia al completarse.
order:
type: integer
minimum: 1
description: >-
Número de secuencia de firma. Los destinatarios deben firmar en
orden, firmando primero los números más bajos. Este campo es
obligatorio para todos los destinatarios.
phone_number:
type: string
maxLength: 50
nullable: true
description: Número de teléfono del destinatario
street_address:
type: string
maxLength: 255
nullable: true
description: Dirección postal
city:
type: string
maxLength: 100
nullable: true
description: Ciudad
state_province:
type: string
maxLength: 100
nullable: true
description: Estado o provincia
postal_code:
type: string
maxLength: 20
nullable: true
description: Código postal
country:
type: string
maxLength: 100
nullable: true
description: País
title:
type: string
maxLength: 100
nullable: true
description: Cargo
company:
type: string
maxLength: 255
nullable: true
description: Nombre de la empresa
custom_fields:
type: object
additionalProperties: true
description: >-
Pares clave-valor personalizados para datos adicionales del
destinatario
AnchorTag:
type: object
required:
- anchor_string
- type
- recipient_id
description: >-
Definición de etiqueta de anclaje para la colocación automática de
campos. Las etiquetas de anclaje son marcadores de texto incrustados en
un documento PDF (por ejemplo, '{{SIGN_HERE}}') que se localizan
automáticamente y se convierten en campos posicionados. El texto del
anclaje se elimina del PDF después del procesamiento de forma
predeterminada.
properties:
anchor_string:
type: string
minLength: 1
maxLength: 200
description: >-
Cadena de texto a buscar en el documento PDF. Los patrones comunes
incluyen '{{SIGN_HERE}}', '{{DATE}}', etc.
example: '{{SIGN_HERE}}'
type:
type: string
enum:
- signature
- initial
- initials
- text
- date
- checkbox
- radio_buttons
- radio
- dropdown
- textarea
- text_area
- url
- approval_signature
- approval_checkmark
- approval_date
description: Tipo de campo a colocar en la ubicación del anclaje
recipient_id:
oneOf:
- type: integer
- type: string
description: >-
ID del destinatario asignado a este campo. Usa un ID temporal (por
ejemplo, 'temp_1') para la creación basada en documentos, o un
número entero de orden para la basada en plantillas.
example: temp_1
x_offset:
type: number
description: >-
Desplazamiento horizontal desde la posición del anclaje. Las
unidades se determinan mediante offset_units (predeterminado:
porcentaje del ancho de página).
default: 0
y_offset:
type: number
description: >-
Desplazamiento vertical desde la posición del anclaje. Las unidades
se determinan mediante offset_units (predeterminado: porcentaje del
alto de página).
default: 0
offset_units:
type: string
enum:
- percent
- pixels
default: percent
description: >-
Tipo de unidad para x_offset y y_offset. 'percent' = porcentaje de
las dimensiones de la página, 'pixels' = puntos PDF (72 DPI).
width:
type: number
minimum: 0
exclusiveMinimum: true
description: >-
Ancho del campo como porcentaje del ancho de página. Los valores
predeterminados varían según el tipo de campo (por ejemplo,
signature=25, text=20, checkbox=3).
height:
type: number
minimum: 0
exclusiveMinimum: true
description: >-
Alto del campo como porcentaje del alto de página. Los valores
predeterminados varían según el tipo de campo (por ejemplo,
signature=5, text=3, checkbox=3).
case_sensitive:
type: boolean
default: false
description: >-
Indica si la coincidencia de la cadena de anclaje distingue entre
mayúsculas y minúsculas
match_whole_word:
type: boolean
default: true
description: >-
Indica si se deben coincidir solo palabras completas (delimitadas
por caracteres que no son de palabra)
ignore_if_not_present:
type: boolean
default: false
description: >-
Si es true, omite este anclaje sin generar un error cuando no se
encuentra en el documento. Si es false (predeterminado), un anclaje
faltante provoca un error de validación.
occurrence:
type: integer
minimum: 0
maximum: 1000
default: 0
description: >-
Qué ocurrencia usar para colocar un campo. 0 = todas las ocurrencias
(predeterminado), 1 = solo la primera, 2 = solo la segunda, etc.
remove_anchor_text:
type: boolean
default: true
description: >-
Indica si se debe eliminar el texto de anclaje del PDF dibujando un
rectángulo blanco sobre él
required:
type: boolean
default: true
description: Indica si el campo debe ser completado por el firmante
read_only:
type: boolean
default: false
description: Indica si el campo es de solo lectura (prellenado)
read_only_value:
type: string
nullable: true
maxLength: 10000
description: Valor estático para campos de solo lectura
variable_name:
type: string
nullable: true
maxLength: 255
description: Nombre de variable para el campo
variable_defined_name:
type: string
maxLength: 100
nullable: true
description: >-
Nombre legible de la definición de campo personalizado. Se puede
usar como alternativa a variable_name para apuntar a campos en la
creación basada en plantillas.
background_color:
type: string
nullable: true
pattern: ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$
description: Color de fondo en hexadecimal (por ejemplo, '#FFFDE7')
example: '#FFFDE7'
dropdown_options:
description: Opciones para campos desplegables
oneOf:
- type: array
items:
type: string
- type: object
date_default:
type: string
nullable: true
maxLength: 50
description: Valor de fecha predeterminado
date_signing_default:
type: boolean
default: false
description: Usar la fecha de firma como valor predeterminado
multi_group_id:
type: string
nullable: true
maxLength: 255
description: ID de grupo para vincular campos de casilla de verificación/radio
CreateAndSendResponse:
type: object
properties:
id:
type: string
format: uuid
description: ID de la solicitud de firma
name:
type: string
description: Nombre de la solicitud de firma
description:
type: string
nullable: true
description: Descripción de la solicitud de firma
status:
type: string
enum:
- sent
description: Siempre 'sent' para este endpoint
document_url:
type: string
format: uri
description: URL firmada para acceder al documento
page_count:
type: integer
description: Número de páginas del documento
expiration_hours:
type: integer
description: Horas hasta la expiración
settings:
$ref: '#/components/schemas/SigningRequestSettings'
created_date:
type: string
format: date-time
sent_date:
type: string
format: date-time
description: Cuándo se envió la solicitud
template_id:
type: string
format: uuid
nullable: true
first_signer:
type: object
description: Detalles del primer firmante que recibió el email
properties:
id:
type: string
format: uuid
name:
type: string
email:
type: string
format: email
signing_link:
type: string
format: uri
description: Enlace directo para que el firmante acceda a la vista de firma
recipients:
type: array
description: Todos los destinatarios con UUIDs reales
items:
type: object
properties:
id:
type: string
format: uuid
first_name:
type: string
last_name:
type: string
nullable: true
name:
type: string
email:
type: string
format: email
designation:
type: string
order:
type: integer
fields:
type: array
description: Todos los campos con UUIDs reales de destinatarios
items:
$ref: '#/components/schemas/Field'
credits_remaining:
type: integer
description: Créditos de la empresa restantes después de la deducción
description: Solicitud de firma creada y enviada
required:
- id
- name
- status
CreateAndSendValidationError:
type: object
properties:
error:
type: string
code:
type: string
description: Código de error legible por máquina
example: VALIDATION_ERROR
phase:
type: string
enum:
- create_validation
- send_validation
description: Qué fase de validación falló
validation_errors:
type: array
description: Errores de validación detallados de la fase de envío
items:
type: object
properties:
recipient_index:
type: integer
description: Índice del destinatario (basado en 1)
recipient_email:
type: string
missing_fields:
type: array
items:
type: string
description: Lista de campos requeridos faltantes
description: Error de validación durante create-and-send
required:
- error
- code
InsufficientCreditsError:
type: object
properties:
error:
type: string
example: >-
Insufficient credits. Please purchase more credits to send signing
requests.
code:
type: string
example: INSUFFICIENT_CREDITS
current_credits:
type: integer
example: 0
description: Error de créditos insuficientes
required:
- error
- code
- current_credits
Error:
type: object
properties:
error:
type: string
description: Mensaje de error legible para humanos
message:
type: string
description: Descripción detallada del error
details:
type: object
description: Detalles adicionales del error
additionalProperties: true
required:
- error
UnprocessableEntityError:
type: object
properties:
error:
type: string
example: A recipient's email address cannot receive messages.
code:
type: string
example: RECIPIENT_EMAIL_SUPPRESSED
description: Error de entidad no procesable
required:
- error
- code
SigningRequestSettings:
type: object
description: >-
Configuración devuelta por los endpoints de listado y detalle de
Solicitudes de Firma. Las Plantillas usan el esquema TemplateSettings
(sin campos de identidad).
properties:
allow_download:
type: boolean
description: Si los destinatarios pueden descargar el documento
default: true
attach_pdf_on_finish:
type: boolean
description: Si se debe adjuntar el PDF cuando se completa la firma
default: true
allow_editing_before_sending:
type: boolean
description: Si la Solicitud de Firma se puede editar antes de enviarse
default: false
use_signing_order:
type: boolean
description: >-
Si se aplica un orden de firma entre los destinatarios. Cuando es
true, los Firmantes reciben el documento en secuencia según su
order. Cuando es false, todos los Firmantes reciben el documento al
mismo tiempo.
default: true
hand_drawn_only:
type: boolean
description: >-
Cuando está habilitado, los Firmantes solo pueden dibujar su firma a
mano y no pueden usar firmas escritas/basadas en fuente
default: false
send_signing_email:
type: boolean
description: >-
Si se deben enviar correos de notificación de la Solicitud de Firma
a los Firmantes
default: true
send_finish_email:
type: boolean
description: >-
Si se debe enviar un correo de finalización cuando todos los
Firmantes terminan
default: true
send_expiration_email:
type: boolean
description: >-
Si se debe enviar un correo de notificación de expiración cuando la
solicitud expira
default: true
send_cancellation_email:
type: boolean
description: >-
Si se debe enviar un correo de notificación de cancelación cuando se
cancela la solicitud
default: true
require_otp_verification:
type: boolean
nullable: true
description: >-
Si los Firmantes deben verificar su correo con un código de un solo
uso antes de acceder al documento. null = hereda la configuración
del Espacio de Trabajo/empresa.
default: null
disable_guided_navigation:
type: boolean
nullable: true
description: >-
Desactiva el desplazamiento automático al siguiente campo requerido
durante la firma. Hereda del Espacio de Trabajo o de la empresa si
no está configurado.
allow_presigning_download:
type: boolean
nullable: true
description: >-
Permite a los Firmantes descargar el documento original antes de
firmar. Hereda de la configuración del Espacio de Trabajo o de la
empresa cuando es null.
show_qr_code:
type: boolean
nullable: true
description: >-
Muestra un código QR en la página de firma que permite a los
Firmantes continuar desde su teléfono. Hereda de la configuración
del Espacio de Trabajo o de la empresa cuando es null.
identity_editable_fields:
type: array
nullable: true
items:
type: string
description: >-
Campos de identidad que los Firmantes pueden editar antes de firmar
(por ejemplo, ["name", "company"]). null = desactivado. Cuando está
configurado, un diálogo de confirmación permite a los Firmantes
editar los campos especificados.
notify_identity_change_email:
type: boolean
default: false
description: >-
Envía una notificación por correo cuando un Firmante cambia su
identidad.
Field:
type: object
required:
- type
- position
- page_number
description: >-
Definición de campo para solicitudes de firma. **Campos de solo
lectura**: Establece read_only=true para prellenar un valor de campo que
los firmantes no puedan editar. Usa read_only_value para texto estático,
o prefilled_data para autocompletar a partir de los atributos del
destinatario. **Fusión de campos basada en plantilla**: Al crear desde
una plantilla con un array de fields, usa template_field_id (preferido)
o variable_name (alternativa) para hacer coincidir los campos de la
plantilla. Solo las propiedades proporcionadas sobrescriben los valores
predeterminados de la plantilla (actualización parcial). Los campos sin
coincidencia se ignoran.
properties:
id:
type: string
format: uuid
description: >-
Identificador único (inclúyelo para actualizaciones, omítelo para
campos nuevos)
template_field_id:
type: string
format: uuid
description: >-
ID del campo de plantilla a hacer coincidir para actualizaciones
parciales (solo en creación basada en plantilla). Úsalo para
identificar qué campo de la plantilla sobrescribir. Tiene prioridad
sobre variable_name para la coincidencia.
type:
type: string
enum:
- signature
- text
- date
- checkbox
- dropdown
- initial
- initials
- text_area
- textarea
- image
- stamp
- approval_signature
- approval_checkmark
- approval_date
description: >-
Tipo de campo. Acepta 'initial' o 'initials' (normalizado a
'initial'), 'textarea' o 'text_area' (normalizado a 'text_area').
position:
type: object
required:
- x
- 'y'
- width
- height
description: >-
El campo debe caber dentro de los límites de la página: x + width <=
100 e y + height <= 100
properties:
x:
type: number
minimum: 0
maximum: 100
description: Coordenada X como porcentaje (0-100)
'y':
type: number
minimum: 0
maximum: 100
description: Coordenada Y como porcentaje (0-100)
width:
type: number
minimum: 0
maximum: 100
description: Ancho como porcentaje (0-100). x + width debe ser <= 100
height:
type: number
minimum: 0
maximum: 100
description: Alto como porcentaje (0-100). y + height debe ser <= 100
page_number:
type: integer
minimum: 1
description: >-
Número de página donde se ubica el campo (indexado desde 1). No debe
exceder el total de páginas del documento.
required:
type: boolean
default: false
description: Si el campo debe completarse
recipient_id:
type: string
description: >-
ID del destinatario asignado a este campo. Usa un UUID real para
creación o actualizaciones basadas en plantilla, o un ID temporal
(por ejemplo, 'temp_1') para creación basada en documento, para
referenciar destinatarios definidos en la misma solicitud.
variable_name:
type: string
maxLength: 100
nullable: true
description: >-
Nombre de variable para el campo (usado en plantillas). También se
usa como alternativa para la coincidencia de campos en creación
basada en plantilla cuando no se proporciona template_field_id.
variable_defined_name:
type: string
maxLength: 100
nullable: true
description: >-
Nombre de definición de campo personalizado, legible por humanos.
Puede usarse como alternativa a variable_name para apuntar a campos
en creación basada en plantilla.
dropdown_options:
description: Opciones para campos desplegables
oneOf:
- type: array
items:
type: string
- type: object
date_default:
type: string
format: date
nullable: true
description: Valor de fecha predeterminado
date_signing_default:
type: boolean
default: false
description: Usar la fecha de firma como valor predeterminado
multi_group_id:
type: string
format: uuid
nullable: true
description: >-
ID de grupo para vincular varios campos de casilla de verificación o
botón de opción entre sí. Los campos que comparten el mismo
multi_group_id se comportan como un grupo mutuamente excluyente
(como botones de opción) - seleccionar uno deselecciona
automáticamente los demás del grupo. Usa el mismo UUID en varios
campos para crear un grupo donde solo se pueda seleccionar una
opción a la vez.
format_rules:
oneOf:
- $ref: '#/components/schemas/DateFormatRules'
- $ref: '#/components/schemas/FileFormatRules'
- type: object
additionalProperties: true
nullable: true
description: >-
Reglas de formato para el valor del campo. Para campos de fecha, usa
el esquema DateFormatRules con la propiedad dateFormat. Para campos
de archivo, usa el esquema FileFormatRules con la propiedad
acceptedFileTypes (image_and_pdf, image, o pdf). Para campos url,
usa { urlDisplayText: string }.
validation_rules:
$ref: '#/components/schemas/FieldValidationRules'
read_only:
type: boolean
default: false
description: >-
Indica si este campo es de solo lectura (prellenado antes de la
firma). Cuando es true, el firmante no puede editar el valor del
campo. Útil para mostrar los términos del contrato, información del
destinatario u otros datos fijos.
read_only_value:
type: string
nullable: true
description: >-
Valor estático para campos de solo lectura. Tiene prioridad sobre
prefilled_data si se especifican ambos. Solo aplicable cuando
read_only es true. Ejemplo: 'Contrato #12345' o 'Acme Corporation'.
prefilled_data:
type: string
nullable: true
enum:
- first_name
- last_name
- full_name
- email
- phone_number
- company
- title
- street_address
- city
- state_province
- postal_code
- country
description: >-
Atributo del usuario para autocompletar cuando read_only es true. El
valor se obtiene de los datos del destinatario asignado en el
momento de la firma. También puede hacer referencia a las claves de
custom_fields definidas en el destinatario (no se limita a los
valores del enum). Solo aplicable cuando read_only es true y
read_only_value no está configurado. Ejemplo: configúralo como
'email' para mostrar la dirección de correo electrónico del
destinatario.
required_conditions:
$ref: '#/components/schemas/ConditionSet'
nullable: true
description: >-
Reglas condicionales para cuándo este campo es obligatorio. Cuando
se configura, tiene prioridad sobre el indicador estático
'required'. El campo solo es obligatorio cuando las condiciones se
evalúan como verdaderas según los valores de otros campos.
visibility_conditions:
$ref: '#/components/schemas/ConditionSet'
nullable: true
description: >-
Reglas condicionales para cuándo este campo es visible. Cuando se
configura, el campo permanece oculto a menos que las condiciones se
evalúen como verdaderas. Los campos ocultos no se validan al enviar.
background_color:
type: string
nullable: true
pattern: ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$
description: >-
Color de fondo del campo como cadena de color hexadecimal (por
ejemplo, '#FFFDE7', '#fff'). Útil para resaltar campos que necesitan
atención.
example: '#FFFDE7'
DateFormatRules:
type: object
description: >-
Reglas de formato para campos de fecha. Especifica cómo deben mostrarse
y formatearse los valores de fecha.
properties:
dateFormat:
type: string
description: >-
Patrón de formato de fecha. Usa formatos predefinidos o patrones
personalizados con: yyyy (año de 4 dígitos), MM (mes de 2 dígitos),
dd (día de 2 dígitos), MMMM (nombre completo del mes), MMM (nombre
abreviado del mes), HH (hora en formato 24 horas), mm (minuto), ss
(segundo). Ejemplos: 'MM/dd/yyyy' se muestra como 01/31/2024, 'MMMM
dd, yyyy' se muestra como January 31, 2024.
enum:
- MM/dd/yyyy
- dd/MM/yyyy
- yyyy-MM-dd
- MMMM dd, yyyy
- MMM dd, yyyy
- dd MMMM yyyy
default: MM/dd/yyyy
example:
dateFormat: MMMM dd, yyyy
FileFormatRules:
type: object
description: >-
Reglas de formato para campos de carga de archivos. Especifica qué tipos
de archivo pueden subir los firmantes.
properties:
acceptedFileTypes:
type: string
enum:
- image_and_pdf
- image
- pdf
default: image_and_pdf
description: >-
Tipos de archivo aceptados para la carga. 'image_and_pdf' acepta
JPG, PNG y PDF. 'image' acepta solo JPG y PNG. 'pdf' acepta solo
PDF. Los archivos se validan por sus bytes mágicos (magic bytes), no
solo por la extensión. El tamaño máximo de archivo es 10MB.
example:
acceptedFileTypes: image_and_pdf
FieldValidationRules:
type: object
nullable: true
description: >-
Reglas de validación para valores de campo. Reservado para uso futuro:
actualmente no se aplica a ningún tipo de campo.
additionalProperties: true
ConditionSet:
type: object
required:
- logic
- groups
description: >-
Un conjunto de grupos de condiciones con lógica anidada. El operador
'logic' externo combina los grupos, mientras que las condiciones de cada
grupo usan el operador opuesto. Ejemplo: logic='and' significa que todos
los grupos deben coincidir, y dentro de cada grupo cualquier condición
puede coincidir (OR).
properties:
logic:
type: string
enum:
- and
- or
description: >-
Operador lógico para combinar grupos. 'and' = todos los grupos deben
coincidir, 'or' = cualquier grupo puede coincidir.
groups:
type: array
items:
$ref: '#/components/schemas/ConditionGroup'
description: Array de grupos de condiciones
ConditionGroup:
type: object
required:
- conditions
properties:
conditions:
type: array
items:
$ref: '#/components/schemas/Condition'
description: >-
Array de condiciones dentro de este grupo. Se combinan usando el
operador opuesto al del ConditionSet padre.
Condition:
type: object
required:
- field_id
- operator
description: Una sola condición que evalúa el valor de un campo.
properties:
field_id:
type: string
format: uuid
description: ID del campo a evaluar
operator:
type: string
enum:
- is_filled
- is_empty
- equals
- not_equals
- contains
- not_contains
- greater_than
- less_than
- greater_than_or_equal
- less_than_or_equal
description: >-
Operador de comparación. 'is_filled'/'is_empty' no requieren un
valor. Operadores de texto: equals, not_equals, contains,
not_contains. Operadores numéricos/de fecha: greater_than,
less_than, greater_than_or_equal, less_than_or_equal.
value:
oneOf:
- type: string
- type: number
nullable: true
description: >-
Valor con el que comparar. No es necesario para los operadores
is_filled/is_empty.
responses:
UnauthorizedError:
description: No Autorizado - Clave API inválida o faltante
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Unauthorized
message: Invalid API key
RateLimitError:
description: Demasiadas Solicitudes - Se superó el límite de solicitudes
headers:
X-RateLimit-Limit:
schema:
type: integer
description: Número máximo de solicitudes por minuto
X-RateLimit-Remaining:
schema:
type: integer
description: Solicitudes restantes
X-RateLimit-Reset:
schema:
type: integer
description: Marca de tiempo Unix del reinicio
Retry-After:
schema:
type: integer
description: Segundos hasta que se permita reintentar
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Rate Limit Exceeded
message: Too many requests. Please wait before retrying.
details:
retry_after: 45
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: >-
Clave API para autenticación. Usa tu clave API directamente sin ningún
prefijo (por ejemplo, 'your-api-key'). El prefijo Bearer es opcional
pero no obligatorio.
````