> ## 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 Solicitud de Firma
> Crea una nueva solicitud de firma ya sea a partir de un documento PDF (basado en documento) o a partir de una plantilla existente (basado en plantilla). Para la creación basada en documento, allow_editing_before_sending se establece automáticamente en true. Para la creación basada en plantilla, las propiedades se heredan de la plantilla y se pueden sobrescribir.
**Patrón de ID Temporal**: Para la creación basada en documento, puedes referenciar destinatarios antes de que se creen usando IDs temporales (formato: 'temp_X' donde X es cualquier identificador, por ejemplo, 'temp_1', 'temp_alice'). Usa estos IDs temporales en recipient.id, field.recipient_id y reminder.recipient_id. La API valida todas las referencias y mapea automáticamente los IDs temporales a UUID reales después de que se crean los destinatarios. La respuesta contiene solo UUID reales.
**Validación de ID Temporal**: Los IDs temporales deben comenzar con 'temp_', ser únicos entre todos los destinatarios de la solicitud, y todas las referencias de field/reminder deben apuntar a destinatarios definidos en la misma solicitud. Un formato inválido, IDs duplicados o referencias de destinatario faltantes devuelven un error 400 con mensajes de validación detallados.
## OpenAPI
````yaml api-reference/v01.30.00/openapi-v01.30.00.es.json post /signing-requests
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:
post:
tags:
- Signing Requests
summary: Crear Solicitud de Firma
description: >-
Crea una nueva solicitud de firma ya sea a partir de un documento PDF
(basado en documento) o a partir de una plantilla existente (basado en
plantilla). Para la creación basada en documento,
allow_editing_before_sending se establece automáticamente en true. Para
la creación basada en plantilla, las propiedades se heredan de la
plantilla y se pueden sobrescribir.
**Patrón de ID Temporal**: Para la creación basada en documento, puedes
referenciar destinatarios antes de que se creen usando IDs temporales
(formato: 'temp_X' donde X es cualquier identificador, por ejemplo,
'temp_1', 'temp_alice'). Usa estos IDs temporales en recipient.id,
field.recipient_id y reminder.recipient_id. La API valida todas las
referencias y mapea automáticamente los IDs temporales a UUID reales
después de que se crean los destinatarios. La respuesta contiene solo
UUID reales.
**Validación de ID Temporal**: Los IDs temporales deben comenzar con
'temp_', ser únicos entre todos los destinatarios de la solicitud, y
todas las referencias de field/reminder deben apuntar a destinatarios
definidos en la misma solicitud. Un formato inválido, IDs duplicados o
referencias de destinatario faltantes devuelven un error 400 con
mensajes de validación detallados.
operationId: createSigningRequest
requestBody:
$ref: '#/components/requestBodies/PatchSigningRequestBody'
responses:
'201':
description: >-
Solicitud de firma creada correctamente. La respuesta puede incluir
un array 'warnings' con advertencias de validación de formato de
email (no bloqueantes).
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/SigningRequestCreateResponse'
'400':
$ref: '#/components/responses/ValidationError'
description: >-
Entrada inválida: debes proporcionar 'document' o 'template_id', no
ambos. El documento debe ser un PDF válido codificado en base64 de
menos de 20MB. La plantilla debe existir y pertenecer al espacio de
trabajo.
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
description: Plantilla no encontrada o no pertenece al espacio de trabajo
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/RateLimitError'
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.createSigningRequest({
template_id: "template_id",
name: "Updated Contract Name",
expiration_hours: 72
});
console.log(response);
components:
requestBodies:
PatchSigningRequestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchSigningRequestBodySchema'
examples:
update-properties:
summary: Actualizar propiedades
value:
name: Updated Contract Name
expiration_hours: 72
update-recipient:
summary: Actualizar un solo destinatario
value:
recipient:
id: rec123-e89b-12d3-a456-426614174000
first_name: John
last_name: Smith
email: john.smith@example.com
designation: Signer
order: 1
add-recipient:
summary: Añadir nuevo destinatario
value:
recipient:
first_name: Jane
last_name: Doe
email: jane@example.com
designation: Signer
order: 2
add-date-field:
summary: Añadir campo de fecha con formato
value:
field:
type: date
position:
x: 70
'y': 45
width: 15
height: 3
page_number: 1
required: true
recipient_id: rec123-e89b-12d3-a456-426614174000
date_signing_default: true
format_rules:
dateFormat: MMMM dd, yyyy
add-read-only-static-field:
summary: Añadir campo de solo lectura con valor estático
description: >-
Crea un campo de texto que muestra un valor fijo que el firmante
no puede editar
value:
field:
type: text
position:
x: 15
'y': 20
width: 40
height: 3
page_number: 1
required: false
recipient_id: rec123-e89b-12d3-a456-426614174000
read_only: true
read_only_value: 'Contract #12345 - Acme Corporation'
add-read-only-prefilled-field:
summary: Añadir campo de solo lectura con datos del destinatario
description: >-
Crea un campo de texto que se autocompleta con el correo
electrónico del destinatario (el firmante no puede editarlo)
value:
field:
type: text
position:
x: 15
'y': 30
width: 30
height: 3
page_number: 1
required: false
recipient_id: rec123-e89b-12d3-a456-426614174000
read_only: true
prefilled_data: email
schemas:
SigningRequestCreateResponse:
type: object
description: >-
Solicitud de firma tal como la devuelven los endpoints CREATE (POST
/signing-requests)
properties:
id:
type: string
format: uuid
description: Identificador único de la solicitud de firma
name:
type: string
description: Nombre de la solicitud de firma
maxLength: 255
description:
type: string
nullable: true
description: Descripción de la solicitud de firma
status:
type: string
enum:
- draft
description: >-
El status siempre es 'draft' para solicitudes de firma recién
creadas
document_url:
type: string
format: uri
description: URL prefirmada al documento PDF
page_count:
type: integer
minimum: 1
description: Número de páginas en el documento
expiration_hours:
type: integer
minimum: 1
default: 168
description: >-
Horas hasta que la solicitud de firma expire (por defecto: 168 = 7
días)
template_id:
type: string
format: uuid
nullable: true
description: ID de la plantilla si se creó a partir de una plantilla
settings:
$ref: '#/components/schemas/SigningRequestSettings'
created_date:
type: string
format: date-time
description: Marca de tiempo de creación
updated_date:
type: string
format: date-time
description: Marca de tiempo de la última actualización
sent_date:
type: string
format: date-time
nullable: true
description: Cuándo se envió la solicitud de firma
finished_date:
type: string
format: date-time
nullable: true
description: Cuándo se completaron todas las firmas
cancelled_date:
type: string
format: date-time
nullable: true
description: Cuándo se canceló la solicitud de firma
recipients:
type: array
description: Destinatarios de la solicitud de firma
items:
$ref: '#/components/schemas/SigningRequestCreateRecipient'
fields:
type: array
description: Campos de la solicitud de firma con valores de posición planos
items:
$ref: '#/components/schemas/SigningRequestCreateField'
warnings:
type: array
items:
type: string
description: >-
Advertencias opcionales de validación de formato de correo
electrónico. Solo están presentes cuando los correos electrónicos de
los destinatarios tienen formatos inusuales.
required:
- id
- name
- status
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
PatchSigningRequestBodySchema:
oneOf:
- type: object
required:
- document
description: Crear una Solicitud de Firma a partir de un documento PDF
properties:
document:
type: string
format: byte
description: >-
Documento PDF o DOCX codificado en base64. Los archivos DOCX se
convierten automáticamente a PDF. El número de páginas se
extraerá automáticamente.
name:
type: string
maxLength: 255
description: Nombre para la Solicitud de Firma
description:
type: string
description: Descripción para la Solicitud de Firma
expiration_hours:
type: integer
minimum: 1
default: 168
description: >-
Horas hasta que expire la Solicitud de Firma (predeterminado:
168 = 7 días)
recipients:
type: array
items:
$ref: '#/components/schemas/Recipient'
description: >-
Destinatarios para la Solicitud de Firma. Usa IDs temporales
(por ejemplo, 'temp_1') en el campo id para hacer referencia a
los destinatarios en fields/reminders.
fields:
type: array
items:
$ref: '#/components/schemas/Field'
description: >-
Campos para colocar en el documento. Usa recipient_id para
asignar campos a los destinatarios.
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 añaden junto con cualquier campo
especificado manualmente. Solo está disponible para la creación
basada en documento (no basada en Plantilla).
reminders:
type: array
items:
$ref: '#/components/schemas/SigningRequestReminder'
description: Recordatorios para enviar a los destinatarios
settings:
$ref: '#/components/schemas/SigningRequestSettings'
description: Configuración de la Solicitud de Firma
- type: object
required:
- template_id
description: >-
Crear una Solicitud de Firma a partir de una Plantilla. Admite
actualizaciones parciales tanto para destinatarios como para campos.
properties:
template_id:
type: string
format: uuid
description: >-
ID de la Plantilla a partir de la cual crear la Solicitud de
Firma. El documento, los campos y los destinatarios
predeterminados se copiarán de la Plantilla.
name:
type: string
maxLength: 255
description: >-
Nombre personalizado para la Solicitud de Firma (usa el nombre
de la Plantilla de forma predeterminada si no se proporciona)
description:
type: string
description: >-
Descripción personalizada (usa la descripción de la Plantilla de
forma predeterminada si no se proporciona)
expiration_hours:
type: integer
minimum: 1
description: Sobrescribir las horas de expiración de la Plantilla
recipients:
type: array
items:
$ref: '#/components/schemas/Recipient'
description: >-
Sobrescrituras de destinatarios opcionales. Usa template_user_id
(preferido) u order (alternativa) para hacer coincidir con los
usuarios de la Plantilla. Solo se puede actualizar la
información del usuario (first_name, last_name, email,
phone_number, campos de dirección, title, company); order y
designation siempre se heredan de la Plantilla. Los
destinatarios no proporcionados usarán los valores
predeterminados de la Plantilla.
fields:
type: array
items:
$ref: '#/components/schemas/Field'
description: >-
Sobrescrituras opcionales de campos para actualizaciones
parciales. Usa template_field_id (preferido) o variable_name
(alternativa) para identificar los campos de la plantilla. Solo
las propiedades proporcionadas sobrescriben los valores
predeterminados de la plantilla. Propiedades de sobrescritura
admitidas: type, required, position, read_only, read_only_value,
format_rules, validation_rules, dropdown_options, date_default,
date_signing_default, multi_group_id. Los campos que no
coincidan se ignoran. Si se omite el array fields, se usan todos
los campos de la plantilla tal cual.
settings:
$ref: '#/components/schemas/SigningRequestSettings'
description: Sobrescribe la configuración de la plantilla
example:
template_id: 21424147-11c0-43d5-ac5f-a1f7001b5607
name: Contract for Client X
recipients:
- template_user_id: template-user-uuid-1
first_name: Toni
last_name: Campins
email: acampins@cocodin.com
fields:
- template_field_id: field-uuid-1
read_only: true
read_only_value: 'Contract #12345'
- variable_name: company_name
read_only_value: Acme Corporation
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.
SigningRequestCreateRecipient:
type: object
description: >-
Destinatario tal como se devuelve en las respuestas CREATE de
solicitudes de firma
properties:
id:
type: string
format: uuid
description: Identificador único del destinatario
first_name:
type: string
nullable: true
description: Nombre del destinatario
last_name:
type: string
nullable: true
description: Apellido del destinatario
name:
type: string
nullable: true
description: >-
Nombre completo combinado (construido automáticamente a partir de
first_name + last_name)
email:
type: string
format: email
description: Dirección de correo electrónico del destinatario
designation:
type: string
enum:
- Signer
- Approver
- CC
description: >-
Rol del destinatario. El Firmante firma el documento, el Aprobador
aprueba con campos de aprobación, CC recibe una copia cuando se
completa.
order:
type: integer
minimum: 1
description: Orden de firma
phone_number:
type: string
nullable: true
description: Número de teléfono del destinatario
street_address:
type: string
nullable: true
description: Dirección postal
city:
type: string
nullable: true
description: Ciudad
state_province:
type: string
nullable: true
description: Estado o provincia
postal_code:
type: string
nullable: true
description: Código postal
country:
type: string
nullable: true
description: País
title:
type: string
nullable: true
description: Puesto de trabajo
company:
type: string
nullable: true
description: Nombre de la empresa
custom_fields:
type: object
nullable: true
description: Pares clave-valor personalizados
finished_date:
type: string
format: date-time
nullable: true
description: Cuándo este destinatario completó la firma
required:
- first_name
- email
- designation
SigningRequestCreateField:
type: object
description: >-
Campo tal como se devuelve en las respuestas CREATE de solicitudes de
firma (posición plana, estilo base de datos)
properties:
id:
type: string
format: uuid
description: Identificador único del campo
type:
type: string
enum:
- text
- signature
- date
- checkbox
- dropdown
- radio_buttons
- number
- text_area
- file
- initial
- stamp
- approval_signature
- approval_checkmark
- approval_date
description: Tipo del campo
recipient_id:
type: string
format: uuid
nullable: true
description: ID del destinatario asignado
page_number:
type: integer
minimum: 1
description: Número de página (indexado desde 1)
x_position:
type: number
description: Coordenada X como porcentaje (0-100)
y_position:
type: number
description: Coordenada Y como porcentaje (0-100)
width:
type: number
description: Ancho como porcentaje (0-100)
height:
type: number
description: Alto como porcentaje (0-100)
required:
type: boolean
description: Indica si el campo es obligatorio
read_only:
type: boolean
description: Indica si este campo es de solo lectura
read_only_value:
type: string
nullable: true
description: Valor estático para campos de solo lectura
variable_name:
type: string
nullable: true
description: Nombre de variable para el mapeo de datos prellenados
variable_defined_name:
type: string
nullable: true
description: >-
Nombre de campo legible tomado de la definición del campo
personalizado (por ejemplo, 'artist_name'). Solo está presente para
campos vinculados a una definición de campo personalizado; de lo
contrario es nulo.
dropdown_options:
nullable: true
description: Opciones para campos desplegables
oneOf:
- type: array
items:
type: string
- type: object
format_rules:
type: object
nullable: true
description: Reglas de formato (por ejemplo, formato de fecha)
validation_rules:
type: object
nullable: true
description: Reglas de validación para el campo
date_signing_default:
type: boolean
description: Si se debe usar la fecha de firma como valor predeterminado
final_value:
type: string
nullable: true
description: Valor prellenado o final del campo
required:
- type
- recipient_id
- page_number
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
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'
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
SigningRequestReminder:
type: object
required:
- hours
- subject
- message
properties:
id:
type: string
format: uuid
description: >-
Identificador único (inclúyelo para actualizaciones, omítelo para
recordatorios nuevos)
hours:
type: integer
minimum: 1
description: Horas antes de la expiración para enviar el recordatorio
all_users:
type: boolean
default: false
description: Enviar recordatorio a todos los destinatarios
recipient_id:
type: string
nullable: true
description: >-
ID de destinatario específico (obligatorio si all_users es false).
Usa un UUID real para destinatarios existentes o un ID temporal (por
ejemplo, 'temp_1') para creación basada en documento, para
referenciar destinatarios dentro de la misma solicitud.
subject:
type: string
maxLength: 255
description: Asunto del email
message:
type: string
maxLength: 5000
description: Cuerpo del mensaje del email
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:
ValidationError:
description: Solicitud Incorrecta - La validación falló
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Validation Error
message: Invalid input data
details:
name: Name is required
email: Invalid email format
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.
````