> ## 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 y Enviar Solicitud de Firma (Atómico) > Crea y envía inmediatamente una solicitud de firma en una única operación atómica. Este endpoint combina la funcionalidad de POST /signing-requests y POST /signing-requests/{id}/send. **Beneficios Clave:** - Una sola llamada a la API en lugar de dos solicitudes separadas - Valida todos los requisitos de envío ANTES de crear la solicitud de firma - Deducción de créditos atómica: solo cobra si todo tiene éxito - Devuelve status: 'sent' inmediatamente con los detalles del primer firmante - Más eficiente (ahorra 1 llamada a la API + tiempo de ida y vuelta) **Validación:** - Todas las validaciones de creación estándar (document/template, recipients, fields) - Validaciones de envío adicionales: - Todos los firmantes deben tener first_name y un email válido - Los campos de solo lectura requeridos deben tener final_value completado - Los campos de datos prellenados (variable_name) deben tener los datos de usuario correspondientes - La empresa debe tener créditos suficientes (≥1) **Atomicidad:** - Si alguna validación falla, no se crea nada - El crédito solo se deduce después de una creación exitosa y antes del envío del email - Si el envío del email falla después de la creación, la solicitud de firma permanece en estado 'draft' y el crédito NO se deduce **Patrón de ID Temporal:** Para la creación basada en documento, usa IDs temporales (formato: 'temp_X') para referenciar destinatarios antes de la creación. La API valida todas las referencias y mapea automáticamente los IDs temporales a UUID reales. **Límite de Tasa:** 120 solicitudes/minuto (igual que las operaciones de escritura) ## OpenAPI ````yaml api-reference/v01.39.01/openapi-v01.39.01.es.json post /signing-requests/create-and-send 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/create-and-send: post: tags: - Signing Requests summary: Crear y Enviar Solicitud de Firma (Atómico) description: >- Crea y envía inmediatamente una solicitud de firma en una única operación atómica. Este endpoint combina la funcionalidad de POST /signing-requests y POST /signing-requests/{id}/send. **Beneficios Clave:** - Una sola llamada a la API en lugar de dos solicitudes separadas - Valida todos los requisitos de envío ANTES de crear la solicitud de firma - Deducción de créditos atómica: solo cobra si todo tiene éxito - Devuelve status: 'sent' inmediatamente con los detalles del primer firmante - Más eficiente (ahorra 1 llamada a la API + tiempo de ida y vuelta) **Validación:** - Todas las validaciones de creación estándar (document/template, recipients, fields) - Validaciones de envío adicionales: - Todos los firmantes deben tener first_name y un email válido - Los campos de solo lectura requeridos deben tener final_value completado - Los campos de datos prellenados (variable_name) deben tener los datos de usuario correspondientes - La empresa debe tener créditos suficientes (≥1) **Atomicidad:** - Si alguna validación falla, no se crea nada - El crédito solo se deduce después de una creación exitosa y antes del envío del email - Si el envío del email falla después de la creación, la solicitud de firma permanece en estado 'draft' y el crédito NO se deduce **Patrón de ID Temporal:** Para la creación basada en documento, usa IDs temporales (formato: 'temp_X') para referenciar destinatarios antes de la creación. La API valida todas las referencias y mapea automáticamente los IDs temporales a UUID reales. **Límite de Tasa:** 120 solicitudes/minuto (igual que las operaciones de escritura) operationId: createAndSendSigningRequest requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string maxLength: 255 description: Nombre de la solicitud de firma example: Employment Contract - John Doe description: type: string description: Descripción de la solicitud de firma example: Full-time employment contract for Software Engineer position document: type: string format: byte description: >- Documento PDF o DOCX codificado en base64 (mutuamente excluyente con template_id y document_id). 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. example: >- JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c... template_id: type: string format: uuid description: >- ID de la plantilla a usar (mutuamente excluyente con document y document_id). **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`. example: 123e4567-e89b-12d3-a456-426614174000 expiration_hours: type: integer minimum: 1 default: 168 description: >- Horas hasta que expira la solicitud de firma (por defecto: 168 = 7 días) example: 168 recipients: type: array description: >- Array de destinatarios. Al menos uno debe ser un Firmante. Para creación basada en documento: obligatorio. Para creación basada en plantilla: opcional (usa los destinatarios de la plantilla si se omite). Usa template_user_id (preferido) u order (alternativa) para hacer coincidir con los usuarios 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. minItems: 1 items: $ref: '#/components/schemas/Recipient' fields: type: array description: >- Array de campos a completar (solo para creación basada en documento) items: type: object required: - type - page - x - 'y' properties: recipient_id: type: string description: >- ID temporal o UUID del destinatario asignado a este campo example: temp_signer_1 type: type: string enum: - signature - initial - text - date - checkbox - dropdown - radio_buttons - text_area - url - file - stamp - approval_signature - approval_checkmark - approval_date description: >- Tipo de campo. Acepta alias: "initials" (normalizado a "initial"), "textarea" (normalizado a "text_area"), "radio" (normalizado a "radio_buttons"). example: signature page: type: integer minimum: 1 description: Número de página del PDF (indexado desde 1) example: 1 x: type: number description: Coordenada X en la página example: 100 'y': type: number description: Coordenada Y en la página example: 200 width: type: number default: 200 example: 200 height: type: number default: 50 example: 50 variable_name: type: string description: >- Nombre de variable para datos precargados (por ejemplo, 'phone_number', 'company'). Si se establece, el campo correspondiente del destinatario debe estar completado. enum: - first_name - last_name - full_name - email - phone_number - street_address - city - state_province - postal_code - country - title - company example: phone_number variable_defined_name: type: string maxLength: 100 nullable: true description: >- Nombre legible del campo personalizado. Se puede usar como alternativa a variable_name para apuntar a campos en la creación basada en plantilla. required: type: boolean default: false description: Si el campo es obligatorio read_only: type: boolean default: false description: Si el campo es de solo lectura (precargado) final_value: type: string description: >- Valor precargado para campos de solo lectura (obligatorio si read_only=true y required=true) example: Software Engineer 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' dropdown_options: description: >- Opciones para campos desplegables. Obligatorio cuando type es "dropdown". example: - Option A - Option B - Option C oneOf: - type: array items: type: string - type: object 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. 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 agregan junto a cualquier campo especificado manualmente. Solo disponible para creación basada en documento (no para creación basada en plantilla). reminders: type: array description: Array de configuraciones de recordatorios items: type: object required: - hours_before_expiration properties: hours_before_expiration: type: integer minimum: 1 description: >- Horas antes de la expiración para enviar el recordatorio example: 24 settings: type: object description: Configuración de la solicitud de firma properties: use_signing_order: type: boolean default: true description: >- Aplica el orden de firma según recipient.order. Cuando es false, todos los firmantes reciben el documento simultáneamente. allow_download: type: boolean default: true description: Permite a los destinatarios descargar el documento attach_pdf_on_finish: type: boolean default: true description: Adjunta el PDF completado al correo de finalización send_signing_email: type: boolean default: true description: Envía notificación por correo a los firmantes send_finish_email: type: boolean default: true description: Envía un correo cuando se completan todas las firmas send_expiration_email: type: boolean default: true description: Envía un correo cuando expira la solicitud send_cancellation_email: type: boolean default: true description: Envía un correo cuando se cancela la solicitud hand_drawn_only: type: boolean default: false description: >- Exige a los firmantes dibujar su firma a mano en lugar de usar firmas escritas identity_editable_fields: type: array nullable: true items: type: string enum: - name - company - title - phone - address description: >- Campos de identidad que los firmantes pueden editar antes de firmar; `null` desactiva la edición. Cuando se define, aparece un cuadro de diálogo de confirmación que permite a los firmantes editar los campos indicados. example: - name - company notify_identity_change_webhook: type: boolean default: false description: >- Envía un evento de webhook cuando un firmante cambia su identidad notify_identity_change_email: type: boolean default: false description: >- Envía notificación por correo cuando un firmante cambia su identidad document_id: type: string format: uuid description: >- ID de un documento subido previamente (mutuamente excluyente con document y template_id). Se obtiene llamando primero a POST /documents. example: 123e4567-e89b-12d3-a456-426614174000 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 (cuando se usa template_id) y después a los valores predeterminados del espacio de trabajo y la empresa. example: Thank you for signing 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 (cuando se usa template_id) y después a los valores predeterminados del espacio de trabajo y la empresa. example: Your signed copy is on its way to your inbox. 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 (cuando se usa template_id) y después a los valores predeterminados del espacio de trabajo y la empresa. example: https://example.com/thank-you 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 (cuando se usa template_id) y después a los valores predeterminados del espacio de trabajo y la empresa. example: 5 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 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`. oneOf: - required: - document - required: - template_id - required: - document_ids examples: document-based: summary: Crear y enviar con documento value: name: Employment Contract - John Doe description: Contrato de empleo a tiempo completo document: JVBERi0xLjQKJeLjz9MK... expiration_hours: 168 recipients: - id: temp_signer_1 first_name: John last_name: Doe email: john.doe@example.com designation: Signer order: 1 phone_number: +1-555-0123 company: Acme Corp title: Ingeniero de Software fields: - recipient_id: temp_signer_1 type: signature page: 1 x: 100 'y': 500 width: 200 height: 50 - recipient_id: temp_signer_1 type: text page: 1 x: 100 'y': 400 width: 150 height: 30 variable_name: phone_number required: true read_only: true settings: use_signing_order: true send_signing_email: true template-based: summary: Crear y enviar desde plantilla value: name: NDA - Jane Smith template_id: 123e4567-e89b-12d3-a456-426614174000 recipients: - first_name: Jane last_name: Smith email: jane.smith@example.com designation: Signer order: 1 company: Tech Startup Inc expiration_hours: 72 responses: '201': description: >- Solicitud de firma creada y enviada exitosamente. La respuesta puede incluir advertencias no bloqueantes 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/CreateAndSendResponse' example: id: 550e8400-e29b-41d4-a716-446655440000 name: Employment Contract - John Doe description: Contrato de empleo a tiempo completo status: sent document_url: https://storage.supabase.co/... page_count: 3 expiration_hours: 168 settings: use_signing_order: true allow_download: true attach_pdf_on_finish: true send_signing_email: true send_finish_email: true send_expiration_email: true send_cancellation_email: true hand_drawn_only: false created_date: '2026-01-12T10:30:00Z' sent_date: '2026-01-12T10:30:00Z' template_id: null first_signer: id: rec456-e89b-12d3-a456-426614174000 name: John Doe email: john.doe@example.com signing_link: >- https://app.firma.dev/signing/rec456-e89b-12d3-a456-426614174000 recipients: - id: rec456-e89b-12d3-a456-426614174000 first_name: John last_name: Doe name: John Doe email: john.doe@example.com designation: Signer order: 1 fields: - id: field123-e89b-12d3-a456-426614174000 field_type: signature seal_participant_id: null credits_remaining: 99 '400': description: >- Error de validación: entrada inválida o faltan datos obligatorios del firmante. 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`. En el paso de envío, `SEAL_NO_IMAGE_FIELD` cuando un participante de sello de la solicitud no posee ningún campo de tipo `stamp` (su campo de estampa): la solicitud no se envía y no se conserva ninguna solicitud de firma. content: application/json: schema: $ref: '#/components/schemas/CreateAndSendValidationError' examples: missing-recipient-data: value: error: >- One or more signers are missing required information for sending phase: send_validation validation_errors: - recipient_index: 1 recipient_email: john@example.com missing_fields: - phone_number - company invalid-document: value: error: Document must be valid base64-encoded PDF phase: create_validation seal-no-image-field: summary: >- Un participante de sello no tiene campo de estampa (imagen del sello) value: error: >- Each organization seal needs at least one seal image field. code: SEAL_NO_IMAGE_FIELD '401': $ref: '#/components/responses/UnauthorizedError' '402': description: Créditos insuficientes content: application/json: schema: $ref: '#/components/schemas/InsufficientCreditsError' '404': description: >- No se encontró la plantilla o no está en el espacio de trabajo de la clave API. 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`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, `DOCUMENT_SET_DISPATCH_STALE`. `SEND_EFFECTS_EXIST` y `ALREADY_SENT` también pueden incluir `signing_request_id`: está presente cuando se conservó la solicitud de firma que creó esta llamada (se rechazó su reversión), por lo que debes recuperar esa solicitud en lugar de reintentar, ya que un reintento crea una segunda solicitud; sin él, no se conservó ninguna solicitud. content: application/json: schema: anyOf: - $ref: '#/components/schemas/CreateAndSendConflictError' - 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' '422': description: >- La dirección de correo del destinatario está suprimida (rebotó anteriormente o fue marcada como spam) y no se le puede enviar content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityError' '429': $ref: '#/components/responses/RateLimitError' '500': description: >- Error inesperado del servidor. Cualquier Solicitud de Firma creada parcialmente se revierte, por lo que no queda ningún borrador. Los errores del paso de envío accionables por el cliente devuelven 400, 402 o 422 en su lugar. content: application/json: schema: $ref: '#/components/schemas/Error' '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.createAndSendSigningRequest({ "name": "Employment Contract - John Doe", "description": "Full-time employment contract", "document": "JVBERi0xLjQKJeLjz9MK...", "expiration_hours": 168, "recipients": [ { "id": "temp_signer_1", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "designation": "Signer", "order": 1, "phone_number": "+1-555-0123", "company": "Acme Corp", "title": "Software Engineer" } ], "fields": [ { "recipient_id": "temp_signer_1", "type": "signature", "page": 1, "x": 100, "y": 500, "width": 200, "height": 50 }, { "recipient_id": "temp_signer_1", "type": "text", "page": 1, "x": 100, "y": 400, "width": 150, "height": 30, "variable_name": "phone_number", "required": true, "read_only": true } ], "settings": { "use_signing_order": true, "send_signing_email": true } }); 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 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`. 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`. CreateAndSendResponse: type: object properties: id: type: string format: uuid description: ID de la solicitud de firma name: type: string description: Nombre de la solicitud de firma description: type: string nullable: true description: Descripción de la solicitud de firma status: type: string enum: - sent description: Siempre 'sent' para este endpoint document_url: type: string format: uri description: URL firmada para acceder al documento page_count: type: integer description: Número de páginas del documento expiration_hours: type: integer description: Horas hasta la expiración settings: $ref: '#/components/schemas/SigningRequestSettings' created_date: type: string format: date-time sent_date: type: string format: date-time description: Cuándo se envió la solicitud template_id: type: string format: uuid nullable: true first_signer: type: object description: Detalles del primer firmante que recibió el email properties: id: type: string format: uuid name: type: string email: type: string format: email signing_link: type: string format: uri description: Enlace directo para que el firmante acceda a la vista de firma recipients: type: array description: Todos los destinatarios con UUIDs reales items: type: object properties: id: type: string format: uuid first_name: type: string last_name: type: string nullable: true name: type: string email: type: string format: email designation: type: string order: type: integer fields: type: array description: >- Todos los campos activos de la nueva solicitud de firma, incluidos los campos que pertenecen a participantes de sello. Cada elemento es el registro de campo almacenado, no la forma `Field` usada en las peticiones: por ejemplo, el tipo de campo está en `field_type`, y un campo propio de un sello no tiene destinatario y nombra a su participante de sello en `seal_participant_id`. items: type: object additionalProperties: true 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' credits_remaining: type: integer description: Créditos de la empresa restantes después de la deducción warnings: type: array items: type: string description: >- Advertencias opcionales no bloqueantes, incluidas propiedades de etiquetas de anclaje desconocidas durante la ventana de compatibilidad y advertencias de procesamiento de anclajes. description: Solicitud de firma creada y enviada required: - id - name - status CreateAndSendValidationError: type: object properties: error: type: string code: type: string description: Código de error legible por máquina example: VALIDATION_ERROR phase: type: string enum: - create_validation - send_validation description: Qué fase de validación falló validation_errors: type: array description: Errores de validación detallados de la fase de envío items: type: object properties: recipient_index: type: integer description: Índice del destinatario (basado en 1) recipient_email: type: string missing_fields: type: array items: type: string description: Lista de campos requeridos faltantes 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 description: Error de validación durante create-and-send required: - error - code InsufficientCreditsError: type: object properties: error: type: string example: >- Insufficient credits. Please purchase more credits to send signing requests. code: type: string example: INSUFFICIENT_CREDITS current_credits: type: integer example: 0 description: Error de créditos insuficientes required: - error - code - current_credits 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 CreateAndSendConflictError: description: >- Un 409 respondido por POST /signing-requests/create-and-send: un MultiDocumentError que además indica la solicitud de firma creada por esta llamada cuando esa solicitud se conservó (su reversión se rechazó con `SEND_EFFECTS_EXIST` o `ALREADY_SENT`). allOf: - $ref: '#/components/schemas/MultiDocumentError' - type: object properties: signing_request_id: type: string format: uuid description: >- Presente solo en SEND_EFFECTS_EXIST y ALREADY_SENT cuando la solicitud de firma creada por esta llamada se conservó (su reversión se rechazó): su id, para que quien llama pueda recuperarla en lugar de reintentar (un reintento crea una segunda solicitud). Ausente cuando la solicitud se revirtió. 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' UnprocessableEntityError: type: object properties: error: type: string example: A recipient's email address cannot receive messages. code: type: string example: RECIPIENT_EMAIL_SUPPRESSED description: Error de entidad no procesable required: - error - code 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. 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. 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. 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.