> ## 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.39.01/openapi-v01.39.01.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. **Documentos múltiples (API 01.39.00, requiere habilitación)**: una plantilla o solicitud de firma puede contener hasta 20 documentos. Las rutas del subrecurso `/documents` y las claves `documents`, `documents_version` y `documents_layout_version` solo se ofrecen a las empresas habilitadas para documentos múltiples; para cualquier otra empresa, las rutas responden `404 NOT_FOUND` y las claves no aparecen. **Sellos de plantilla al crear (API 01.39.01)**: crear una solicitud de firma a partir de una plantilla con `POST /signing-requests` o `POST /signing-requests/create-and-send` ahora hereda los participantes de sello de la plantilla, y los campos de la plantilla que les pertenecen, cuando `seal_participants` está ausente o es `null`. Esto cambia el comportamiento de v1 sin incrementar la versión; envía `seal_participants: []` para crear la solicitud sin sellos. `POST /templates/{id}/duplicate` también traslada los participantes de sello de la plantilla; consulta esa operación para ver en qué se diferencia para las empresas habilitadas para documentos múltiples. `GET /templates/{id}` devuelve `seal_participants`, y `POST /templates` responde `warnings` cuando su cuerpo contiene claves que ignora. version: 01.39.01 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: allOf: - $ref: '#/components/schemas/Field' - type: object properties: seal_attribute: type: string enum: - display_name - signatory_title - null nullable: true description: >- Qué texto muestra un campo de texto propio de un sello: el nombre visible del sello (`display_name`) o el cargo del firmante (`signatory_title`). Se aplica a un campo que pertenece a un participante de sello (un campo con `seal_participant_temp_id`, o un campo de plantilla que pertenece a un participante de sello) y se ignora en cualquier otro campo. Se almacena en el campo como `format_rules.sealAttribute`; en una solicitud basada en plantilla reemplaza el `sealAttribute` que lleva el campo de la plantilla y deja sin cambios el resto de `format_rules` del campo de la plantilla. Cualquier otro valor responde 400 `VALIDATION_ERROR`; esta comprobación se aplica a todos los campos del cuerpo, los posea o no un sello. 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 - ca 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. `null` se trata como una clave ausente; cualquier otro valor que no sea un array responde 400 `VALIDATION_ERROR`. Los valores `order` de los sellos y los valores `order` de los destinatarios deben formar una única secuencia contigua que empiece en 1: un hueco responde 400 `INVALID_SIGNING_ORDER`, dos de ellos (destinatarios o sellos) que compartan un `order` responden 400 `SEAL_ORDER_COLLISION`, y todo destinatario necesita un `order` cuando hay un sello. Un array no vacío requiere que los sellos de organización estén habilitados; en caso contrario la llamada responde 503 `SEALS_DISABLED`. nullable: true - 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. **Sellos.** Si la plantilla tiene participantes de sello y `seal_participants` está ausente o es `null`, la solicitud los hereda junto con los campos de la plantilla que les pertenecen. Un array, incluido `[]`, los reemplaza: los participantes de sello de la plantilla y sus campos no se copian. Cualquier otro tipo responde 400 `VALIDATION_ERROR`. Un sello conservado y los destinatarios se renumeran juntos en una única secuencia de orden contigua que mantiene el orden relativo de la plantilla. Cuando la plantilla no tiene destinatarios propios, los sellos heredados se colocan después de los destinatarios de la solicitud. Un sello de plantilla sigue la versión actual de su linaje: la solicitud adjunta la versión actual, no la versión a la que apunta la plantilla. Si esa versión actual está revocada o borrada, o el linaje no tiene versión actual, la llamada responde 409 `SEAL_UNAVAILABLE` y no crea nada. Un sello de plantilla que la empresa de la clave API no puede ver, o cuya versión actual está limitada a un espacio de trabajo distinto del de la clave API, no se copia y tampoco sus campos; la solicitud se crea igualmente y `seal_participants` lista el sello como una entrada descartada (`dropped: true`). Si se conservara un sello mientras los sellos de organización no están habilitados, la llamada responde 503 `SEALS_DISABLED`. 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. Los destinatarios con designation CC nunca se hacen coincidir con usuarios de la plantilla; se añaden como destinatarios en CC. Los destinatarios en CC de la plantilla se copian en la solicitud de firma, omitiendo aquellos cuyo email (sin distinción entre mayúsculas y minúsculas) ya figura en un destinatario en CC de la solicitud. fields: type: array items: allOf: - $ref: '#/components/schemas/Field' - type: object properties: seal_attribute: type: string enum: - display_name - signatory_title - null nullable: true description: >- Qué texto muestra un campo de texto propio de un sello: el nombre visible del sello (`display_name`) o el cargo del firmante (`signatory_title`). Se aplica a un campo que pertenece a un participante de sello (un campo con `seal_participant_temp_id`, o un campo de plantilla que pertenece a un participante de sello) y se ignora en cualquier otro campo. Se almacena en el campo como `format_rules.sealAttribute`; en una solicitud basada en plantilla reemplaza el `sealAttribute` que lleva el campo de la plantilla y deja sin cambios el resto de `format_rules` del campo de la plantilla. Cualquier otro valor responde 400 `VALIDATION_ERROR`; esta comprobación se aplica a todos los campos del cuerpo, los posea o no un sello. 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 - ca 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 para la nueva solicitud de firma: con `template_id`, omite la clave o envía `null` para heredar los sellos de la plantilla, envía `[]` para no tener sellos, o envía un array para reemplazarlos. Un sello de plantilla reemplazado y sus campos no se copian. Cualquier otro tipo responde 400 `VALIDATION_ERROR`. En una solicitud basada en plantilla, los órdenes de los sellos y los órdenes de los destinatarios se renumeran juntos en una única secuencia contigua, tanto si los sellos se heredan como si se envían en el array. Un array no vacío, o un sello heredado que se conservaría, requiere que los sellos de organización estén habilitados; en caso contrario la llamada responde 503 `SEALS_DISABLED`. nullable: true 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 - type: object required: - document_ids description: >- Crear una solicitud de firma a partir de varios documentos subidos (multidocumento, requiere habilitación) properties: document_ids: type: array minItems: 1 maxItems: 20 items: type: string format: uuid description: >- Ids de subida temporal de POST /documents, en el orden de los documentos, para crear una solicitud de firma multidocumento (requiere habilitación). Exactamente uno de document, document_id, document_ids o template_id (`400 CONFLICTING_DOCUMENT_SOURCE`); un id repetido responde `400 DUPLICATE_DOCUMENT_ID`, más de 20 `400 MAX_DOCUMENTS_EXCEEDED`, una subida desconocida o caducada `400 DOCUMENT_UPLOAD_NOT_FOUND`, un conjunto de más de 100 MB `413 DOCUMENT_SET_TOO_LARGE`; más de un id para una empresa no habilitada responde `409 MULTI_DOCUMENT_READ_ONLY`. 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: allOf: - $ref: '#/components/schemas/Field' - type: object properties: seal_attribute: type: string enum: - display_name - signatory_title - null nullable: true description: >- Qué texto muestra un campo de texto propio de un sello: el nombre visible del sello (`display_name`) o el cargo del firmante (`signatory_title`). Se aplica a un campo que pertenece a un participante de sello (un campo con `seal_participant_temp_id`, o un campo de plantilla que pertenece a un participante de sello) y se ignora en cualquier otro campo. Se almacena en el campo como `format_rules.sealAttribute`; en una solicitud basada en plantilla reemplaza el `sealAttribute` que lleva el campo de la plantilla y deja sin cambios el resto de `format_rules` del campo de la plantilla. Cualquier otro valor responde 400 `VALIDATION_ERROR`; esta comprobación se aplica a todos los campos del cuerpo, los posea o no un sello. 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 - ca 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. `null` se trata como una clave ausente; cualquier otro valor que no sea un array responde 400 `VALIDATION_ERROR`. Los valores `order` de los sellos y los valores `order` de los destinatarios deben formar una única secuencia contigua que empiece en 1: un hueco responde 400 `INVALID_SIGNING_ORDER`, dos de ellos (destinatarios o sellos) que compartan un `order` responden 400 `SEAL_ORDER_COLLISION`, y todo destinatario necesita un `order` cuando hay un sello. Un array no vacío requiere que los sellos de organización estén habilitados; en caso contrario la llamada responde 503 `SEALS_DISABLED`. nullable: true properties: seal_participants: type: array items: $ref: '#/components/schemas/SealParticipantInput' description: >- Participantes de sello de organización para la nueva solicitud de firma: con `template_id`, omite la clave o envía `null` para heredar los sellos de la plantilla, envía `[]` para no tener sellos, o envía un array para reemplazarlos. Un sello de plantilla reemplazado y sus campos no se copian. Cualquier otro tipo responde 400 `VALIDATION_ERROR`. En una solicitud basada en plantilla, los órdenes de los sellos y los órdenes de los destinatarios se renumeran juntos en una única secuencia contigua, tanto si los sellos se heredan como si se envían en el array. Un array no vacío, o un sello heredado que se conservaría, requiere que los sellos de organización estén habilitados; en caso contrario la llamada responde 503 `SEALS_DISABLED`. nullable: true 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) seal_attribute: type: string enum: - display_name - signatory_title - null nullable: true description: >- Qué texto muestra un campo de texto propio de un sello: el nombre visible del sello (`display_name`) o el cargo del firmante (`signatory_title`). Se aplica a un campo que pertenece a un participante de sello (un campo con `seal_participant_temp_id`, o un campo de plantilla que pertenece a un participante de sello) y se ignora en cualquier otro campo. Se almacena en el campo como `format_rules.sealAttribute`; en una solicitud basada en plantilla reemplaza el `sealAttribute` que lleva el campo de la plantilla y deja sin cambios el resto de `format_rules` del campo de la plantilla. Cualquier otro valor responde 400 `VALIDATION_ERROR`; esta comprobación se aplica a todos los campos del cuerpo, los posea o no un sello. 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) seal_attribute: type: string enum: - display_name - signatory_title - null nullable: true description: >- Qué texto muestra un campo de texto propio de un sello: el nombre visible del sello (`display_name`) o el cargo del firmante (`signatory_title`). Se aplica a un campo que pertenece a un participante de sello (un campo con `seal_participant_temp_id`, o un campo de plantilla que pertenece a un participante de sello) y se ignora en cualquier otro campo. Se almacena en el campo como `format_rules.sealAttribute`; en una solicitud basada en plantilla reemplaza el `sealAttribute` que lleva el campo de la plantilla y deja sin cambios el resto de `format_rules` del campo de la plantilla. Cualquier otro valor responde 400 `VALIDATION_ERROR`; esta comprobación se aplica a todos los campos del cuerpo, los posea o no un sello. 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': 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 6 MB de carga útil de la petición (~4,5 MB sin codificar). Multidocumento: `CONFLICTING_DOCUMENT_SOURCE`, `DUPLICATE_DOCUMENT_ID`, `MAX_DOCUMENTS_EXCEEDED`, `DOCUMENT_UPLOAD_NOT_FOUND`, `ANCHOR_DOCUMENT_REQUIRED`. Sellos de organización: `VALIDATION_ERROR` cuando `seal_participants` no es ni un array ni `null`, cuando una de sus entradas no tiene `temp_id`, repite un `temp_id` o tiene un `order` que no es un entero positivo, o cuando el `seal_attribute` de un campo no es `display_name`, `signatory_title` ni `null`; `SEAL_UNAVAILABLE` cuando una entrada omite `seal_id` y ni el espacio de trabajo ni la empresa tienen un sello predeterminado activo; en una solicitud basada en documento con participantes de sello, `INVALID_SIGNING_ORDER` cuando un destinatario no tiene `order` o los destinatarios y los sellos no forman una única secuencia que empiece en 1, y `SEAL_ORDER_COLLISION` cuando dos de ellos (destinatarios o sellos) comparten un `order`. 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 '401': $ref: '#/components/responses/UnauthorizedError' '403': description: >- La plantilla no está en el espacio de trabajo de la clave API (`INVALID_TEMPLATE`). content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- No se encontró la plantilla; una plantilla fuera del espacio de trabajo de la clave API también puede responder 404 en lugar de 403. Un sello nombrado en `seal_participants` no existe, pertenece a otra empresa o está limitado a otro espacio de trabajo (`NOT_FOUND`). content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- Conflicto: `SEAL_UNAVAILABLE` (un sello nombrado en `seal_participants` está revocado o borrado, o no es la versión actual de su linaje; o la versión actual de un sello de plantilla heredado está revocada o borrada, o ese sello no tiene versión actual), `MULTI_DOCUMENT_READ_ONLY`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, `DOCUMENT_SET_DISPATCH_STALE` content: application/json: schema: anyOf: - $ref: '#/components/schemas/MultiDocumentError' - allOf: - $ref: '#/components/schemas/Error' - type: object required: - error - code properties: code: type: string enum: - SEAL_UNAVAILABLE '413': description: DOCUMENT_SET_TOO_LARGE content: application/json: schema: $ref: '#/components/schemas/MultiDocumentError' '429': $ref: '#/components/responses/RateLimitError' '503': description: >- El procesamiento de etiquetas de anclaje está deshabilitado en la ruta perimetral de respaldo (`ANCHOR_DISABLED_EDGE`): reintenta a través de la ruta principal de la API. O los sellos de organización no están habilitados y `seal_participants` es un array no vacío (se responde antes de comprobar sus entradas) o la herencia de la plantilla conserva al menos un sello (`SEALS_DISABLED`). content: application/json: schema: type: object required: - error - code properties: error: type: string code: type: string enum: - ANCHOR_DISABLED_EDGE - SEALS_DISABLED 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. Un destinatario con designation CC nunca se hace coincidir con un usuario de la plantilla; se añade como destinatario en CC, y los destinatarios en CC de la plantilla se copian en la solicitud de firma, omitiendo aquellos cuyo email (sin distinción entre mayúsculas y minúsculas) ya figura en un destinatario en CC de la solicitud. **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. Un destinatario existente no puede cambiarse entre CC y Firmante/Aprobador (400); elimínelo y vuelva a crearlo. 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. No se usa para destinatarios en CC, que nunca se hacen coincidir con un usuario de 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 document_index: type: integer minimum: 1 description: >- Índice (empezando en 1) dentro de `document_ids` del documento en el que se busca esta etiqueta. Opcional con un solo documento (valor predeterminado 1); obligatorio con más de uno (`400 ANCHOR_DOCUMENT_REQUIRED`); un valor fuera de rango responde `400 VALIDATION_ERROR`. 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: >- Indica si los firmantes deben verificar su correo electrónico con un código de un solo uso antes de acceder al documento; `null` hereda la configuración del espacio de trabajo o de la 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; `null` hereda la configuración del espacio de trabajo o de la empresa. 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` desactiva la edición. Cuando se define, un cuadro de diálogo de confirmación permite a los firmantes editar los campos indicados. 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: - temp_id - order description: >- Un participante de sello de organización de una nueva solicitud de firma: un elemento de `seal_participants` en `POST /signing-requests` y `POST /signing-requests/create-and-send`. properties: seal_id: type: string format: uuid description: >- ID del sello de organización a aplicar; omítelo para usar el sello predeterminado del espacio de trabajo o, cuando este no tiene ninguno, el de la empresa. La llamada responde 400 `SEAL_UNAVAILABLE` cuando no existe ninguno de los dos. order: type: integer minimum: 1 description: Posición en la secuencia de firma temp_id: type: string description: >- ID temporal de este participante de sello, obligatorio y único dentro de `seal_participants`; los campos de la misma solicitud lo nombran en `seal_participant_temp_id`. 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. Cada elemento es un participante de sello persistido (`dropped: false`) o, en una solicitud basada en plantilla, una entrada para un sello de plantilla que no se copió porque la empresa de la clave API no puede ver el sello o porque el sello está limitado a otro espacio de trabajo (`dropped: true`, `id` y `order` null, `seal_out_of_scope: true`). Las entradas descartadas van después de las persistidas, en el orden de la plantilla. Los sellos de plantilla que un array `seal_participants` explícito reemplazó no se listan. items: oneOf: - $ref: '#/components/schemas/SealParticipantCreated' - $ref: '#/components/schemas/SealParticipantDropped' 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_NO_IMAGE_FIELD, SEAL_ORDER_COLLISION, SEAL_PAUSED, SEAL_SCOPE_FORBIDDEN, SEAL_UNAVAILABLE Códigos multidocumento: consulte MultiDocumentErrorCode (41 códigos). 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_NO_IMAGE_FIELD, SEAL_ORDER_COLLISION, SEAL_PAUSED, SEAL_SCOPE_FORBIDDEN, SEAL_UNAVAILABLE MultiDocumentError: description: Un error respondido por una ruta multidocumento. allOf: - $ref: '#/components/schemas/Error' - type: object required: - error - code properties: code: $ref: '#/components/schemas/MultiDocumentErrorCode' 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 SealParticipantCreated: description: >- Un participante de sello persistido del nuevo documento: todas las claves de SealParticipantApi, más `dropped: false`. allOf: - $ref: '#/components/schemas/SealParticipantApi' - type: object required: - dropped properties: dropped: type: boolean enum: - false SealParticipantDropped: type: object description: >- Un sello de plantilla que no se copió a la nueva solicitud de firma o plantilla porque no está disponible allí: la empresa de la clave no puede ver el sello, o el sello está limitado a un espacio de trabajo distinto del espacio de trabajo de destino. Los campos que pertenecen al sello tampoco se copiaron. `seal` es el resumen de la versión actual del sello, o null cuando el sello no es visible para la empresa de la clave. required: - id - order - seal - seal_out_of_scope - dropped properties: id: type: string nullable: true enum: - null description: 'Siempre null: no se creó ningún participante.' order: type: integer nullable: true enum: - null description: 'Siempre null: no se creó ningún participante.' seal: type: object nullable: true description: >- Resumen de la versión actual del sello; null cuando la empresa de la clave API no puede ver el sello. required: - id - lineage_id - name - version - display_name properties: id: type: string format: uuid lineage_id: type: string format: uuid description: Compartido entre las versiones del mismo sello name: type: string version: type: integer display_name: type: string seal_out_of_scope: type: boolean enum: - true dropped: type: boolean enum: - true MultiDocumentErrorCode: type: string enum: - ALREADY_CANCELLED - ALREADY_FINISHED - ALREADY_SENT - ANCHOR_DOCUMENT_REQUIRED - ANCHOR_MISMATCH - CONFLICTING_DOCUMENT_SOURCE - DIMENSION_MISMATCH - DOCUMENTS_LAYOUT_VERSION_REQUIRED - DOCUMENT_CANDIDATE_EXPIRED - DOCUMENT_NOT_FOUND - DOCUMENT_ORIGINAL_NOT_AVAILABLE - DOCUMENT_SET_BUSY - DOCUMENT_SET_DISPATCH_STALE - DOCUMENT_SET_INCONSISTENT - DOCUMENT_SET_LOCKED - DOCUMENT_SET_TOO_LARGE - DOCUMENT_SET_VERSION_CONFLICT - DOCUMENT_SIGNED_NOT_AVAILABLE - DOCUMENT_UPLOAD_NOT_FOUND - DUPLICATE_DOCUMENT_ID - FENCE_COLUMN_PROTECTED - INSUFFICIENT_CREDITS - INTERNAL - INTERNAL_ERROR - INVALID_DOCUMENT_ORDER - INVALID_SIGNING_ORDER - MAX_DOCUMENTS_EXCEEDED - MIN_DOCUMENTS_REQUIRED - MULTI_DOCUMENT_READ_ONLY - MULTI_DOCUMENT_REPLACE_UNSUPPORTED - NOT_FOUND - PAGE_COUNT_MISMATCH - PARTICIPANTS_CHANGED - RATE_LIMIT_EXCEEDED - SEAL_MUTATION_NOT_ALLOWED - SEND_EFFECTS_EXIST - SEND_IN_PROGRESS - SIGNED_DATA_IMMUTABLE - SIGNING_ORDER_LOCKED_APPLIED - SIGNING_ORDER_LOCKED_SENDING - SIGNING_ORDER_LOCKED_SENT - VALIDATION_ERROR description: >- Códigos de error del contrato multidocumento y de las rutas que modifica (generados a partir de las filas de la matriz de errores que expone la API). Un fallo genuino del servidor responde 500 con INTERNAL_ERROR en las rutas heredadas e INTERNAL en las rutas HttpError compartidas (despacho multidocumento, el mapa de estados RPC, las rutas del conjunto de documentos); ninguno de los dos incluye detalles. 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. SealParticipantApi: type: object description: >- Participante de sello tal como lo devuelve la API en una solicitud de firma o en una plantilla. Todas las claves están siempre presentes; las claves anulables son null cuando no tienen valor. required: - id - order - seal - status - applied_at - paused_at - pause_reason - swapped_from_seal_id - triggered_by_recipient_id - sender_kind - seal_out_of_scope properties: id: type: string format: uuid order: type: integer minimum: 1 description: >- Posición en el orden de firma, compartida con el espacio de orden de los destinatarios. seal: type: object description: El sello de organización que aplica este participante. required: - id - lineage_id - name - version - display_name properties: id: type: string format: uuid lineage_id: type: string format: uuid description: Compartido entre las versiones del mismo sello name: type: string version: type: integer display_name: type: string status: type: string enum: - pending - paused - applied description: >- applied cuando applied_at tiene valor; si no, paused cuando paused_at tiene valor; si no, pending. applied_at: type: string format: date-time nullable: true paused_at: type: string format: date-time nullable: true pause_reason: type: string nullable: true enum: - seal_revoked_stop_pending - seal_integrity_mismatch - null swapped_from_seal_id: type: string format: uuid nullable: true triggered_by_recipient_id: type: string format: uuid nullable: true description: El destinatario cuya acción aplicó el sello. sender_kind: type: string nullable: true enum: - dashboard - api_key - embedded - null seal_out_of_scope: type: boolean description: >- Verdadero cuando el sello pertenece a un espacio de trabajo distinto del de la solicitud de firma o de la plantilla. 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: 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.