> ## 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. # Crear Solicitud de Firma > Crea una nueva solicitud de firma ya sea a partir de un documento PDF (basado en documento) o a partir de una plantilla existente (basado en plantilla). Para la creación basada en documento, allow_editing_before_sending se establece automáticamente en true. Para la creación basada en plantilla, las propiedades se heredan de la plantilla y se pueden sobrescribir. **Patrón de ID Temporal**: Para la creación basada en documento, puedes referenciar destinatarios antes de que se creen usando IDs temporales (formato: 'temp_X' donde X es cualquier identificador, por ejemplo, 'temp_1', 'temp_alice'). Usa estos IDs temporales en recipient.id, field.recipient_id y reminder.recipient_id. La API valida todas las referencias y mapea automáticamente los IDs temporales a UUID reales después de que se crean los destinatarios. La respuesta contiene solo UUID reales. **Validación de ID Temporal**: Los IDs temporales deben comenzar con 'temp_', ser únicos entre todos los destinatarios de la solicitud, y todas las referencias de field/reminder deben apuntar a destinatarios definidos en la misma solicitud. Un formato inválido, IDs duplicados o referencias de destinatario faltantes devuelven un error 400 con mensajes de validación detallados. ## OpenAPI ````yaml api-reference/v01.37.00/openapi-v01.37.00.es.json post /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 ``` **Encabezado X-Firma-Deprecation**: Algunas operaciones de creación de sellos y de actualización de imagen devuelven un encabezado de respuesta `X-Firma-Deprecation` cuando se invocan a través del edge gateway, indicando que la operación debe realizarse en el host principal de la API. version: 01.37.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: Organization Seals description: >- Gestión de sellos de organización: crear, actualizar, revocar y borrar sellos aplicados a solicitudes de firma - 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: post: tags: - Signing Requests summary: Crear Solicitud de Firma description: >- Crea una nueva solicitud de firma ya sea a partir de un documento PDF (basado en documento) o a partir de una plantilla existente (basado en plantilla). Para la creación basada en documento, allow_editing_before_sending se establece automáticamente en true. Para la creación basada en plantilla, las propiedades se heredan de la plantilla y se pueden sobrescribir. **Patrón de ID Temporal**: Para la creación basada en documento, puedes referenciar destinatarios antes de que se creen usando IDs temporales (formato: 'temp_X' donde X es cualquier identificador, por ejemplo, 'temp_1', 'temp_alice'). Usa estos IDs temporales en recipient.id, field.recipient_id y reminder.recipient_id. La API valida todas las referencias y mapea automáticamente los IDs temporales a UUID reales después de que se crean los destinatarios. La respuesta contiene solo UUID reales. **Validación de ID Temporal**: Los IDs temporales deben comenzar con 'temp_', ser únicos entre todos los destinatarios de la solicitud, y todas las referencias de field/reminder deben apuntar a destinatarios definidos en la misma solicitud. Un formato inválido, IDs duplicados o referencias de destinatario faltantes devuelven un error 400 con mensajes de validación detallados. operationId: createSigningRequest requestBody: required: true content: application/json: schema: oneOf: - type: object required: - document description: Crear una Solicitud de Firma a partir de un documento PDF properties: document: type: string format: byte description: >- Documento PDF o DOCX codificado en base64. Los archivos DOCX se convierten automáticamente a PDF. El número de páginas se extrae automáticamente. Para documentos de más de 5 MB, usa POST /documents y pasa el document_id en su lugar. name: type: string maxLength: 255 description: Nombre para la Solicitud de Firma description: type: string description: Descripción para la Solicitud de Firma expiration_hours: type: integer minimum: 1 default: 168 description: >- Horas hasta que expire la Solicitud de Firma (predeterminado: 168 = 7 días) recipients: type: array items: $ref: '#/components/schemas/Recipient' description: >- Destinatarios para la Solicitud de Firma. Usa IDs temporales (por ejemplo, 'temp_1') en el campo id para hacer referencia a los destinatarios en fields/reminders. fields: type: array items: $ref: '#/components/schemas/Field' description: >- Campos para colocar en el documento. Usa recipient_id para asignar campos a los destinatarios. anchor_tags: type: array maxItems: 100 items: $ref: '#/components/schemas/AnchorTag' description: >- Etiquetas de anclaje para la colocación automática de campos. Se localizan marcadores de texto en el PDF y se convierten en campos posicionados. El texto de anclaje se elimina del PDF después del procesamiento. Los campos creados a partir de etiquetas de anclaje se añaden junto con cualquier campo especificado manualmente. Solo está disponible para la creación basada en documento (no basada en Plantilla). reminders: type: array items: $ref: '#/components/schemas/SigningRequestReminder' description: Recordatorios para enviar a los destinatarios settings: $ref: '#/components/schemas/SigningRequestSettings' description: Configuración de la Solicitud de Firma language: type: string nullable: true enum: - en - es - it - pt - fr - de - el - ru - pl - cs - sv - nl - ro - nb description: >- Idioma opcional de los correos para esta solicitud de firma. Cuando se establece, todos los correos dirigidos al firmante (y el formato de fecha) lo utilizan. Omítelo o usa null para volver al idioma predeterminado del espacio de trabajo y luego de la empresa (sin cambios de comportamiento). completion_title: type: string nullable: true description: >- Encabezado mostrado en la página de finalización tras la firma. Hereda del espacio de trabajo y después de la empresa cuando se omite o es null. maxLength: 200 completion_message: type: string nullable: true description: >- Texto principal mostrado en la página de finalización tras la firma. Hereda del espacio de trabajo y después de la empresa cuando se omite o es null. maxLength: 1000 completion_redirect_url: type: string format: uri nullable: true description: >- URL a la que se redirige al firmante desde la página de finalización. Debe usar https:// (http://localhost y http://127.0.0.1 también se aceptan en solicitudes de firma en modo de prueba). Hereda del espacio de trabajo y después de la empresa cuando se omite o es null. maxLength: 2000 completion_redirect_delay: type: integer nullable: true description: >- Segundos que espera la página de finalización antes de redirigir (0 redirige de inmediato). Solo se aplica cuando se resuelve una URL de redirección; la página usa 5 segundos cuando ningún nivel define un retraso. Hereda del espacio de trabajo y después de la empresa cuando se omite o es null. minimum: 0 maximum: 30 seal_participants: type: array items: $ref: '#/components/schemas/SealParticipantInput' description: >- Participantes de sello de organización a incluir en la secuencia de firma - type: object required: - template_id description: >- Crear una Solicitud de Firma a partir de una Plantilla. Admite actualizaciones parciales tanto para destinatarios como para campos. properties: template_id: type: string format: uuid description: >- ID de la Plantilla a partir de la cual crear la Solicitud de Firma. El documento, los campos y los destinatarios predeterminados se copiarán de la Plantilla. name: type: string maxLength: 255 description: >- Nombre personalizado para la Solicitud de Firma (usa el nombre de la Plantilla de forma predeterminada si no se proporciona) description: type: string description: >- Descripción personalizada (usa la descripción de la Plantilla de forma predeterminada si no se proporciona) expiration_hours: type: integer minimum: 1 description: Sobrescribir las horas de expiración de la Plantilla recipients: type: array items: $ref: '#/components/schemas/Recipient' description: >- Sobrescrituras de destinatarios opcionales. Usa template_user_id (preferido) u order (alternativa) para hacer coincidir con los usuarios de la Plantilla. Solo se puede actualizar la información del usuario (first_name, last_name, email, phone_number, campos de dirección, title, company); order y designation siempre se heredan de la Plantilla. Los destinatarios no proporcionados usarán los valores predeterminados de la Plantilla. fields: type: array items: $ref: '#/components/schemas/Field' description: >- Sobrescrituras opcionales de campos para actualizaciones parciales. Usa template_field_id (preferido) o variable_name (alternativa) para identificar los campos de la plantilla. Solo las propiedades proporcionadas sobrescriben los valores predeterminados de la plantilla. Propiedades de sobrescritura admitidas: type, required, position, read_only, read_only_value, format_rules, validation_rules, dropdown_options, date_default, date_signing_default, multi_group_id. Los campos que no coincidan se ignoran. Si se omite el array fields, se usan todos los campos de la plantilla tal cual. settings: $ref: '#/components/schemas/SigningRequestSettings' description: Sobrescribe la configuración de la plantilla language: type: string nullable: true enum: - en - es - it - pt - fr - de - el - ru - pl - cs - sv - nl - ro - nb description: >- Idioma opcional de los correos para esta solicitud de firma. Cuando se establece, todos los correos dirigidos al firmante (y el formato de fecha) lo utilizan. Omítelo o usa null para volver al idioma predeterminado del espacio de trabajo y luego de la empresa (sin cambios de comportamiento). completion_title: type: string nullable: true description: >- Encabezado mostrado en la página de finalización tras la firma. Recurre al valor de la plantilla y después a los valores predeterminados del espacio de trabajo y la empresa cuando se omite o es null. maxLength: 200 completion_message: type: string nullable: true description: >- Texto principal mostrado en la página de finalización tras la firma. Recurre al valor de la plantilla y después a los valores predeterminados del espacio de trabajo y la empresa cuando se omite o es null. maxLength: 1000 completion_redirect_url: type: string format: uri nullable: true description: >- URL a la que se redirige al firmante desde la página de finalización. Debe usar https:// (http://localhost y http://127.0.0.1 también se aceptan en solicitudes de firma en modo de prueba). Recurre al valor de la plantilla y después a los valores predeterminados del espacio de trabajo y la empresa cuando se omite o es null. maxLength: 2000 completion_redirect_delay: type: integer nullable: true description: >- Segundos que espera la página de finalización antes de redirigir (0 redirige de inmediato). Solo se aplica cuando se resuelve una URL de redirección; la página usa 5 segundos cuando ningún nivel define un retraso. Recurre al valor de la plantilla y después a los valores predeterminados del espacio de trabajo y la empresa cuando se omite o es null. minimum: 0 maximum: 30 seal_participants: type: array items: $ref: '#/components/schemas/SealParticipantInput' description: >- Participantes de sello de organización a incluir en la secuencia de firma example: template_id: 21424147-11c0-43d5-ac5f-a1f7001b5607 name: Contract for Client X recipients: - template_user_id: template-user-uuid-1 first_name: Toni last_name: Campins email: acampins@cocodin.com fields: - template_field_id: field-uuid-1 read_only: true read_only_value: 'Contract #12345' - variable_name: company_name read_only_value: Acme Corporation properties: seal_participants: type: array items: $ref: '#/components/schemas/SealParticipantInput' description: >- Participantes de sello de organización a incluir en la secuencia de firma fields: type: array items: allOf: - $ref: '#/components/schemas/Field' - type: object properties: seal_participant_temp_id: type: string description: >- ID temporal del participante de sello al que está asignado este campo (coincide con temp_id en el array seal_participants) properties: seal_participant_temp_id: type: string description: >- ID temporal del participante de sello al que está asignado este campo (coincide con temp_id en el array seal_participants) description: Campos a colocar en el documento examples: update-properties: summary: Actualizar propiedades value: name: Updated Contract Name expiration_hours: 72 update-recipient: summary: Actualizar un solo destinatario 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: Añadir nuevo destinatario value: recipient: first_name: Jane last_name: Doe email: jane@example.com designation: Signer order: 2 add-date-field: summary: Añadir campo de fecha con formato value: field: type: date position: x: 70 'y': 45 width: 15 height: 3 page_number: 1 required: true recipient_id: rec123-e89b-12d3-a456-426614174000 date_signing_default: true format_rules: dateFormat: MMMM dd, yyyy add-read-only-static-field: summary: Añadir campo de solo lectura con valor estático description: >- Crea un campo de texto que muestra un valor fijo que el firmante no puede editar value: field: type: text position: x: 15 'y': 20 width: 40 height: 3 page_number: 1 required: false recipient_id: rec123-e89b-12d3-a456-426614174000 read_only: true read_only_value: 'Contract #12345 - Acme Corporation' add-read-only-prefilled-field: summary: Añadir campo de solo lectura con datos del destinatario description: >- Crea un campo de texto que se autocompleta con el correo electrónico del destinatario (el firmante no puede editarlo) value: field: type: text position: x: 15 'y': 30 width: 30 height: 3 page_number: 1 required: false recipient_id: rec123-e89b-12d3-a456-426614174000 read_only: true prefilled_data: email responses: '201': description: >- Solicitud de firma creada exitosamente. La respuesta puede incluir advertencias no bloqueantes de correo electrónico o de etiquetas de anclaje. 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/SigningRequestCreateResponse' '400': $ref: '#/components/responses/ValidationError' description: >- Entrada inválida: debes proporcionar 'document' o 'template_id', no ambos. El documento debe ser un PDF válido codificado en base64 de menos de 20MB. La plantilla debe existir y pertenecer al espacio de trabajo. '401': $ref: '#/components/responses/UnauthorizedError' '404': description: Plantilla no encontrada o no pertenece al espacio de trabajo content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/RateLimitError' '503': description: >- El procesamiento de etiquetas de anclaje está deshabilitado en la ruta de respaldo del edge. Reintenta a través de la ruta principal de la API. content: application/json: schema: type: object required: - error - code properties: error: type: string code: type: string enum: - ANCHOR_DISABLED_EDGE 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.createSigningRequest({ template_id: "template_id", name: "Updated Contract Name", expiration_hours: 72 }); console.log(response); components: schemas: 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 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 }. Los campos con texto (text, textarea, email, name, phone, company, title, number, dropdown, url, date) aceptan además una propiedad opcional fontSize (entero en px, 8-48, con límites) — consulta TextFormatRules. 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' seal_participant_temp_id: type: string nullable: true description: >- ID temporal del participante de sello al que está asignado este campo (coincide con temp_id en el array seal_participants). Se usa durante la creación para vincular campos a participantes de sello definidos en la misma solicitud. AnchorTag: type: object additionalProperties: false required: - anchor_string - type - recipient_id description: >- Definición de etiqueta de anclaje para la colocación automática de campos. Las etiquetas de anclaje son marcadores de texto incrustados en un documento PDF (por ejemplo, '{{SIGN_HERE}}') que se localizan automáticamente y se convierten en campos posicionados. El texto del anclaje se elimina del PDF después del procesamiento de forma predeterminada. properties: anchor_string: type: string minLength: 1 maxLength: 200 description: >- Cadena de texto a buscar en el documento PDF. Los patrones comunes incluyen '{{SIGN_HERE}}', '{{DATE}}', etc. example: '{{SIGN_HERE}}' type: type: string enum: - signature - initial - initials - text - date - checkbox - radio_buttons - radio - dropdown - textarea - text_area - url - approval_signature - approval_checkmark - approval_date description: Tipo de campo a colocar en la ubicación del anclaje recipient_id: oneOf: - type: integer - type: string description: >- ID del destinatario asignado a este campo. Usa un ID temporal (por ejemplo, 'temp_1') para la creación basada en documentos, o un número entero de orden para la basada en plantillas. example: temp_1 x_offset: type: number description: >- Desplazamiento horizontal desde la posición del anclaje. Las unidades se determinan mediante offset_units (predeterminado: porcentaje del ancho de página). default: 0 y_offset: type: number description: >- Desplazamiento vertical desde la posición del anclaje. Las unidades se determinan mediante offset_units (predeterminado: porcentaje del alto de página). default: 0 offset_units: type: string enum: - percent - pixels default: percent description: >- Tipo de unidad para x_offset y y_offset. 'percent' = porcentaje de las dimensiones de la página, 'pixels' = puntos PDF (72 DPI). width: type: number minimum: 0 exclusiveMinimum: true description: >- Ancho del campo como porcentaje del ancho de página. Los valores predeterminados varían según el tipo de campo (por ejemplo, signature=25, text=20, checkbox=3). height: type: number minimum: 0 exclusiveMinimum: true description: >- Alto del campo como porcentaje del alto de página. Los valores predeterminados varían según el tipo de campo (por ejemplo, signature=5, text=3, checkbox=3). case_sensitive: type: boolean default: false description: >- Indica si la coincidencia de la cadena de anclaje distingue entre mayúsculas y minúsculas match_whole_word: type: boolean default: true description: >- Indica si se deben coincidir solo palabras completas (delimitadas por caracteres que no son de palabra) ignore_if_not_present: type: boolean default: false description: >- Si es true, omite este anclaje sin generar un error cuando no se encuentra en el documento. Si es false (predeterminado), un anclaje faltante provoca un error de validación. occurrence: type: integer minimum: 0 maximum: 1000 default: 0 description: >- Qué ocurrencia usar para colocar un campo. 0 = todas las ocurrencias (predeterminado), 1 = solo la primera, 2 = solo la segunda, etc. remove_anchor_text: type: boolean default: true description: >- Si se debe eliminar el texto del anclaje usando geometría de glifos corregida y eliminación de texto a nivel de subpíxel. Por defecto true. add_white_background: type: boolean default: false description: >- Si se debe dibujar un fondo blanco sobre todo el rectángulo del campo resuelto. Es independiente de la eliminación del texto del anclaje. required: type: boolean default: true description: Indica si el campo debe ser completado por el firmante read_only: type: boolean default: false description: Indica si el campo es de solo lectura (prellenado) read_only_value: type: string nullable: true maxLength: 10000 description: Valor estático para campos de solo lectura variable_name: type: string nullable: true maxLength: 255 description: Nombre de variable para el campo variable_defined_name: type: string maxLength: 100 nullable: true description: >- Nombre legible de la definición de campo personalizado. Se puede usar como alternativa a variable_name para apuntar a campos en la creación basada en plantillas. background_color: type: string nullable: true pattern: ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$ description: Color de fondo en hexadecimal (por ejemplo, '#FFFDE7') example: '#FFFDE7' font_size: type: integer minimum: 8 maximum: 48 description: >- Tamaño de fuente inicial/máximo opcional en píxeles para tipos de campo con texto, almacenado en el campo resuelto como format_rules.fontSize (consulta TextFormatRules). El texto se reduce automáticamente para ajustarse al recuadro del campo. Omítelo para el dimensionado automático. Los valores fuera de 8-48 se limitan a ese rango; los valores no numéricos se ignoran. example: 12 dropdown_options: description: Opciones para campos desplegables oneOf: - type: array items: type: string - type: object date_default: type: string nullable: true maxLength: 50 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 nullable: true maxLength: 255 description: ID de grupo para vincular campos de casilla de verificación/radio 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 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. SealParticipantInput: type: object required: - seal_id - order description: >- Asignación de participante de sello para una solicitud de firma o plantilla. properties: seal_id: type: string format: uuid description: ID del sello de organización a aplicar order: type: integer minimum: 1 description: Posición en la secuencia de firma temp_id: type: string description: >- ID temporal para referenciar en las asignaciones de campos dentro de la misma solicitud SigningRequestCreateResponse: type: object description: >- Solicitud de firma tal como la devuelven los endpoints CREATE (POST /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: - draft description: >- El status siempre es 'draft' para solicitudes de firma recién creadas document_url: type: string format: uri description: URL prefirmada al documento PDF 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) 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 recipients: type: array description: Destinatarios de la solicitud de firma items: $ref: '#/components/schemas/SigningRequestCreateRecipient' fields: type: array description: Campos de la solicitud de firma con valores de posición planos items: $ref: '#/components/schemas/SigningRequestCreateField' warnings: type: array items: type: string description: >- Advertencias opcionales no bloqueantes, incluidos formatos de correo electrónico de destinatario inusuales, propiedades de etiquetas de anclaje desconocidas durante la ventana de compatibilidad y advertencias de procesamiento de anclajes. seal_participants: type: array description: >- Participantes de sello de organización en el orden de firma. Vacío cuando la solicitud no tiene sellos. items: $ref: '#/components/schemas/SealParticipant' required: - id - name - status Error: type: object properties: error: type: string description: Mensaje de error legible para humanos code: type: string description: >- Código de error legible por máquina. Códigos relacionados con sellos: SEALS_DISABLED, SEAL_ALREADY_REVOKED, SEAL_CREATION_DISABLED_EDGE, SEAL_ERASE_NOT_ELIGIBLE, SEAL_IMAGE_INVALID, SEAL_MUTATION_NOT_ALLOWED, SEAL_NOT_FOUND, SEAL_ORDER_COLLISION, SEAL_PAUSED, SEAL_SCOPE_FORBIDDEN, SEAL_UNAVAILABLE errors: type: array description: >- Todos los errores de validación cuando se notifican varios fallos a la vez. El error de nivel superior repite el primer elemento por compatibilidad con versiones anteriores. items: type: object required: - message properties: message: type: string message: type: string description: Descripción detallada del error details: type: object description: Detalles adicionales del error additionalProperties: true required: - error description: >- Códigos de error de sellos de organización: SEALS_DISABLED, SEAL_ALREADY_REVOKED, SEAL_CREATION_DISABLED_EDGE, SEAL_ERASE_NOT_ELIGIBLE, SEAL_IMAGE_INVALID, SEAL_MUTATION_NOT_ALLOWED, SEAL_NOT_FOUND, SEAL_ORDER_COLLISION, SEAL_PAUSED, SEAL_SCOPE_FORBIDDEN, SEAL_UNAVAILABLE 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 fontSize: type: integer minimum: 8 maximum: 48 description: >- Tamaño de fuente inicial/máximo opcional en píxeles para el valor del campo renderizado. El texto se reduce automáticamente para ajustarse al recuadro del campo. Omítelo para el dimensionado automático. Los valores fuera de 8-48 se limitan a ese rango. 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 SigningRequestCreateRecipient: type: object description: >- Destinatario tal como se devuelve en las respuestas CREATE de solicitudes de firma properties: id: type: string format: uuid description: Identificador único del destinatario first_name: type: string nullable: true description: Nombre del destinatario last_name: type: string nullable: true description: Apellido del destinatario name: type: string nullable: true description: >- Nombre completo combinado (construido automáticamente a partir de first_name + last_name) 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 phone_number: type: string nullable: true description: Número de teléfono del destinatario street_address: type: string nullable: true description: Dirección postal city: type: string nullable: true description: Ciudad state_province: type: string nullable: true description: Estado o provincia postal_code: type: string nullable: true description: Código postal country: type: string nullable: true description: País title: type: string nullable: true description: Puesto de trabajo company: type: string nullable: true description: Nombre de la empresa custom_fields: type: object nullable: true description: Pares clave-valor personalizados finished_date: type: string format: date-time nullable: true description: Cuándo este destinatario completó la firma required: - first_name - email - designation SigningRequestCreateField: type: object description: >- Campo tal como se devuelve en las respuestas CREATE de solicitudes de firma (posición plana, estilo base de datos) 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 recipient_id: type: string format: uuid nullable: true description: ID del destinatario asignado page_number: type: integer minimum: 1 description: Número de página (indexado desde 1) x_position: type: number description: Coordenada X como porcentaje (0-100) y_position: type: number description: Coordenada Y como porcentaje (0-100) width: type: number description: Ancho como porcentaje (0-100) height: type: number description: Alto como porcentaje (0-100) required: type: boolean description: Indica si el campo es obligatorio read_only: type: boolean description: Indica si este campo es de solo lectura read_only_value: type: string nullable: true description: Valor estático para campos de solo lectura variable_name: type: string nullable: true description: Nombre de variable para el mapeo de datos prellenados 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. dropdown_options: nullable: true description: Opciones para campos desplegables oneOf: - type: array items: type: string - type: object format_rules: type: object nullable: true description: Reglas de formato (por ejemplo, formato de fecha) validation_rules: type: object nullable: true description: Reglas de validación para el campo date_signing_default: type: boolean description: Si se debe usar la fecha de firma como valor predeterminado final_value: type: string nullable: true description: Valor prellenado o final del campo required: - type - recipient_id - page_number SealParticipant: type: object description: Participante de sello en una solicitud de firma o plantilla. properties: id: type: string format: uuid organization_seals_id: type: string format: uuid order: type: integer minimum: 1 deleted: type: integer enum: - 0 - 1 created_at: type: string format: date-time updated_at: type: string format: date-time 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: 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 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. ````