> ## 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.
# Listar Plantillas
> Recupera una lista paginada de plantillas
## OpenAPI
````yaml api-reference/v01.30.00/openapi-v01.30.00.es.json get /templates
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:
get:
tags:
- Templates
summary: Listar Plantillas
description: Recupera una lista paginada de plantillas
operationId: listTemplates
parameters:
- name: page
in: query
schema:
type: integer
minimum: 1
default: 1
description: Número de página
- name: page_size
in: query
schema:
type: integer
minimum: 1
maximum: 200
default: 50
description: Elementos por página
- name: name
in: query
schema:
type: string
description: >-
Filtrar por nombre de plantilla (coincidencia parcial, sin
distinción entre mayúsculas y minúsculas)
- name: created_after
in: query
schema:
type: string
format: date-time
description: Filtrar plantillas creadas después de esta fecha (formato ISO 8601)
- name: created_before
in: query
schema:
type: string
format: date-time
description: Filtrar plantillas creadas antes de esta fecha (formato ISO 8601)
- name: sort_by
in: query
schema:
type: string
enum:
- name
- created_on
- last_changed_on
default: created_on
description: Campo por el cual ordenar
- name: sort_order
in: query
schema:
type: string
enum:
- asc
- desc
default: desc
description: Orden de clasificación
responses:
'200':
description: Plantillas recuperadas exitosamente
headers:
X-RateLimit-Limit:
schema:
type: integer
description: 'Límite de tasa: 200 solicitudes por minuto'
X-RateLimit-Remaining:
schema:
type: integer
X-RateLimit-Reset:
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateListResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
'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.listTemplates();
console.log(response);
components:
schemas:
TemplateListResponse:
type: object
description: Lista paginada de plantillas
properties:
results:
type: array
items:
$ref: '#/components/schemas/Template'
pagination:
$ref: '#/components/schemas/Pagination'
required:
- results
- pagination
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
Pagination:
type: object
properties:
current_page:
type: integer
page_size:
type: integer
total_count:
type: integer
total_pages:
type: integer
description: Metadatos de paginación para respuestas de listas
required:
- current_page
- page_size
- total_count
- total_pages
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.
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
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:
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.
````