> ## 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 Solicitudes de Firma
> Recupera una lista paginada de solicitudes de firma
## OpenAPI
````yaml api-reference/v01.30.00/openapi-v01.30.00.es.json get /signing-requests
openapi: 3.0.3
info:
title: API de Socios de Firma
description: >-
API RESTful para firma de documentos y gestión de plantillas.
**Autenticación**: Todos los endpoints requieren autenticación mediante
clave API a través del encabezado `Authorization`. Usa tu clave API
directamente sin ningún prefijo (por ejemplo, `your-api-key`). El prefijo
Bearer es opcional pero no obligatorio.
**Características de Seguridad**:
- Validación de entrada usando esquemas Zod con mensajes de error detallados
a nivel de campo
- Tokens JWT firmados con RSA-256 para el acceso al Editor de Plantillas
incrustado
**Límite de Solicitudes**: Los límites de solicitudes están escalonados
según el tipo de operación:
- Operaciones de lectura (GET): 200 solicitudes por minuto
- Operaciones de escritura (POST/PUT/PATCH/DELETE): 120 solicitudes por
minuto
- Operaciones CRUD de webhooks: 60 solicitudes por minuto
- Prueba de webhook: 10 solicitudes por minuto
- Regeneración/expiración de clave API: 1 solicitud por minuto
- Rotación de secreto de webhook: 1 solicitud por minuto
Cuando se superan los límites de solicitudes, la API devuelve una respuesta
`429 Too Many Requests` con los encabezados:
- `X-RateLimit-Limit`: Máximo de solicitudes por minuto para este endpoint
- `X-RateLimit-Remaining`: Solicitudes restantes en la ventana actual
- `X-RateLimit-Reset`: Marca de tiempo Unix de cuándo se restablece el
límite
- `Retry-After`: Segundos hasta que se permita reintentar
**Manejo de Errores**: Todos los errores devuelven respuestas JSON
estructuradas con `error` (mensaje legible para humanos), `code`
(identificador legible por máquina) y `details` (errores de validación a
nivel de campo cuando corresponda).
**Integración del Editor de Plantillas Incrustado**: El Editor de Plantillas
de Firma se puede incrustar en tu aplicación usando una biblioteca
JavaScript independiente.
```html
```
version: 01.30.00
contact:
name: API Support
url: https://firma.com/support
servers:
- url: https://api.firma.dev/functions/v1/signing-request-api
description: API de Producción - Recomendada (Actual)
- url: https://api.firma.dev/api/v1
description: API de Producción - Planeada
security:
- ApiKeyAuth: []
tags:
- name: Company
description: Información y configuración de la empresa
- name: Workspaces
description: Operaciones de gestión de espacios de trabajo
- name: Templates
description: Operaciones de gestión de plantillas
- name: Signing Requests
description: Operaciones de solicitudes de firma de documentos
- name: Custom Fields
description: >-
Gestión de definiciones de campos personalizados para espacios de trabajo,
plantillas y solicitudes de firma
- name: Webhooks
description: Configuración y gestión de webhooks
- name: JWT Management
description: Generación y revocación de tokens JWT para plantillas incrustadas
- name: Workspace Settings
description: Configuración y ajustes del espacio de trabajo
- name: Email Domains
description: >-
Configuración y verificación de dominios de correo electrónico para enviar
correos de solicitudes de firma desde dominios personalizados
- name: Email Templates
description: >-
Gestión de plantillas de correo electrónico para personalización de
notificaciones de solicitudes de firma a nivel de espacio de trabajo y de
empresa
- name: Signer Terms
description: >-
Términos de servicio / declaraciones de consentimiento personalizadas del
firmante, a nivel de empresa con anulaciones por espacio de trabajo según
el idioma
paths:
/signing-requests:
get:
tags:
- Signing Requests
summary: Listar Solicitudes de Firma
description: Recupera una lista paginada de solicitudes de firma
operationId: listSigningRequests
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 la solicitud de firma (coincidencia parcial,
sin distinción entre mayúsculas y minúsculas)
- name: status
in: query
schema:
type: string
enum:
- not_sent
- in_progress
- finished
- cancelled
- declined
- deleted
- expired
description: >-
Filtrar por estado de la solicitud de firma. Admite múltiples
valores separados por comas.
**Estados disponibles:**
- `not_sent`: Solicitud creada pero aún no enviada a los firmantes
- `in_progress`: Enviada a los firmantes pero no completada,
cancelada, rechazada ni expirada
- `finished`: Todos los firmantes han completado
- `cancelled`: La solicitud fue cancelada por el remitente
- `declined`: Un firmante rechazó firmar (la solicitud se detiene)
- `deleted`: Registros eliminados de forma parcial (normalmente
ocultos)
- `expired`: Enviada pero pasado el tiempo de expiración (sent_on +
expiration_hours < now)
**Ejemplo:** `?status=in_progress,expired`
**Nota:** El estado `expired` usa filtrado posterior, lo que puede
tener implicaciones de rendimiento en conjuntos de datos grandes.
- name: created_after
in: query
schema:
type: string
format: date-time
description: >-
Filtrar solicitudes de firma creadas después de esta fecha (formato
ISO 8601)
- name: created_before
in: query
schema:
type: string
format: date-time
description: >-
Filtra las solicitudes de firma creadas antes de esta fecha (formato
ISO 8601)
- name: signer_email
in: query
schema:
type: string
description: Filtra por dirección de email del firmante (coincidencia exacta)
- name: signer_name
in: query
schema:
type: string
description: >-
Filtra por nombre del firmante (coincidencia parcial, sin distinguir
mayúsculas/minúsculas)
- name: sort_by
in: query
schema:
type: string
enum:
- name
- created_on
- expiration_hours
- sent_on
- finished_on
default: created_on
description: Campo por el que ordenar
- name: sort_order
in: query
schema:
type: string
enum:
- asc
- desc
default: desc
description: Orden de clasificación
responses:
'200':
description: Solicitudes de firma obtenidas correctamente
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/SigningRequestListResponse'
'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.signingRequests.listSigningRequests();
console.log(response);
components:
schemas:
SigningRequestListResponse:
type: object
description: Lista paginada de solicitudes de firma
properties:
results:
type: array
items:
$ref: '#/components/schemas/SigningRequestListItem'
pagination:
$ref: '#/components/schemas/Pagination'
required:
- results
- pagination
SigningRequestListItem:
type: object
description: >-
Solicitud de firma tal como la devuelve el endpoint LIST (GET
/signing-requests)
properties:
id:
type: string
format: uuid
description: Identificador único de la solicitud de firma
name:
type: string
description: Nombre de la solicitud de firma
maxLength: 255
description:
type: string
nullable: true
description: Descripción de la solicitud de firma
status:
type: string
enum:
- not_sent
- in_progress
- finished
- cancelled
- declined
- deleted
- expired
description: Estado actual de la solicitud de firma
document_url:
type: string
format: uri
description: >-
URL prefirmada al documento PDF. Es una URL firmada de tiempo
limitado para acceso seguro - ver document_url_expires_at para el
tiempo 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 solicitud de firma 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 solicitud de firma para recibir una URL firmada nueva.
page_count:
type: integer
minimum: 1
description: Número de páginas en el documento
expiration_hours:
type: integer
minimum: 1
default: 168
description: >-
Horas hasta que la solicitud de firma expire (por defecto: 168 = 7
días)
expires_at:
type: string
format: date-time
nullable: true
description: >-
Marca de tiempo ISO 8601 de cuándo expira la solicitud de firma. Se
calcula a partir de sent_date + expiration_hours. Es nulo si la
solicitud de firma aún no ha sido enviada o no tiene
expiration_hours configurado.
credit_cost:
type: integer
minimum: 1
default: 1
description: >-
Número de créditos consumidos cuando se envió esta solicitud de
firma. El valor mínimo es 1.
template_id:
type: string
format: uuid
nullable: true
description: ID de la plantilla si se creó a partir de una plantilla
settings:
$ref: '#/components/schemas/SigningRequestSettings'
created_date:
type: string
format: date-time
description: Marca de tiempo de creación
updated_date:
type: string
format: date-time
description: Marca de tiempo de la última actualización
sent_date:
type: string
format: date-time
nullable: true
description: Cuándo se envió la solicitud de firma
finished_date:
type: string
format: date-time
nullable: true
description: Cuándo se completaron todas las firmas
cancelled_date:
type: string
format: date-time
nullable: true
description: Cuándo se canceló la solicitud de firma
declined_date:
type: string
format: date-time
nullable: true
description: Cuándo se rechazó la solicitud de firma
recipients:
type: array
description: Destinatarios de la solicitud de firma (formato simplificado)
items:
$ref: '#/components/schemas/SigningRequestListRecipient'
fields:
type: array
description: Campos de la solicitud de firma con objeto de posición anidado
items:
type: object
properties:
id:
type: string
format: uuid
type:
type: string
enum:
- text
- signature
- date
- checkbox
- dropdown
- radio_buttons
- number
- text_area
- file
- initial
- stamp
- approval_signature
- approval_checkmark
- approval_date
required:
type: boolean
recipient_id:
type: string
format: uuid
nullable: true
variable_name:
type: string
nullable: true
variable_defined_name:
type: string
nullable: true
description: >-
Nombre de campo legible tomado de la definición del campo
personalizado (por ejemplo, 'artist_name'). Solo está presente
para campos vinculados a una definición de campo
personalizado; de lo contrario es nulo.
position:
type: object
properties:
x:
type: number
'y':
type: number
width:
type: number
height:
type: number
value:
type: string
nullable: true
description: Valor final del campo después de firmar
dropdown_options:
nullable: true
oneOf:
- type: array
items:
type: string
- type: object
format_rules:
$ref: '#/components/schemas/DateFormatRules'
nullable: true
validation_rules:
$ref: '#/components/schemas/FieldValidationRules'
required:
- id
- name
- status
- 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.
SigningRequestListRecipient:
type: object
description: >-
Destinatario tal como se devuelve en las respuestas LIST de solicitudes
de firma (formato simplificado)
properties:
id:
type: string
format: uuid
description: Identificador único del destinatario
name:
type: string
description: Nombre completo combinado
email:
type: string
format: email
description: Dirección de correo electrónico del destinatario
designation:
type: string
enum:
- Signer
- Approver
- CC
description: >-
Rol del destinatario. El Firmante firma el documento, el Aprobador
aprueba con campos de aprobación, CC recibe una copia cuando se
completa.
order:
type: integer
minimum: 1
description: Orden de firma
finished_date:
type: string
format: date-time
nullable: true
description: Cuándo este destinatario completó la firma
signature_details:
type: object
nullable: true
description: Detalles sobre la firma del destinatario
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.
````