> ## 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. # Actualizar Parcialmente una Solicitud de Firma > Actualiza las propiedades de la solicitud de firma, un único destinatario O un único campo. No se pueden actualizar varios tipos de entidad en una misma petición. No se puede actualizar después de que la solicitud de firma se haya enviado, completado o cancelado, salvo para un intercambio de sello (consulta `seal_participant`). Un `seal_participant` que nombra un sello responde 404 `NOT_FOUND` cuando el sello no existe o pertenece a otra empresa, y 400 `SEAL_UNAVAILABLE` cuando el sello está revocado, borrado o no es la versión actual de su linaje, y también cuando está limitado a un espacio de trabajo distinto del de la solicitud de firma. Estas respuestas son para añadir un participante de sello y para cambiar su sello. Un intercambio de sello (`swap_to_seal_id`) responde de forma distinta para el nuevo sello: 404 `NOT_FOUND` cuando no existe, pertenece a otra empresa o está limitado a un espacio de trabajo distinto del de la solicitud de firma; 409 `SEAL_UNAVAILABLE` cuando está revocado, borrado o no es la versión actual de su linaje; 400 `SEAL_FIELD_REQUIRED` cuando el participante de sello no tiene campo de sello en la solicitud de firma. Añadir un participante de sello o cambiar su sello responde 503 `SEALS_DISABLED` cuando los sellos de organización no están habilitados. Añadir un participante de sello requiere `order` (consulta el contrato de orden). Un campo que pertenece a un participante de sello solo acepta cambios de `position` y `page_number`; cualquier otra clave de `field`, incluida `recipient_id`, se ignora. ## OpenAPI ````yaml api-reference/v01.39.01/openapi-v01.39.01.es.json patch /signing-requests/{id} openapi: 3.0.3 info: title: API de Socios de Firma description: >- API RESTful para firma de documentos y gestión de plantillas. **Autenticación**: Todos los endpoints requieren autenticación mediante clave API a través del encabezado `Authorization`. Usa tu clave API directamente sin ningún prefijo (por ejemplo, `your-api-key`). El prefijo Bearer es opcional pero no obligatorio. **Características de Seguridad**: - Validación de entrada usando esquemas Zod con mensajes de error detallados a nivel de campo - Tokens JWT firmados con RSA-256 para el acceso al Editor de Plantillas incrustado **Límite de Solicitudes**: Los límites de solicitudes están escalonados según el tipo de operación: - Operaciones de lectura (GET): 200 solicitudes por minuto - Operaciones de escritura (POST/PUT/PATCH/DELETE): 120 solicitudes por minuto - Operaciones CRUD de webhooks: 60 solicitudes por minuto - Prueba de webhook: 10 solicitudes por minuto - Regeneración/expiración de clave API: 1 solicitud por minuto - Rotación de secreto de webhook: 1 solicitud por minuto Cuando se superan los límites de solicitudes, la API devuelve una respuesta `429 Too Many Requests` con los encabezados: - `X-RateLimit-Limit`: Máximo de solicitudes por minuto para este endpoint - `X-RateLimit-Remaining`: Solicitudes restantes en la ventana actual - `X-RateLimit-Reset`: Marca de tiempo Unix de cuándo se restablece el límite - `Retry-After`: Segundos hasta que se permita reintentar **Manejo de Errores**: Todos los errores devuelven respuestas JSON estructuradas con `error` (mensaje legible para humanos), `code` (identificador legible por máquina) y `details` (errores de validación a nivel de campo cuando corresponda). **Integración del Editor de Plantillas Incrustado**: El Editor de Plantillas de Firma se puede incrustar en tu aplicación usando una biblioteca JavaScript independiente. ```html ``` **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/{id}: patch: tags: - Signing Requests summary: Actualizar Parcialmente una Solicitud de Firma description: >- Actualiza las propiedades de la solicitud de firma, un único destinatario O un único campo. No se pueden actualizar varios tipos de entidad en una misma petición. No se puede actualizar después de que la solicitud de firma se haya enviado, completado o cancelado, salvo para un intercambio de sello (consulta `seal_participant`). Un `seal_participant` que nombra un sello responde 404 `NOT_FOUND` cuando el sello no existe o pertenece a otra empresa, y 400 `SEAL_UNAVAILABLE` cuando el sello está revocado, borrado o no es la versión actual de su linaje, y también cuando está limitado a un espacio de trabajo distinto del de la solicitud de firma. Estas respuestas son para añadir un participante de sello y para cambiar su sello. Un intercambio de sello (`swap_to_seal_id`) responde de forma distinta para el nuevo sello: 404 `NOT_FOUND` cuando no existe, pertenece a otra empresa o está limitado a un espacio de trabajo distinto del de la solicitud de firma; 409 `SEAL_UNAVAILABLE` cuando está revocado, borrado o no es la versión actual de su linaje; 400 `SEAL_FIELD_REQUIRED` cuando el participante de sello no tiene campo de sello en la solicitud de firma. Añadir un participante de sello o cambiar su sello responde 503 `SEALS_DISABLED` cuando los sellos de organización no están habilitados. Añadir un participante de sello requiere `order` (consulta el contrato de orden). Un campo que pertenece a un participante de sello solo acepta cambios de `position` y `page_number`; cualquier otra clave de `field`, incluida `recipient_id`, se ignora. operationId: patchSigningRequest parameters: - name: id in: path required: true schema: type: string format: uuid description: ID de la Solicitud de Firma requestBody: required: true content: application/json: schema: oneOf: - type: object description: Actualizar solo las propiedades de la Solicitud de Firma properties: name: type: string maxLength: 255 description: Nuevo nombre para la solicitud de firma description: type: string description: Nueva descripción document: type: string format: byte description: >- Reemplaza el documento con un nuevo PDF codificado en base64. El número de páginas se extraerá automáticamente. expiration_hours: type: integer minimum: 1 description: Nuevas horas de expiración settings: $ref: '#/components/schemas/SigningRequestSettings' description: Actualizar configuración 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. Null o una cadena vacía elimina la sobrescritura; si se omite, no cambia. maxLength: 200 completion_message: type: string nullable: true description: >- Texto principal mostrado en la página de finalización tras la firma. Null o una cadena vacía elimina la sobrescritura; si se omite, no cambia. 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). Null o una cadena vacía elimina la sobrescritura; si se omite, no cambia. 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. Null elimina la sobrescritura; si se omite, no cambia. minimum: 0 maximum: 30 - type: object required: - recipient description: Crea o actualiza un solo destinatario properties: recipient: $ref: '#/components/schemas/Recipient' description: >- Destinatario a crear (omite id) o actualizar (incluye id). Al actualizar first_name o last_name, el campo name se reconstruye automáticamente usando los valores existentes de la base de datos para cualquier campo no proporcionado. Resultado: 'Nombre Apellido' si ambos existen, 'Nombre' si solo existe first_name. - type: object required: - field description: Crea o actualiza un solo campo properties: field: type: object properties: id: type: string format: uuid description: >- Inclúyelo para actualizar un campo existente, omítelo para crear uno nuevo type: type: string enum: - text - signature - date - checkbox - initial - initials - dropdown - radio_buttons - textarea - text_area - url - file - stamp - approval_signature - approval_checkmark - approval_date description: >- Tipo de campo. Acepta 'initial' o 'initials', 'textarea' o 'text_area'. Obligatorio para campos nuevos. Los campos url son de solo lectura automáticamente. Los campos file permiten a los firmantes subir archivos adjuntos (imágenes/PDF). Los campos stamp muestran una imagen preconfigurada. position: type: object properties: x: type: number description: Posición X en el documento 'y': type: number description: Posición Y en el documento width: type: number description: Ancho del campo height: type: number description: Alto del campo description: >- Objeto de posición. Todas las propiedades son obligatorias para campos nuevos. page_number: type: integer minimum: 1 description: >- Número de página (indexado desde 1). Obligatorio para campos nuevos. required: type: boolean description: Si el campo es obligatorio recipient_id: type: string format: uuid nullable: true description: >- ID del destinatario al que asignar el campo; `null` quita el destinatario del campo y lo deja sin asignar. variable_name: type: string description: >- Nombre de variable para el mapeo de datos prellenados variable_defined_name: type: string maxLength: 100 nullable: true description: >- Nombre legible de definición de campo personalizado. Se puede usar como alternativa a variable_name para apuntar a campos en la creación basada en plantilla. dropdown_options: description: Opciones para campos desplegables oneOf: - type: array items: type: string - type: object format_rules: type: object description: >- Reglas de formato (p. ej., formato de fecha, urlDisplayText para campos url, acceptedFileTypes para campos file) validation_rules: type: object description: Reglas de validación para el campo multi_group_id: type: string format: uuid description: ID de grupo para grupos de botones de opción date_default: type: string description: Valor de fecha predeterminado date_signing_default: type: boolean description: >- Para campos de fecha, usa la fecha de firma como valor predeterminado read_only: type: boolean description: >- Si el campo es de solo lectura (automáticamente verdadero para campos url) read_only_value: type: string description: >- Valor estático para campos de solo lectura. Para campos url, esta es la URL a la que enlazar. final_value: type: string description: >- Valor final del campo (para campos de solo lectura prellenados) documents_layout_version: type: integer minimum: 0 description: >- El `documents_layout_version` de su última lectura (multidocumento). Obligatorio para escribir un campo en una solicitud de firma con más de un documento o con una versión de disposición superior a 1 (`409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`); un valor obsoleto responde `409 DOCUMENT_SET_VERSION_CONFLICT`; un valor que no es un entero no negativo responde `400 VALIDATION_ERROR` con la clave `documents_layout_version`. - type: object required: - seal_participant description: >- Añade, actualiza o intercambia un participante de sello de la solicitud de firma. Envía solo la clave `seal_participant`. properties: seal_participant: type: object description: >- Uno de tres usos, según las claves enviadas; cada uno responde `{ "seal_participant": ... }`. Añadir: envía `seal_id` y `order` sin `id`; responde 201. Actualizar: envía `id` con `order` para mover al participante (un `seal_id` enviado junto con `order` se ignora), o `id` con `seal_id` solo para cambiar su sello; responde 200. Añadir y actualizar solo son posibles antes de que se envíe la solicitud (después, 409 `ALREADY_SENT`). Intercambiar: envía `id` con `swap_to_seal_id` para reemplazar el sello de un participante de sello pausado; responde 200. Un intercambio solo es posible en una solicitud que se envió y no está finalizada ni cancelada (409 `SEAL_MUTATION_NOT_ALLOWED` en una solicitud que no se envió y cuando el participante no está pausado), y solo con una clave API del espacio de trabajo protegido (en caso contrario, 403 `PROTECTED_KEY_REQUIRED`). Cuando se envía `swap_to_seal_id`, `seal_id` y `order` se ignoran. properties: id: type: string format: uuid description: >- ID del participante de sello que se va a actualizar o intercambiar. Omítelo para añadir un participante de sello. seal_id: type: string format: uuid description: >- ID del sello de organización. Obligatorio para añadir un participante de sello; en una actualización sin `order` pasa a ser el sello del participante. El sello debe pertenecer a la empresa, ser la versión actual de su linaje, no estar revocado ni borrado y no estar limitado a otro espacio de trabajo. order: type: integer minimum: 1 description: >- Posición en el orden de firma, compartido con el espacio de orden de los destinatarios. Obligatorio para añadir un participante de sello; en una actualización mueve al participante. swap_to_seal_id: type: string format: uuid description: >- ID del sello de organización que reemplaza el sello de un participante de sello pausado en una solicitud enviada. examples: update-properties: summary: Actualizar propiedades value: name: Updated Contract Name expiration_hours: 72 update-recipient: summary: Actualizar destinatario único 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: Agregar nuevo destinatario value: recipient: first_name: Jane last_name: Doe email: jane@example.com designation: Signer order: 2 create-url-field: summary: Crear campo URL value: field: type: url position: x: 100 'y': 200 width: 150 height: 30 page_number: 1 read_only_value: https://example.com/terms format_rules: urlDisplayText: View Terms & Conditions create-file-field: summary: Crear campo de subida de archivo value: field: type: file position: x: 100 'y': 300 width: 200 height: 40 page_number: 1 required: true format_rules: acceptedFileTypes: image_and_pdf update-field: summary: Actualizar posición de campo existente value: field: id: field123-e89b-12d3-a456-426614174000 position: x: 120 'y': 220 responses: '200': description: >- Solicitud de firma actualizada correctamente. La forma de la respuesta depende de lo que se actualizó: la actualización de propiedades devuelve {id, name, template_description, document_url, expiration_hours}; la actualización de un destinatario devuelve el objeto de destinatario completo; la actualización de un campo devuelve el objeto de campo completo; la actualización o el intercambio de un participante de sello devuelve `{ "seal_participant": }`. La respuesta puede incluir un campo 'warning' para advertencias de validación del formato del correo electrónico (no bloqueantes). 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: anyOf: - type: object description: Respuesta al actualizar propiedades properties: id: type: string format: uuid name: type: string template_description: type: string nullable: true document_url: type: string format: uri expiration_hours: type: integer - type: object description: Respuesta al actualizar/crear un destinatario - type: object description: Respuesta al actualizar/crear un campo - type: object description: >- Respuesta al actualizar un participante de sello o intercambiar su sello required: - seal_participant properties: seal_participant: $ref: '#/components/schemas/SealParticipantApi' '201': description: >- Se creó un destinatario, un campo o un participante de sello. El cuerpo es el objeto de destinatario o de campo creado; para un participante de sello es `{ "seal_participant": }`. Actualizar un participante de sello responde 200 con el mismo cuerpo `{ "seal_participant": ... }`. 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: anyOf: - type: object description: El destinatario creado - type: object description: El campo creado - type: object description: El participante de sello creado required: - seal_participant properties: seal_participant: $ref: '#/components/schemas/SealParticipantApi' '400': description: >- Solicitud Incorrecta - No se pueden actualizar propiedades y destinatario en la misma solicitud. Multidocumento: `PAGE_COUNT_MISMATCH`, `DIMENSION_MISMATCH`, `ANCHOR_MISMATCH` (reemplazo de documento en línea; `ANCHOR_MISMATCH`: las anclas del reemplazo no se resuelven como están almacenadas). Escrituras de campos multidocumento: `VALIDATION_ERROR` con la clave `page` (una página más allá del número de páginas del documento) o `documents_layout_version`. Sellos de organización: `SEAL_FIELD_REQUIRED` cuando se envía un intercambio de sello para un participante de sello que no tiene campo de sello en la solicitud de firma. content: application/json: schema: $ref: '#/components/schemas/Error' examples: mixed-update: value: error: Invalid request message: >- Cannot update both properties and recipient in the same request '401': $ref: '#/components/responses/UnauthorizedError' '403': description: >- Se envió un intercambio de sello (`swap_to_seal_id`) con una clave API que no es del espacio de trabajo protegido (`PROTECTED_KEY_REQUIRED`). content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Solicitud de firma o participante de sello no encontrado content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: error: Signing request not found code: NOT_FOUND seal_not_found: value: error: Seal not found code: NOT_FOUND '409': description: >- Conflicto: `MULTI_DOCUMENT_READ_ONLY`, `ALREADY_SENT`, `ALREADY_FINISHED`, `ALREADY_CANCELLED`, `SEND_IN_PROGRESS`, `DOCUMENTS_LAYOUT_VERSION_REQUIRED`, `DOCUMENT_SET_VERSION_CONFLICT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_DISPATCH_STALE`, `DOCUMENT_CANDIDATE_EXPIRED`, `DOCUMENT_SET_INCONSISTENT`, `SIGNED_DATA_IMMUTABLE`, `MULTI_DOCUMENT_REPLACE_UNSUPPORTED`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_UNAVAILABLE`. `MULTI_DOCUMENT_REPLACE_UNSUPPORTED`: un `document` en línea en una solicitud con más de un documento (usa las rutas /documents). `SEAL_MUTATION_NOT_ALLOWED`: un intercambio de sello en una solicitud que no se envió, o de un participante de sello que no está pausado. `SEAL_UNAVAILABLE`: el nuevo sello de un intercambio de sello está revocado, borrado o no es la versión actual de su linaje. 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 '429': $ref: '#/components/responses/RateLimitError' '503': description: >- Los sellos de organización no están habilitados y se añade un participante de sello o se cambia su sello (`SEALS_DISABLED`). content: application/json: schema: $ref: '#/components/schemas/Error' 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.patchSigningRequest({ id: "id", body: { name: "Updated Contract Name", expiration_hours: 72 } }); console.log(response); components: schemas: 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. 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 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. 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' 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. 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.