> ## 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 Plantilla
> Actualización integral de la plantilla, incluyendo propiedades, usuarios, campos y recordatorios. Admite la eliminación de usuarios con reasignación o eliminación de campos. Todas las secciones son opcionales, pero se debe proporcionar al menos una.
## OpenAPI
````yaml api-reference/v01.30.00/openapi-v01.30.00.es.json put /templates/{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:
/templates/{id}:
put:
tags:
- Templates
summary: Actualización Integral de Plantilla
description: >-
Actualización integral de la plantilla, incluyendo propiedades,
usuarios, campos y recordatorios. Admite la eliminación de usuarios con
reasignación o eliminación de campos. Todas las secciones son
opcionales, pero se debe proporcionar al menos una.
operationId: updateTemplate
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
template_properties:
type: object
description: Actualizar los metadatos y la configuración de la plantilla
properties:
name:
type: string
maxLength: 255
description:
type: string
document:
type: string
format: byte
description: >-
PDF o DOCX codificado en Base64 para reemplazar el
documento. Los archivos DOCX se convierten
automáticamente a PDF. Tamaño máximo: 20MB
expiration_hours:
type: integer
minimum: 1
settings:
type: object
properties:
allow_editing_before_sending:
type: boolean
attach_pdf_on_finish:
type: boolean
allow_download:
type: boolean
hand_drawn_only:
type: boolean
require_otp_verification:
type: boolean
nullable: true
disable_guided_navigation:
type: boolean
nullable: true
allow_presigning_download:
type: boolean
nullable: true
description: >-
Permite a los firmantes descargar el documento
original antes de firmar. Hereda 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 la configuración del espacio de trabajo o de
la empresa cuando es null.
users:
type: array
description: >-
Insertar o actualizar usuarios (incluye id para actualizar,
omítelo para crear)
items:
type: object
required:
- first_name
- email
- designation
- order
properties:
id:
type: string
format: uuid
description: Omítelo para usuarios nuevos
first_name:
type: string
last_name:
type: string
description: >-
Opcional, pero requerido si se usan las variables
prellenadas full_name o last_name
email:
type: string
format: email
designation:
type: string
enum:
- Signer
- Approver
- CC
order:
type: integer
minimum: 1
phone_number:
type: string
street_address:
type: string
city:
type: string
state_province:
type: string
postal_code:
type: string
country:
type: string
title:
type: string
company:
type: string
force_remove_conditions:
type: boolean
default: false
description: >-
Al eliminar usuarios cuyos campos son referenciados por
condiciones en otros campos: si es true, elimina
automáticamente las referencias de condición; si es false
(predeterminado), la solicitud será rechazada con un error.
deleted_users:
type: array
description: Usuarios a eliminar con estrategia de manejo de campos
items:
type: object
required:
- user_id
- field_action
properties:
user_id:
type: string
format: uuid
field_action:
type: string
enum:
- delete
- reassign
description: Qué hacer con los campos asignados a este usuario
reassign_to_user_id:
type: string
format: uuid
description: >-
Requerido cuando field_action es 'reassign'. El
usuario destino debe tener la misma designación.
fields:
type: array
description: >-
Crea o actualiza campos (incluye id para actualizar, omítelo
para crear)
items:
type: object
required:
- type
- x
- 'y'
- width
- height
- page
properties:
id:
type: string
format: uuid
description: Omitir para campos nuevos
type:
type: string
enum:
- signature
- text
- date
- checkbox
- dropdown
- approval_signature
- approval_checkmark
- approval_date
x:
type: number
minimum: 0
maximum: 100
description: Posición X como porcentaje
'y':
type: number
minimum: 0
maximum: 100
description: Posición Y como porcentaje
width:
type: number
minimum: 0
maximum: 100
height:
type: number
minimum: 0
maximum: 100
page:
type: integer
minimum: 1
required:
type: boolean
default: false
assigned_to_user_id:
type: string
format: uuid
options:
type: array
items:
type: string
description: Para campos de tipo desplegable
default_to_signing_date:
type: boolean
description: Para campos de fecha
multi_group_id:
type: string
format: uuid
description: >-
ID de grupo para grupos de casillas de
verificación/botones de opción mutuamente excluyentes
variable_name:
type: string
variable_defined_name:
type: string
maxLength: 100
nullable: true
description: >-
Nombre de definición de campo personalizado legible
para humanos. Se puede usar como alternativa a
variable_name para apuntar a campos en la creación
basada en plantillas.
required_conditions:
$ref: '#/components/schemas/ConditionSet'
nullable: true
visibility_conditions:
$ref: '#/components/schemas/ConditionSet'
nullable: true
reminders:
type: array
description: >-
Crea o actualiza recordatorios (incluye id para actualizar,
omítelo para crear)
items:
type: object
required:
- hours
- subject
- message
properties:
id:
type: string
format: uuid
description: Omitir para recordatorios nuevos
hours:
type: integer
minimum: 1
description: Horas después del envío antes del recordatorio
all_users:
type: boolean
default: false
user_id:
type: string
format: uuid
description: Requerido si all_users es false
subject:
type: string
maxLength: 255
message:
type: string
maxLength: 5000
responses:
'200':
description: >-
Plantilla actualizada correctamente. Devuelve la plantilla completa
con todas sus relaciones.
headers:
X-RateLimit-Limit:
schema:
type: integer
description: 'Límite de solicitudes: 120 solicitudes por minuto'
X-RateLimit-Remaining:
schema:
type: integer
X-RateLimit-Reset:
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
'400':
$ref: '#/components/responses/ValidationError'
'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.templates.updateTemplate({
id: "id"
});
console.log(response);
components:
schemas:
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
Template:
type: object
properties:
id:
type: string
format: uuid
description: Identificador único de la plantilla
name:
type: string
description: Nombre de la plantilla
maxLength: 255
description:
type: string
description: Descripción de la plantilla
nullable: true
document_url:
type: string
format: uri
description: >-
URL prefirmada al documento PDF. Es una URL firmada con tiempo
limitado para acceso seguro; consulta document_url_expires_at para
conocer el momento de expiración. Las URLs iniciales son válidas por
7 días; las URLs renovadas son válidas por 1 hora. Solicita una
nueva recuperación de la plantilla para obtener una URL nueva si ha
expirado.
document_url_expires_at:
type: string
format: date-time
nullable: true
description: >-
Marca de tiempo ISO 8601 de cuándo expirará document_url. Después de
este momento, la URL devolverá un error de acceso denegado. Vuelve a
obtener la plantilla para recibir una nueva URL firmada.
page_count:
type: integer
minimum: 1
description: Número de páginas del documento
expiration_hours:
type: integer
minimum: 1
default: 168
description: >-
Horas hasta que expiren las solicitudes de firma creadas a partir de
esta plantilla
credit_cost:
type: integer
minimum: 1
default: 1
description: >-
Número de créditos consumidos cuando se envía una solicitud de firma
desde esta plantilla. El valor mínimo es 1.
settings:
$ref: '#/components/schemas/SigningRequestSettings'
recipients:
type: array
items:
$ref: '#/components/schemas/TemplateUser'
description: >-
Destinatarios de la plantilla (incluido en GET de una sola
plantilla)
fields:
type: array
items:
$ref: '#/components/schemas/TemplateField'
description: Campos de la plantilla (incluido en GET de una sola plantilla)
created_date:
type: string
format: date-time
description: Marca de tiempo de creación de la plantilla
updated_date:
type: string
format: date-time
description: Marca de tiempo de la última actualización de la plantilla
required:
- id
- name
- created_date
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.
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.
TemplateUser:
type: object
properties:
id:
type: string
format: uuid
description: Identificador único del usuario de la plantilla
name:
type: string
description: Nombre del destinatario (nombre y apellido combinados)
email:
type: string
format: email
description: Dirección de correo electrónico del destinatario
first_name:
type: string
nullable: true
description: Nombre del destinatario
last_name:
type: string
nullable: true
description: Apellido 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 finalizar.
order:
type: integer
minimum: 1
description: Orden en el que el destinatario debe firmar
phone_number:
type: string
nullable: true
description: Número de teléfono del destinatario
street_address:
type: string
nullable: true
description: Dirección postal del destinatario
city:
type: string
nullable: true
description: Ciudad del destinatario
state_province:
type: string
nullable: true
description: Estado o provincia del destinatario
postal_code:
type: string
nullable: true
description: Código postal del destinatario
country:
type: string
nullable: true
description: País del destinatario
title:
type: string
nullable: true
description: Cargo del destinatario
company:
type: string
nullable: true
description: Nombre de la empresa del destinatario
required_fields:
type: array
items:
type: string
description: >-
Lista de campos de datos del destinatario requeridos para el envío
(basada en los campos de la plantilla con asignaciones de
variable_name). Siempre incluye 'email' y 'first_name'.
missing_fields:
type: array
items:
type: string
description: >-
Lista de campos requeridos que actualmente están vacíos para este
destinatario
required_read_only_fields:
type: array
items:
type: object
properties:
variable_name:
type: string
nullable: true
description: Nombre de variable del campo de solo lectura
variable_defined_name:
type: string
nullable: true
description: >-
Nombre del campo legible para humanos, 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 null.
field_type:
type: string
description: Tipo del campo (text, date, etc.)
description: >-
Lista de campos obligatorios de solo lectura que necesitan valores
prellenados antes de enviar
ready_to_send:
type: boolean
description: >-
Indica si este destinatario tiene todos los datos obligatorios
completados para poder enviarse
required:
- id
- first_name
- email
- designation
- order
TemplateField:
type: object
description: Un campo colocado en un documento de plantilla
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
required:
type: boolean
description: Indica si el campo es obligatorio
recipient_id:
type: string
format: uuid
nullable: true
description: ID del destinatario asignado
variable_name:
type: string
nullable: true
description: Nombre de variable del campo (usado en plantillas)
variable_defined_name:
type: string
nullable: true
description: >-
Nombre del campo legible para humanos, 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 null.
position:
type: object
description: >-
Posición y dimensiones del campo en el documento. Todos los valores
son porcentajes (0-100). El campo debe caber dentro de la página: x
+ width <= 100 y y + height <= 100.
properties:
x:
type: number
minimum: 0
maximum: 100
description: Coordenada X de la posición del campo (porcentaje, 0-100)
'y':
type: number
minimum: 0
maximum: 100
description: Coordenada Y de la posición del campo (porcentaje, 0-100)
width:
type: number
minimum: 0
maximum: 100
description: >-
Ancho del campo (porcentaje, 0-100). Nota: x + width debe ser <=
100
height:
type: number
minimum: 0
maximum: 100
description: >-
Alto del campo (porcentaje, 0-100). Nota: y + height debe ser <=
100
page_number:
type: integer
minimum: 1
nullable: true
description: >-
Número de página donde se encuentra el campo (empieza en 1). No debe
superar el total de páginas del documento.
dropdown_options:
nullable: true
description: Opciones para campos desplegables
oneOf:
- type: array
items:
type: string
- type: object
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 puede seleccionar una
opción a la vez.
date_default:
type: string
format: date
nullable: true
description: >-
Valor de fecha predeterminado para campos de fecha (formato ISO
8601, por ejemplo, '2024-01-15')
date_signing_default:
type: boolean
description: >-
Usar la fecha de firma como valor predeterminado para campos de
fecha
format_rules:
$ref: '#/components/schemas/DateFormatRules'
nullable: true
description: >-
Reglas de formato: actualmente se usan para campos de fecha, para
especificar el formato de visualización
validation_rules:
$ref: '#/components/schemas/FieldValidationRules'
read_only:
type: boolean
default: false
description: Indica si este campo es de solo lectura (prellenado antes de firmar)
read_only_value:
type: string
nullable: true
description: Valor estático para campos de solo lectura
required:
- id
- type
- page_number
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
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.
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
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
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
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.
````