> ## 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.
# Actualización Integral de Solicitud de Firma
> Realiza actualizaciones integrales a una solicitud de firma, incluyendo propiedades, destinatarios, campos y recordatorios. No se puede actualizar después de que la solicitud de firma haya sido enviada, completada o cancelada. Todas las secciones son opcionales, pero se debe proporcionar al menos una.
**Patrón de ID Temporal para Nuevos Destinatarios**: Al agregar nuevos destinatarios en una actualización integral, usa el campo '_temp_id' (formato: 'temp_X') en lugar de 'id' para establecer relaciones con campos y recordatorios. Esto te permite crear nuevos destinatarios y referenciarlos en campos/recordatorios en una sola solicitud. Usa el campo 'id' para actualizar destinatarios existentes. Reglas de validación: (1) Los IDs temporales deben comenzar con 'temp_'; (2) Cada ID temporal debe ser único dentro de la solicitud; (3) Los campos y recordatorios pueden referenciar IDs temporales en su propiedad recipient_id; (4) La API resolverá automáticamente los IDs temporales a UUIDs reales después de la creación del destinatario.
## OpenAPI
````yaml api-reference/v01.30.00/openapi-v01.30.00.es.json put /signing-requests/{id}
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/{id}:
put:
tags:
- Signing Requests
summary: Actualización Integral de Solicitud de Firma
description: >-
Realiza actualizaciones integrales a una solicitud de firma, incluyendo
propiedades, destinatarios, campos y recordatorios. No se puede
actualizar después de que la solicitud de firma haya sido enviada,
completada o cancelada. Todas las secciones son opcionales, pero se debe
proporcionar al menos una.
**Patrón de ID Temporal para Nuevos Destinatarios**: Al agregar nuevos
destinatarios en una actualización integral, usa el campo '_temp_id'
(formato: 'temp_X') en lugar de 'id' para establecer relaciones con
campos y recordatorios. Esto te permite crear nuevos destinatarios y
referenciarlos en campos/recordatorios en una sola solicitud. Usa el
campo 'id' para actualizar destinatarios existentes. Reglas de
validación: (1) Los IDs temporales deben comenzar con 'temp_'; (2) Cada
ID temporal debe ser único dentro de la solicitud; (3) Los campos y
recordatorios pueden referenciar IDs temporales en su propiedad
recipient_id; (4) La API resolverá automáticamente los IDs temporales a
UUIDs reales después de la creación del destinatario.
operationId: updateSigningRequest
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ID de la solicitud de firma
requestBody:
$ref: '#/components/requestBodies/UpdateSigningRequestBody'
responses:
'200':
description: >-
Solicitud de firma actualizada correctamente. Devuelve la solicitud
de firma actualizada y un resumen de los cambios realizados.
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/SigningRequestUpdateResponse'
'400':
description: >-
Errores de validación. Todos los errores de sección se devuelven
juntos.
content:
application/json:
schema:
$ref: '#/components/schemas/SigningRequestUpdateError'
example:
error: Validation failed
message: Multiple validation errors occurred
details:
recipients:
- 'Recipient 1: email is invalid'
deleted_recipients:
- 'Cannot reassign: designations must match'
fields:
- 'Field 2: x coordinate must be between 0 and 100'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'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.updateSigningRequest({
id: "id",
signing_request_properties: {
name: "Updated Contract Name",
expiration_hours: 72
},
recipients: [{
id: "rec1-e89b-12d3-a456-426614174000",
first_name: "John",
last_name: "Smith",
email: "john.smith@example.com",
designation: "Signer",
order: 1
}, {
first_name: "Jane",
last_name: "Doe",
email: "jane@example.com",
designation: "Signer",
order: 2
}],
deleted_recipients: [{
recipient_id: "rec2-e89b-12d3-a456-426614174000",
field_action: "reassign",
reassign_to_recipient_id: "rec1-e89b-12d3-a456-426614174000"
}],
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"
}],
reminders: [{
hours: 48,
all_users: true,
subject: "Reminder: Please sign the document",
message: "This is a reminder to complete your signature."
}]
});
console.log(response);
components:
requestBodies:
UpdateSigningRequestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSigningRequestBodySchema'
examples:
comprehensive-update:
summary: Actualización completa con todas las secciones
value:
signing_request_properties:
name: Updated Contract Name
expiration_hours: 72
recipients:
- id: rec1-e89b-12d3-a456-426614174000
first_name: John
last_name: Smith
email: john.smith@example.com
designation: Signer
order: 1
- first_name: Jane
last_name: Doe
email: jane@example.com
designation: Signer
order: 2
deleted_recipients:
- recipient_id: rec2-e89b-12d3-a456-426614174000
field_action: reassign
reassign_to_recipient_id: rec1-e89b-12d3-a456-426614174000
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
reminders:
- hours: 48
all_users: true
subject: 'Reminder: Please sign the document'
message: This is a reminder to complete your signature.
update-with-temp-ids:
summary: Actualizar con nuevos destinatarios usando IDs temporales
description: >-
Actualización completa que añade nuevos destinatarios con IDs
temporales junto a los destinatarios existentes
value:
signing_request_properties:
name: Updated NDA Agreement
recipients:
- id: existing-recipient-uuid
email: updated@example.com
- _temp_id: temp_new_signer
first_name: New
last_name: Signer
email: newsigner@example.com
designation: Signer
order: 2
fields:
- id: existing-field-uuid
position:
x: 10
'y': 70
width: 30
height: 10
- recipient_id: temp_new_signer
type: signature
page_number: 1
position:
x: 10
'y': 55
width: 30
height: 10
required: true
reminders:
- recipient_id: temp_new_signer
hours: 24
all_users: false
subject: 'Reminder: Sign Document'
message: Please sign the updated NDA.
schemas:
SigningRequestUpdateResponse:
type: object
properties:
id:
type: string
format: uuid
description: >-
ID de la solicitud de firma (por compatibilidad con versiones
anteriores)
name:
type: string
description: >-
Nombre de la solicitud de firma (por compatibilidad con versiones
anteriores)
signing_request:
type: object
description: >-
Resumen de la solicitud de firma actualizada (subconjunto del
esquema completo de SigningRequest)
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 (mapeada desde
template_description)
document_url:
type: string
format: uri
description: URL prefirmada al documento PDF
document_url_expires_at:
type: string
format: date-time
nullable: true
description: Cuándo expira la URL del documento
document_page_count:
type: integer
description: Número de páginas del documento
status:
type: string
description: Estado actual de la solicitud de firma
expiration_hours:
type: integer
description: Horas hasta que expira la solicitud de firma
settings:
type: object
description: >-
Subconjunto de la configuración de la solicitud de firma
devuelto en la respuesta PUT
properties:
allow_download:
type: boolean
description: Si los destinatarios pueden descargar el documento
attach_pdf_on_finish:
type: boolean
description: Si se debe adjuntar el PDF al finalizar
hand_drawn_only:
type: boolean
description: Si solo se permiten firmas dibujadas a mano
template_id:
type: string
format: uuid
nullable: true
description: ID de la plantilla si se creó a partir de una plantilla
expires_at:
type: string
format: date-time
nullable: true
description: Timestamp ISO 8601 de cuándo expira la solicitud de firma
created_date:
type: string
format: date-time
description: Timestamp de creació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
items:
$ref: '#/components/schemas/Recipient'
description: Lista actualizada de destinatarios
reminders:
type: array
items:
$ref: '#/components/schemas/Reminder'
description: Lista actualizada de recordatorios
summary:
type: object
description: Resumen de todos los cambios realizados en esta actualización
properties:
properties_updated:
type: boolean
description: Si se actualizó alguna propiedad
recipients_created:
type: integer
description: Número de destinatarios nuevos creados
recipients_updated:
type: integer
description: Número de destinatarios existentes actualizados
recipients_deleted:
type: integer
description: >-
Número de destinatarios eliminados de forma reversible
(soft-delete)
fields_created:
type: integer
description: Número de campos nuevos creados
fields_updated:
type: integer
description: Número de campos existentes actualizados
fields_reassigned:
type: integer
description: Número de campos reasignados a otro destinatario
fields_deleted:
type: integer
description: Número de campos eliminados de forma reversible (soft-delete)
reminders_created:
type: integer
description: Número de recordatorios nuevos creados
reminders_updated:
type: integer
description: Número de recordatorios existentes actualizados
warnings:
type: array
items:
type: string
description: >-
Advertencias de formato de email para destinatarios (no
bloqueantes)
description: Resultado de la actualización de la solicitud de firma
required:
- id
- name
SigningRequestUpdateError:
type: object
properties:
error:
type: string
message:
type: string
details:
type: object
properties:
signing_request_properties:
type: array
items:
type: string
recipients:
type: array
items:
type: string
deleted_recipients:
type: array
items:
type: string
fields:
type: array
items:
type: string
reminders:
type: array
items:
type: string
description: Error de validación al actualizar la solicitud de firma
required:
- error
UpdateSigningRequestBodySchema:
type: object
properties:
signing_request_properties:
type: object
description: Actualiza las propiedades de la solicitud de firma
properties:
name:
type: string
maxLength: 255
description:
type: string
document:
type: string
format: byte
description: Reemplaza el documento (PDF codificado en base64)
expiration_hours:
type: integer
minimum: 1
settings:
$ref: '#/components/schemas/SigningRequestSettings'
recipients:
type: array
items:
$ref: '#/components/schemas/Recipient'
description: >-
Inserta o actualiza destinatarios: incluye 'id' para actualizar
destinatarios existentes, usa '_temp_id' (por ejemplo, 'temp_1')
para destinatarios nuevos y así poder referenciarlos en fields y
reminders dentro de la misma solicitud
deleted_recipients:
type: array
items:
$ref: '#/components/schemas/DeletedRecipient'
description: Destinatarios a eliminar y cómo manejar sus campos
force_remove_conditions:
type: boolean
default: false
description: >-
Al eliminar destinatarios cuyos campos son referenciados por
condiciones en otros campos: si es true, se eliminan automáticamente
las referencias de la condición; si es false (predeterminado), la
solicitud se rechazará con un error que lista los campos
dependientes.
fields:
type: array
items:
$ref: '#/components/schemas/Field'
description: >-
Inserta o actualiza campos: incluye id para actualizar, omite id
para crear uno nuevo
reminders:
type: array
items:
$ref: '#/components/schemas/SigningRequestReminder'
description: >-
Inserta o actualiza recordatorios: incluye id para actualizar, omite
id para crear uno nuevo
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
Reminder:
type: object
properties:
id:
type: string
format: uuid
description: Identificador único del recordatorio
hours:
type: integer
minimum: 1
description: Horas después del envío antes de que se envíe el recordatorio
subject:
type: string
description: Asunto del correo para el recordatorio
maxLength: 255
message:
type: string
description: Cuerpo del mensaje de correo para el recordatorio
maxLength: 5000
all_users:
type: boolean
description: Indica si el recordatorio aplica a todos los usuarios
template_user_id:
type: string
format: uuid
nullable: true
description: >-
Usuario específico al que se le enviará el recordatorio (usado en el
contexto de plantilla)
recipient_id:
type: string
format: uuid
nullable: true
description: >-
Destinatario específico al que se le enviará el recordatorio (usado
en el contexto de solicitud de firma, es lo mismo que
template_user_id)
sent_on:
type: string
format: date-time
nullable: true
description: Marca de tiempo de cuándo se envió realmente el recordatorio
created_at:
type: string
format: date-time
description: Marca de tiempo de creación del recordatorio
updated_at:
type: string
format: date-time
description: Marca de tiempo de la última actualización del recordatorio
required:
- id
- hours
- subject
- message
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
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.
DeletedRecipient:
type: object
required:
- recipient_id
- field_action
properties:
recipient_id:
type: string
format: uuid
description: ID del destinatario a eliminar
field_action:
type: string
enum:
- delete
- reassign
description: Acción a realizar con los campos asignados a este destinatario
reassign_to_recipient_id:
type: string
format: uuid
description: >-
Destinatario al que reasignar los campos (obligatorio si
field_action es 'reassign')
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'
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:
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
NotFoundError:
description: No Encontrado - El recurso no existe
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Not Found
message: The requested resource was not found
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.
````