> ## 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.
# Actualizar Parcialmente una Solicitud de Firma
> Actualiza las propiedades de la Solicitud de Firma, un solo destinatario, O un solo campo. No se pueden actualizar varios tipos de entidad en una misma solicitud. No se puede actualizar después de que la Solicitud de Firma haya sido enviada, completada o cancelada.
## OpenAPI
````yaml api-reference/v01.30.00/openapi-v01.30.00.es.json patch /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}:
patch:
tags:
- Signing Requests
summary: Actualizar Parcialmente una Solicitud de Firma
description: >-
Actualiza las propiedades de la Solicitud de Firma, un solo
destinatario, O un solo campo. No se pueden actualizar varios tipos de
entidad en una misma solicitud. No se puede actualizar después de que la
Solicitud de Firma haya sido enviada, completada o cancelada.
operationId: patchSigningRequest
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ID de la Solicitud de Firma
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- type: object
description: Actualizar solo las propiedades de la Solicitud de Firma
properties:
name:
type: string
maxLength: 255
description: Nuevo nombre para la solicitud de firma
description:
type: string
description: Nueva descripción
document:
type: string
format: byte
description: >-
Reemplaza el documento con un nuevo PDF codificado en
base64. El número de páginas se extraerá
automáticamente.
expiration_hours:
type: integer
minimum: 1
description: Nuevas horas de expiración
settings:
$ref: '#/components/schemas/SigningRequestSettings'
description: Actualizar configuración
- type: object
required:
- recipient
description: Crea o actualiza un solo destinatario
properties:
recipient:
$ref: '#/components/schemas/Recipient'
description: >-
Destinatario a crear (omite id) o actualizar (incluye
id). Al actualizar first_name o last_name, el campo name
se reconstruye automáticamente usando los valores
existentes de la base de datos para cualquier campo no
proporcionado. Resultado: 'Nombre Apellido' si ambos
existen, 'Nombre' si solo existe first_name.
- type: object
required:
- field
description: Crea o actualiza un solo campo
properties:
field:
type: object
properties:
id:
type: string
format: uuid
description: >-
Inclúyelo para actualizar un campo existente,
omítelo para crear uno nuevo
type:
type: string
enum:
- text
- signature
- date
- checkbox
- initial
- initials
- dropdown
- radio_buttons
- textarea
- text_area
- url
- file
- stamp
- approval_signature
- approval_checkmark
- approval_date
description: >-
Tipo de campo. Acepta 'initial' o 'initials',
'textarea' o 'text_area'. Obligatorio para campos
nuevos. Los campos url son de solo lectura
automáticamente. Los campos file permiten a los
firmantes subir archivos adjuntos (imágenes/PDF).
Los campos stamp muestran una imagen preconfigurada.
position:
type: object
properties:
x:
type: number
description: Posición X en el documento
'y':
type: number
description: Posición Y en el documento
width:
type: number
description: Ancho del campo
height:
type: number
description: Alto del campo
description: >-
Objeto de posición. Todas las propiedades son
obligatorias para campos nuevos.
page_number:
type: integer
minimum: 1
description: >-
Número de página (indexado desde 1). Obligatorio
para campos nuevos.
required:
type: boolean
description: Si el campo es obligatorio
recipient_id:
type: string
format: uuid
nullable: true
description: ID del destinatario al que se asigna el campo
variable_name:
type: string
description: >-
Nombre de variable para el mapeo de datos
prellenados
variable_defined_name:
type: string
maxLength: 100
nullable: true
description: >-
Nombre legible de definición de campo personalizado.
Se puede usar como alternativa a variable_name para
apuntar a campos en la creación basada en plantilla.
dropdown_options:
description: Opciones para campos desplegables
oneOf:
- type: array
items:
type: string
- type: object
format_rules:
type: object
description: >-
Reglas de formato (p. ej., formato de fecha,
urlDisplayText para campos url, acceptedFileTypes
para campos file)
validation_rules:
type: object
description: Reglas de validación para el campo
multi_group_id:
type: string
format: uuid
description: ID de grupo para grupos de botones de opción
date_default:
type: string
description: Valor de fecha predeterminado
date_signing_default:
type: boolean
description: >-
Para campos de fecha, usa la fecha de firma como
valor predeterminado
read_only:
type: boolean
description: >-
Si el campo es de solo lectura (automáticamente
verdadero para campos url)
read_only_value:
type: string
description: >-
Valor estático para campos de solo lectura. Para
campos url, esta es la URL a la que enlazar.
final_value:
type: string
description: >-
Valor final del campo (para campos de solo lectura
prellenados)
examples:
update-properties:
summary: Actualizar propiedades
value:
name: Updated Contract Name
expiration_hours: 72
update-recipient:
summary: Actualizar destinatario único
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: Agregar nuevo destinatario
value:
recipient:
first_name: Jane
last_name: Doe
email: jane@example.com
designation: Signer
order: 2
create-url-field:
summary: Crear campo URL
value:
field:
type: url
position:
x: 100
'y': 200
width: 150
height: 30
page_number: 1
read_only_value: https://example.com/terms
format_rules:
urlDisplayText: View Terms & Conditions
create-file-field:
summary: Crear campo de subida de archivo
value:
field:
type: file
position:
x: 100
'y': 300
width: 200
height: 40
page_number: 1
required: true
format_rules:
acceptedFileTypes: image_and_pdf
update-field:
summary: Actualizar posición de campo existente
value:
field:
id: field123-e89b-12d3-a456-426614174000
position:
x: 120
'y': 220
responses:
'200':
description: >-
Solicitud de firma actualizada correctamente. La forma de la
respuesta depende de lo que se haya actualizado: la actualización de
propiedades devuelve {id, name, template_description, document_url,
expiration_hours}; la actualización de destinatario devuelve el
objeto de destinatario completo; la actualización de campo devuelve
el objeto de campo completo. La respuesta puede incluir un campo
'warning' para advertencias de validación de formato de correo
electrónico (no bloqueante).
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:
oneOf:
- type: object
description: Respuesta al actualizar propiedades
properties:
id:
type: string
format: uuid
name:
type: string
template_description:
type: string
nullable: true
document_url:
type: string
format: uri
expiration_hours:
type: integer
- type: object
description: Respuesta al actualizar/crear un destinatario
- type: object
description: Respuesta al actualizar/crear un campo
'400':
description: >-
Solicitud Incorrecta - No se pueden actualizar propiedades y
destinatario en la misma solicitud, o la solicitud de firma ya fue
enviada/completada/cancelada
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
cannot-update-sent:
value:
error: Cannot update signing request
message: >-
Signing request has already been sent and cannot be
modified
mixed-update:
value:
error: Invalid request
message: >-
Cannot update both properties and recipient in the same
request
'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.patchSigningRequest({
id: "id",
body: {
name: "Updated Contract Name",
expiration_hours: 72
}
});
console.log(response);
components:
schemas:
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.
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
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
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.
````