> ## 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. # Actualización Integral de Plantilla > Actualización integral de la plantilla, incluyendo propiedades, usuarios, campos y recordatorios. Admite la eliminación de usuarios con reasignación o eliminación de campos. Todas las secciones son opcionales, pero se debe proporcionar al menos una. **No atómico.** Las partes de esta llamada no se aplican como una sola actualización. Cada entrada de `users` o `deleted_users` que añade, mueve o elimina a un firmante o a un aprobador se guarda por separado, en el orden de la petición. Si se rechaza uno de estos guardados, la llamada responde de inmediato con ese error: lo guardado antes se mantiene aplicado y el resto de la petición no se procesa. Los demás problemas (por ejemplo un usuario que no se encuentra, o un campo o un recordatorio no válido) se acumulan y se responden como un único 400 `VALIDATION_ERROR` al final de la llamada. Una vez acumulado un problema, algunos de los cambios restantes se omiten (las entradas de `users`, `fields` y `reminders` que le siguen) y otros todavía pueden aplicarse antes del 400, y lo guardado antes del problema se mantiene aplicado. El 400 no siempre indica qué entradas fallaron. Lee de nuevo la plantilla tras cualquier respuesta que no sea 2xx. Si la lectura de los participantes de sello de la plantilla para la respuesta falla después de las escrituras, la llamada responde 500 aunque las escrituras se hayan aplicado. **Participantes de sello.** La propiedad de petición `seal_participants` define los participantes de sello de la plantilla. Cuando la clave está ausente, los participantes de sello de la plantilla no se modifican. Cuando es un array, el array reemplaza todo el conjunto: se elimina cada participante de sello que tenía la plantilla junto con los campos que poseía, y se crea un participante de sello por cada entrada, de modo que `[]` los elimina todos. Cada entrada es un objeto con `seal_id` (obligatorio, el ID de un sello de organización), `order` (obligatorio, un entero positivo que ninguna otra entrada repite y que no es mayor que el número de destinatarios de la plantilla más el número de entradas) y un `temp_id` opcional. Los destinatarios conservan su orden relativo y cada sello se coloca en su `order`. `null`, cualquier otro valor que no sea un array y una entrada sin `seal_id` responden 400 `VALIDATION_ERROR`; un `order` que incumple las reglas anteriores responde 400 `INVALID_SIGNING_ORDER`; un `seal_id` que no es un UUID responde 404 `NOT_FOUND`; un sello de tu empresa que está revocado o borrado responde 400 `SEAL_UNAVAILABLE`. Cada una de estas respuestas es inmediata y deja sin cambios los participantes de sello. `seal_participants` se procesa después de las demás partes de la llamada, también cuando estas acumularon problemas, por lo que puede aplicarse en una llamada que después responde 400 `VALIDATION_ERROR`. ## OpenAPI ````yaml api-reference/v01.39.01/openapi-v01.39.01.es.json put /templates/{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: /templates/{id}: put: tags: - Templates summary: Actualización Integral de Plantilla description: >- Actualización integral de la plantilla, incluyendo propiedades, usuarios, campos y recordatorios. Admite la eliminación de usuarios con reasignación o eliminación de campos. Todas las secciones son opcionales, pero se debe proporcionar al menos una. **No atómico.** Las partes de esta llamada no se aplican como una sola actualización. Cada entrada de `users` o `deleted_users` que añade, mueve o elimina a un firmante o a un aprobador se guarda por separado, en el orden de la petición. Si se rechaza uno de estos guardados, la llamada responde de inmediato con ese error: lo guardado antes se mantiene aplicado y el resto de la petición no se procesa. Los demás problemas (por ejemplo un usuario que no se encuentra, o un campo o un recordatorio no válido) se acumulan y se responden como un único 400 `VALIDATION_ERROR` al final de la llamada. Una vez acumulado un problema, algunos de los cambios restantes se omiten (las entradas de `users`, `fields` y `reminders` que le siguen) y otros todavía pueden aplicarse antes del 400, y lo guardado antes del problema se mantiene aplicado. El 400 no siempre indica qué entradas fallaron. Lee de nuevo la plantilla tras cualquier respuesta que no sea 2xx. Si la lectura de los participantes de sello de la plantilla para la respuesta falla después de las escrituras, la llamada responde 500 aunque las escrituras se hayan aplicado. **Participantes de sello.** La propiedad de petición `seal_participants` define los participantes de sello de la plantilla. Cuando la clave está ausente, los participantes de sello de la plantilla no se modifican. Cuando es un array, el array reemplaza todo el conjunto: se elimina cada participante de sello que tenía la plantilla junto con los campos que poseía, y se crea un participante de sello por cada entrada, de modo que `[]` los elimina todos. Cada entrada es un objeto con `seal_id` (obligatorio, el ID de un sello de organización), `order` (obligatorio, un entero positivo que ninguna otra entrada repite y que no es mayor que el número de destinatarios de la plantilla más el número de entradas) y un `temp_id` opcional. Los destinatarios conservan su orden relativo y cada sello se coloca en su `order`. `null`, cualquier otro valor que no sea un array y una entrada sin `seal_id` responden 400 `VALIDATION_ERROR`; un `order` que incumple las reglas anteriores responde 400 `INVALID_SIGNING_ORDER`; un `seal_id` que no es un UUID responde 404 `NOT_FOUND`; un sello de tu empresa que está revocado o borrado responde 400 `SEAL_UNAVAILABLE`. Cada una de estas respuestas es inmediata y deja sin cambios los participantes de sello. `seal_participants` se procesa después de las demás partes de la llamada, también cuando estas acumularon problemas, por lo que puede aplicarse en una llamada que después responde 400 `VALIDATION_ERROR`. operationId: updateTemplate parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object properties: template_properties: type: object description: Actualizar los metadatos y la configuración de la plantilla properties: name: type: string maxLength: 255 description: type: string document: type: string format: byte description: >- PDF o DOCX codificado en base64 para reemplazar el documento. Los archivos DOCX se convierten automáticamente a PDF. Para documentos de más de 5 MB, usa POST /documents y pasa el document_id en su lugar. (mutuamente excluyente con document_id) document_id: type: string format: uuid description: >- ID de un documento subido previamente (mutuamente excluyente con document). Obténlo llamando primero a POST /documents. example: 123e4567-e89b-12d3-a456-426614174000 expiration_hours: type: integer minimum: 1 settings: type: object properties: allow_editing_before_sending: type: boolean attach_pdf_on_finish: type: boolean allow_download: type: boolean hand_drawn_only: type: boolean require_otp_verification: type: boolean nullable: true description: >- Exige a los firmantes verificar su correo electrónico con un código de un solo uso; `null` hereda la configuración del espacio de trabajo o de la empresa. disable_guided_navigation: type: boolean nullable: true 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 la configuración del espacio de trabajo o de la empresa cuando es null. users: type: array description: >- Insertar o actualizar usuarios (incluye id para actualizar, omítelo para crear). Un destinatario existente no puede cambiarse entre CC y Firmante/Aprobador (400); elimínalo y créalo de nuevo. items: type: object required: - first_name - email - designation - order properties: id: type: string format: uuid description: Omítelo para usuarios nuevos first_name: type: string last_name: type: string description: >- Opcional, pero requerido si se usan las variables prellenadas full_name o last_name email: type: string format: email designation: type: string enum: - Signer - Approver - CC order: type: integer minimum: 1 phone_number: type: string street_address: type: string city: type: string state_province: type: string postal_code: type: string country: type: string title: type: string company: type: string force_remove_conditions: type: boolean default: false description: >- Al eliminar usuarios cuyos campos son referenciados por condiciones en otros campos: si es true, elimina automáticamente las referencias de condición; si es false (predeterminado), la solicitud será rechazada con un error. deleted_users: type: array description: Usuarios a eliminar con estrategia de manejo de campos items: type: object required: - user_id - field_action properties: user_id: type: string format: uuid field_action: type: string enum: - delete - reassign description: Qué hacer con los campos asignados a este usuario reassign_to_user_id: type: string format: uuid description: >- Requerido cuando field_action es 'reassign'. El usuario destino debe tener la misma designación. fields: type: array description: >- Crea o actualiza campos (incluye id para actualizar, omítelo para crear) items: type: object required: - type - x - 'y' - width - height - page properties: id: type: string format: uuid description: Omitir para campos nuevos type: type: string enum: - signature - text - date - checkbox - dropdown - approval_signature - approval_checkmark - approval_date x: type: number minimum: 0 maximum: 100 description: Posición X como porcentaje 'y': type: number minimum: 0 maximum: 100 description: Posición Y como porcentaje width: type: number minimum: 0 maximum: 100 height: type: number minimum: 0 maximum: 100 page: type: integer minimum: 1 required: type: boolean default: false assigned_to_user_id: type: string format: uuid options: type: array items: type: string description: Para campos de tipo desplegable default_to_signing_date: type: boolean description: Para campos de fecha multi_group_id: type: string format: uuid description: >- ID de grupo para grupos de casillas de verificación/botones de opción mutuamente excluyentes variable_name: type: string variable_defined_name: type: string maxLength: 100 nullable: true description: >- Nombre de definición de campo personalizado legible para humanos. Se puede usar como alternativa a variable_name para apuntar a campos en la creación basada en plantillas. required_conditions: $ref: '#/components/schemas/ConditionSet' nullable: true visibility_conditions: $ref: '#/components/schemas/ConditionSet' nullable: true reminders: type: array description: >- Crea o actualiza recordatorios (incluye id para actualizar, omítelo para crear) items: type: object required: - hours - subject - message properties: id: type: string format: uuid description: Omitir para recordatorios nuevos hours: type: integer minimum: 1 description: Horas después del envío antes del recordatorio all_users: type: boolean default: false user_id: type: string format: uuid description: Requerido si all_users es false subject: type: string maxLength: 255 message: type: string maxLength: 5000 documents_layout_version: type: integer minimum: 0 description: >- El `documents_layout_version` de su última lectura (multidocumento). Obligatorio para escribir un campo en una plantilla 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`. seal_participants: type: array description: >- Cuando está presente, el array reemplaza todo el conjunto de participantes de sello de la plantilla y elimina los campos que poseían los anteriores; `[]` los elimina todos; omite la clave para dejarlos sin cambios. `null` no se acepta: responde 400 `VALIDATION_ERROR`. Consulta la descripción de la operación para las reglas de cada entrada y los errores. items: $ref: '#/components/schemas/TemplateSealParticipantInput' responses: '200': description: >- Plantilla actualizada correctamente. Devuelve la plantilla completa con todas sus relaciones. `seal_participants` lista solo los participantes de sello cuyo sello pertenece a la empresa de la clave API: un participante de sello cuyo sello falta o pertenece a otra empresa se omite, de modo que una lista vacía o más corta no demuestra que la plantilla no tenga otro participante de sello guardado. headers: X-RateLimit-Limit: schema: type: integer description: 'Límite de solicitudes: 120 solicitudes por minuto' X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/TemplateDetail' '400': description: >- Solicitud Incorrecta - La validación falló. Multidocumento: `PAGE_COUNT_MISMATCH`, `DIMENSION_MISMATCH` (reemplazo de documento). Escrituras de campos multidocumento: `VALIDATION_ERROR` con la clave `page` (una página posterior al número de páginas del documento) o `documents_layout_version` 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' '404': $ref: '#/components/responses/NotFoundError' '409': description: >- Conflicto: `MULTI_DOCUMENT_READ_ONLY`, `MULTI_DOCUMENT_REPLACE_UNSUPPORTED`, `DOCUMENT_SET_VERSION_CONFLICT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_DISPATCH_STALE`, `DOCUMENT_CANDIDATE_EXPIRED`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENTS_LAYOUT_VERSION_REQUIRED` content: application/json: schema: $ref: '#/components/schemas/MultiDocumentError' '429': $ref: '#/components/responses/RateLimitError' security: - ApiKeyAuth: [] x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: |- import { FirmaClient } from "@firma-dev/sdk"; const firma = new FirmaClient({ apiKey: "YOUR_API_KEY" }); const response = await firma.templates.updateTemplate({ id: "id" }); console.log(response); components: schemas: 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 TemplateSealParticipantInput: type: object required: - seal_id - order description: >- Un participante de sello de una plantilla: un elemento de `seal_participants` en `PUT /templates/{id}`. properties: seal_id: type: string format: uuid description: >- ID del sello de organización que aplica este participante de sello. Obligatorio: esta llamada no tiene sello predeterminado. order: type: integer minimum: 1 description: >- Posición del sello entre los destinatarios y los sellos de la plantilla: un entero positivo que ninguna otra entrada repite y que no es mayor que el número de destinatarios de la plantilla más el número de entradas. temp_id: type: string description: ID temporal opcional de esta entrada. TemplateDetail: description: >- Una plantilla con sus participantes de sello: todas las claves de Template, más `seal_participants`. `seal_participants` lista solo los participantes de sello cuyo sello pertenece a la empresa de la clave API: un participante de sello cuyo sello falta o pertenece a otra empresa se omite, de modo que una lista vacía o más corta no demuestra que la plantilla no tenga otro participante de sello guardado. allOf: - $ref: '#/components/schemas/Template' - type: object required: - seal_participants properties: seal_participants: type: array description: >- Los participantes de sello de la plantilla en orden, limitados a aquellos cuyo sello pertenece a la empresa de la clave API. Un participante de sello cuyo sello falta o pertenece a otra empresa se omite, de modo que una lista vacía o más corta no demuestra que la plantilla no tenga otro participante de sello guardado. items: $ref: '#/components/schemas/SealParticipantApi' 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' 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. Template: type: object properties: id: type: string format: uuid description: Identificador único de la plantilla name: type: string description: Nombre de la plantilla maxLength: 255 description: type: string description: Descripción de la plantilla nullable: true document_url: type: string format: uri description: >- URL prefirmada al documento PDF. Es una URL firmada con tiempo limitado para acceso seguro; consulta document_url_expires_at para conocer el momento de expiración. Las URLs iniciales son válidas por 7 días; las URLs renovadas son válidas por 1 hora. Solicita una nueva recuperación de la plantilla para obtener una URL nueva si ha expirado. document_url_expires_at: type: string format: date-time nullable: true description: >- Marca de tiempo ISO 8601 de cuándo expirará document_url. Después de este momento, la URL devolverá un error de acceso denegado. Vuelve a obtener la plantilla para recibir una nueva URL firmada. page_count: type: integer minimum: 1 description: Número de páginas del documento expiration_hours: type: integer minimum: 1 default: 168 description: >- Horas hasta que expiren las solicitudes de firma creadas a partir de esta plantilla credit_cost: type: integer minimum: 1 default: 1 description: >- Número de créditos consumidos cuando se envía una solicitud de firma desde esta plantilla. El valor mínimo es 1. settings: $ref: '#/components/schemas/SigningRequestSettings' recipients: type: array items: $ref: '#/components/schemas/TemplateUser' description: >- Destinatarios de la plantilla (incluido en GET de una sola plantilla) fields: type: array items: $ref: '#/components/schemas/TemplateField' description: Campos de la plantilla (incluido en GET de una sola plantilla) created_date: type: string format: date-time description: Marca de tiempo de creación de la plantilla updated_date: type: string format: date-time description: Marca de tiempo de la última actualización de la plantilla documents: type: array items: $ref: '#/components/schemas/DocumentSummary' description: >- Los documentos de la plantilla en orden de posición (multidocumento; presente solo para las empresas habilitadas). En GET /templates (el listado): una entrada de listado no incluye `document_url`. Un elemento cuyo conjunto de documentos nunca se ha modificado aparece aquí con `documents: []`, mientras que su GET individual devuelve su único documento (con `document_id` null). En GET /templates/{id}, PUT /templates/{id} y POST /templates: un elemento cuyo conjunto de documentos nunca se ha modificado devuelve su único documento, con `document_id` null. documents_version: type: integer description: >- Versión del conjunto de documentos; aumenta con cada cambio de documentos (multidocumento; solo empresas habilitadas). documents_layout_version: type: integer description: >- Versión de la disposición de los documentos; aumenta cuando se añaden, eliminan o reordenan documentos (multidocumento; solo empresas habilitadas). Las escrituras de campos en una solicitud de firma con más de un documento la devuelven como `documents_layout_version`. required: - id - name - created_date 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. 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. 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. 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. TemplateUser: type: object properties: id: type: string format: uuid description: Identificador único del usuario de la plantilla name: type: string description: Nombre del destinatario (nombre y apellido combinados) email: type: string format: email description: Dirección de correo electrónico del destinatario first_name: type: string nullable: true description: Nombre del destinatario last_name: type: string nullable: true description: Apellido del destinatario designation: type: string enum: - Signer - Approver - CC description: >- Rol del destinatario. Signer firma el documento, Approver aprueba con campos de aprobación, CC recibe una copia al finalizar. order: type: integer minimum: 1 description: Orden en el que el destinatario debe firmar phone_number: type: string nullable: true description: Número de teléfono del destinatario street_address: type: string nullable: true description: Dirección postal del destinatario city: type: string nullable: true description: Ciudad del destinatario state_province: type: string nullable: true description: Estado o provincia del destinatario postal_code: type: string nullable: true description: Código postal del destinatario country: type: string nullable: true description: País del destinatario title: type: string nullable: true description: Cargo del destinatario company: type: string nullable: true description: Nombre de la empresa del destinatario required_fields: type: array items: type: string description: >- Lista de campos de datos del destinatario requeridos para el envío (basada en los campos de la plantilla con asignaciones de variable_name). Siempre incluye 'email' y 'first_name'. missing_fields: type: array items: type: string description: >- Lista de campos requeridos que actualmente están vacíos para este destinatario required_read_only_fields: type: array items: type: object properties: variable_name: type: string nullable: true description: Nombre de variable del campo de solo lectura variable_defined_name: type: string nullable: true description: >- Nombre del campo legible para humanos, tomado de la definición del campo personalizado (por ejemplo, 'artist_name'). Solo está presente para campos vinculados a una definición de campo personalizado; de lo contrario es null. field_type: type: string description: Tipo del campo (text, date, etc.) description: >- Lista de campos obligatorios de solo lectura que necesitan valores prellenados antes de enviar ready_to_send: type: boolean description: >- Indica si este destinatario tiene todos los datos obligatorios completados para poder enviarse required: - id - first_name - email - designation - order TemplateField: type: object description: Un campo colocado en un documento de plantilla properties: id: type: string format: uuid description: Identificador único del campo type: type: string enum: - text - signature - date - checkbox - dropdown - radio_buttons - number - text_area - file - initial - stamp - approval_signature - approval_checkmark - approval_date description: Tipo del campo required: type: boolean description: Indica si el campo es obligatorio recipient_id: type: string format: uuid nullable: true description: ID del destinatario asignado variable_name: type: string nullable: true description: Nombre de variable del campo (usado en plantillas) variable_defined_name: type: string nullable: true description: >- Nombre del campo legible para humanos, tomado de la definición del campo personalizado (por ejemplo, 'artist_name'). Solo está presente para campos vinculados a una definición de campo personalizado; de lo contrario es null. position: type: object description: >- Posición y dimensiones del campo en el documento. Todos los valores son porcentajes (0-100). El campo debe caber dentro de la página: x + width <= 100 y y + height <= 100. properties: x: type: number minimum: 0 maximum: 100 description: Coordenada X de la posición del campo (porcentaje, 0-100) 'y': type: number minimum: 0 maximum: 100 description: Coordenada Y de la posición del campo (porcentaje, 0-100) width: type: number minimum: 0 maximum: 100 description: >- Ancho del campo (porcentaje, 0-100). Nota: x + width debe ser <= 100 height: type: number minimum: 0 maximum: 100 description: >- Alto del campo (porcentaje, 0-100). Nota: y + height debe ser <= 100 page_number: type: integer minimum: 1 nullable: true description: >- Número de página donde se encuentra el campo (empieza en 1). No debe superar el total de páginas del documento. dropdown_options: nullable: true description: Opciones para campos desplegables oneOf: - type: array items: type: string - type: object multi_group_id: type: string format: uuid nullable: true description: >- ID de grupo para vincular varios campos de casilla de verificación o botón de opción entre sí. Los campos que comparten el mismo multi_group_id se comportan como un grupo mutuamente excluyente (como botones de opción): seleccionar uno deselecciona automáticamente los demás del grupo. Usa el mismo UUID en varios campos para crear un grupo donde solo se puede seleccionar una opción a la vez. date_default: type: string format: date nullable: true description: >- Valor de fecha predeterminado para campos de fecha (formato ISO 8601, por ejemplo, '2024-01-15') date_signing_default: type: boolean description: >- Usar la fecha de firma como valor predeterminado para campos de fecha format_rules: $ref: '#/components/schemas/DateFormatRules' nullable: true description: >- Reglas de formato: actualmente se usan para campos de fecha, para especificar el formato de visualización validation_rules: $ref: '#/components/schemas/FieldValidationRules' read_only: type: boolean default: false description: Indica si este campo es de solo lectura (prellenado antes de firmar) read_only_value: type: string nullable: true description: Valor estático para campos de solo lectura required: - id - type - page_number DocumentSummary: type: object description: Un documento de una plantilla o solicitud de firma. required: - document_id - position - label - original_filename - page_count - document_url_kind properties: document_id: type: string format: uuid nullable: true description: >- Id del documento. null solo para el único documento de una solicitud de firma o plantilla cuyo conjunto de documentos nunca se ha modificado (vea el ejemplo). position: type: integer minimum: 1 description: Posición en el conjunto, empezando en 1. label: type: string nullable: true maxLength: 200 description: Nombre visible, o null. original_filename: type: string nullable: true maxLength: 255 description: Nombre de archivo registrado al subirlo, o null. page_count: type: integer nullable: true description: Número de páginas de este documento. document_url: type: string nullable: true description: >- URL firmada (1 hora) del archivo que indica `document_url_kind`. Ausente en las respuestas de listado. document_url_kind: type: string nullable: true enum: - stored - signed - null description: >- `stored`: el documento tal como está almacenado; `signed`: el documento sellado individualmente. Siempre `stored` en las plantillas; null en las entradas del listado de solicitudes de firma. document_only_hash: type: string nullable: true description: >- SHA-256 (hex) del documento sellado individualmente; null antes de que se vincule el certificado. Solo solicitudes de firma. example: document_id: null position: 1 label: null original_filename: null page_count: 3 document_url: >- https://api.firma.dev/storage/v1/object/sign/signing-request-documents/example.pdf?token=example document_url_kind: stored document_only_hash: null 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 FieldValidationRules: type: object nullable: true description: >- Reglas de validación para valores de campo. Reservado para uso futuro: actualmente no se aplica a ningún tipo de campo. additionalProperties: true responses: UnauthorizedError: description: No Autorizado - Clave API inválida o faltante content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Unauthorized message: Invalid API key NotFoundError: description: No Encontrado - El recurso no existe content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Not Found message: The requested resource was not found 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.