Registro de Cambios de la API

​

Resumen de Versiones

​

v1.30.0

​

Recuperar las marcas del firmante como imágenes

• GET /signing-requests/{id}/signers/{signer_id}/signature — la firma adoptada por el firmante
• GET /signing-requests/{id}/signers/{signer_id}/initials — las iniciales adoptadas por el firmante
• GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id} — un sello para un campo de sello específico
• GET /signing-requests/{id}/signers/{signer_id}/files/{field_id} — un archivo que el firmante subió a un campo de archivo

​

Guía de Migración

​

v1.29.0

​

Subida de documentos en dos pasos

1. Llamar a POST /documents con los metadatos del archivo para recibir una URL de subida pre-firmada
2. Hacer PUT de los bytes del archivo directamente a la URL de subida (soporta hasta 50MB)
3. Pasar el document_id devuelto en tu solicitud POST /signing-requests o POST /signing-requests/create-and-send

​

Nuevo campo de solicitud: document_id

​

Aumento del límite de tamaño de documento

​

Guía de Migración

​

v1.28.0

​

Ejemplos de código del SDK de TypeScript

​

Cambios en la superficie de referencia

​

Guía de Migración

​

v1.27.0

​

Campos de configuración ahora documentados en las respuestas

​

Configuración de solicitud de firma

​

Configuración de plantilla

​

Respuestas de cancelación y reenvío

​

Nuevos esquemas

​

Guía de Migración

​

v1.26.0

​

Configuración del espacio de trabajo: cuatro nuevos campos

​

Estructura de anulaciones de etiquetas de botón

{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}

​

v1.25.2

​

Validación más estricta para las anulaciones de campos de plantilla

{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}

​

Tipos de campo sin distinción de mayúsculas y minúsculas

​

v1.25.1

​

Respuestas de error precisas para create-and-send

• 400 VALIDATION_ERROR — falló la validación de la solicitud o del envío (por ejemplo, a un firmante le falta información obligatoria); la respuesta incluye validation_errors, field_errors o details identificando qué corregir.
• 402 INSUFFICIENT_CREDITS — créditos insuficientes para enviar; current_credits informa el saldo.
• 422 RECIPIENT_EMAIL_SUPPRESSED (nuevo) — la dirección de correo de un destinatario está suprimida (previamente rebotada o marcada como spam) y no se le puede enviar.

​

v1.25.0

​

Colores de marca del editor

• color_accent — color de acento para resaltados, pestañas activas, interruptores y controles principales en el marco del editor.
• color_accent_fg — color de primer plano (texto/icono) mostrado sobre superficies de acento.
• color_canvas — el color del entorno del lienzo del documento detrás de la página.
• color_muted — color de superficie atenuada (separadores, estados de hover, pistas de interruptores).
• color_muted_fg — color de texto atenuado.

• GET/PUT /company/settings y GET/PUT /workspace/{workspace_id}/settings aceptan y devuelven los cinco nuevos campos. Cada uno es una cadena hexadecimal #rrggbb anulable; null significa heredar (espacio de trabajo → empresa → predeterminado de Firma).
• El objeto color_palette resuelto devuelto en los payloads del editor incrustado ahora contiene once claves (las seis existentes más accent, accent_fg, canvas, muted, muted_fg). Cuando no está establecido, muted toma como predeterminado el color card resuelto y muted_fg se deriva para garantizar la legibilidad, por lo que la paleta siempre está completamente poblada.

​

v1.24.0

​

Claves API de prueba del espacio de trabajo

• POST /workspaces ahora provisiona un par de claves live + test y devuelve tanto api_key (live) como el nuevo campo test_api_key.
• GET /workspaces/{id} y GET /workspaces ahora devuelven tanto api_key como test_api_key.
• POST /workspaces/{id}/api-key/regenerate y /api-key/expire aceptan un key_type opcional ("live" o "test", predeterminado "live"). Regenerar un tipo de clave ya no afecta al otro.
• Los espacios de trabajo existentes creados a través de la API se completan retroactivamente con una clave de prueba.

​

v1.23.0

​

Términos del Firmante

• Los endpoints GET listan los términos del firmante de empresa y de espacio de trabajo
• Los endpoints PUT crean o actualizan los términos del firmante por idioma a nivel de empresa y de espacio de trabajo
• Los endpoints DELETE eliminan los términos del firmante de empresa y de espacio de trabajo

​

Configuración de Empresa

​

Cambios de Esquema

• Esquema de configuración de empresa: se agregó require_terms_acceptance (boolean)
• Esquema de configuración de espacio de trabajo: se agregó require_terms_acceptance (boolean, anulable). Usa null para heredar la configuración de la empresa.

​

Guía de Migración

​

v1.22.1

​

Eliminación de dominio de correo

​

Guía de Migración

​

v1.22.0

​

Endpoint de Eliminación de Solicitud de Firma

• 200 con signing_request_id y deleted_on en caso de éxito
• 409 ALREADY_SENT si la solicitud de firma ya se ha enviado
• 404 si no se encuentra o ya se eliminó

​

Nuevo Evento de Webhook

• signing_request.deleted se dispara cuando una solicitud de firma se elimina a través de la API

​

Guía de Migración

​

v1.21.1

​

Gestión de Webhooks del Espacio de Trabajo

• webhook_enabled (boolean) - Habilita o deshabilita los webhooks a nivel de espacio de trabajo. Cuando se establece en true por primera vez, se genera automáticamente un secret de webhook.
• ignore_company_webhooks (boolean) - Si es true, los webhooks a nivel de empresa no se dispararán para eventos en este espacio de trabajo.

​

Cambios de Esquema

• Cuerpo de la solicitud de PATCH /workspaces/: se agregaron webhook_enabled (boolean, opcional) e ignore_company_webhooks (boolean, opcional)
• Respuesta de PATCH /workspaces/: ahora incluye webhook_enabled, webhook_secret, webhook_secret_rotated_at, webhook_secret_created_at e ignore_company_webhooks

​

Guía de Migración

​

v1.21.0

​

Nuevas Configuraciones

• email_local_part (string, anulable) - Personaliza la parte local (antes del @) de los correos de firma salientes cuando se usa un dominio personalizado verificado. Disponible en dos niveles:
  • Configuración de Empresa (GET/PATCH /company) - Establece el valor predeterminado para todos los espacios de trabajo. Cadena con valor predeterminado "support".
  • Configuración de Espacio de Trabajo (GET/PUT /workspace/{id}/settings) - Anula el valor predeterminado de la empresa. Cadena anulable (null hereda de la empresa).

​

Cambios de Esquema

• Esquema de Company: se agregó email_local_part (string, predeterminado "support")
• Esquema de configuración de espacio de trabajo: se agregó email_local_part (string, anulable)

​

Guía de Migración

​

v1.20.0

​

Nuevas Configuraciones

• disable_guided_navigation (boolean, anulable) - Deshabilita el desplazamiento automático al siguiente campo obligatorio durante la firma. Disponible en cuatro niveles:
  • Configuración de Empresa (GET/PUT /company/settings) - Establece el valor predeterminado para todos los espacios de trabajo. Boolean (no anulable).
  • Configuración de Espacio de Trabajo (GET/PUT /workspace/{id}/settings) - Anula el valor predeterminado de la empresa. Boolean o null (null hereda de la empresa).
  • Plantilla (POST/PATCH /templates) - Se copia a las solicitudes de firma creadas a partir de esta plantilla. Boolean o null.
  • Solicitud de Firma (POST/PATCH /signing-requests) - Anulación de mayor prioridad. Boolean o null (null hereda del espacio de trabajo/empresa).

​

Cambios de Esquema

• Esquema de configuración de empresa: se agregó disable_guided_navigation (boolean)
• Esquema de configuración de espacio de trabajo: se agregó disable_guided_navigation (boolean, anulable)
• Esquema de configuración de plantilla: se agregó disable_guided_navigation (boolean, anulable)
• Esquema de configuración de solicitud de firma: se agregó disable_guided_navigation (boolean, anulable)

​

Guía de Migración

​

v1.19.0

​

Nuevos Endpoints

• POST /company/logo - Sube una imagen de logotipo de empresa (PNG o JPEG, máximo 2MB). El logotipo aparece en los certificados de firma y correos electrónicos.
• DELETE /company/logo - Elimina el logotipo de la empresa. Los certificados recurren al predeterminado de Firma.
• POST /workspaces/{id}/logo - Sube un logotipo específico del espacio de trabajo que anula el logotipo de la empresa para ese espacio de trabajo.
• DELETE /workspaces/{id}/logo - Elimina el logotipo del espacio de trabajo. Recurre al logotipo de la empresa.

​

Cambios de Esquema

• El esquema de Workspace ahora incluye icon_url (string, anulable) - una URL públicamente accesible a la imagen del logotipo del espacio de trabajo
• icon_url de Company ahora es de solo lectura en las solicitudes PATCH/PUT. Usa el nuevo endpoint POST /company/logo para gestionar los logotipos.

​

Guía de Migración

• Si establecías icon_url directamente mediante PATCH /company o PATCH /workspaces/{id}, cambia a los nuevos endpoints POST .../logo en su lugar. El campo icon_url ya no se acepta en los cuerpos de solicitud de actualización.
• icon_url en las respuestas GET ahora devuelve una URL públicamente accesible en lugar de una referencia interna.

​

v1.18.0

​

Nuevas Funcionalidades

​

Campos Editables de Identidad

• null - usar el predeterminado de la solicitud
• [] - deshabilitado para este firmante
• ["name", "company"] - campos personalizados para este firmante

{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}

​

Campos de Datos Precompletados Editables

• Campos de plantilla (PATCH /templates/{id}, PUT /templates/{id})
• Campos de solicitud de firma (POST /signing-requests, POST /signing-requests/create-and-send)
• Objetos de respuesta de campo (GET /signing-requests/{id})

{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}

​

Validación del Origen del Valor de Campo

• POST /signing-requests
• POST /signing-requests/create-and-send
• PATCH /templates/{id} (creación y actualización de campos)
• PUT /templates/{id} (upsert de campos)

​

Precedencia de Valores

​

Guía de Migración

• La edición de identidad está deshabilitada de forma predeterminada (identity_editable_fields: null). Establécela en un array de claves de campo para habilitarla.
• Los campos de datos precompletados existentes permanecen bloqueados (de solo lectura) de forma predeterminada. Establece prefilled_editable: true en format_rules para hacerlos editables.

​

v1.17.0

​

Nuevas Funcionalidades

​

Personalización de Color para la Experiencia de Firma

​

Esquema ColorPalette

​

Guía de Migración

• Los seis campos de color son null de forma predeterminada, lo que preserva la apariencia predeterminada existente de Firma.
• Para personalizar los colores, establece valores hexadecimales en la configuración de la empresa (predeterminados para toda la empresa) o en la configuración del espacio de trabajo (anulaciones por espacio de trabajo).
• La cascada de colores es: predeterminados de Firma -> anulaciones de empresa -> anulaciones de espacio de trabajo. Cada nivel solo anula los campos que están explícitamente establecidos (no nulos).

​

v1.16.0

​

Nuevas Funcionalidades

​

Descarga del Documento de la Solicitud de Firma

​

Configuración de Marca de Agua de Descarga Parcial

​

Guía de Migración

• El endpoint de descarga es puramente opcional. No cambia ningún comportamiento existente.
• Llama a GET /signing-requests/{id}/download — maneja 503 con Retry-After hasta que el documento esté listo.

​

v1.15.3

​

Alias de campos limpios para GET /signing-requests//fields

​

Guía de migración

// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true

​

v01.15.02

​

Corrección de Errores

​

Tipos de Campo de Create-and-Send Ampliados

• dropdown (con la propiedad dropdown_options)
• radio_buttons
• text_area
• url
• file

• POST /signing-requests/create-and-send — enum fields[].type

​

v01.15.01

​

Corrección de Errores

​

Enum de Idioma Actualizado

• PUT /workspace/{workspace_id}/settings — campo language
• PUT /company y PATCH /company — campo language
• GET /email-templates/defaults — parámetro de consulta language

​

v01.15.00

​

Nuevas Funcionalidades

​

Webhooks con Alcance de Espacio de Trabajo

• Parámetro workspace_id en la creación de webhooks — Pasa un workspace_id opcional al crear un webhook para limitarlo a un espacio de trabajo específico. Omitirlo crea un webhook a nivel de empresa (comportamiento existente).
• Filtro workspace_id en el listado de webhooks — Filtra la lista de webhooks por espacio de trabajo. Cuando se omite, solo se devuelven los webhooks a nivel de empresa.
• Campo de espacio de trabajo ignore_company_webhooks — Los espacios de trabajo pueden excluirse de recibir eventos de webhook a nivel de empresa estableciendo este indicador en true.

​

Gestión de Secretos de Webhook de Espacio de Trabajo

• POST /workspaces/{id}/webhooks/rotate-secret — Genera un nuevo secret de firma de webhook para el espacio de trabajo. El secreto anterior sigue siendo válido durante un período de gracia de 7 días.
• GET /workspaces/{id}/webhooks/secret-status — Devuelve el estado del secret de webhook del espacio de trabajo, incluyendo fecha de creación, fecha de rotación e información del período de gracia.

​

Campos de Webhook en la Respuesta del Espacio de Trabajo

• webhook_enabled — Si los webhooks a nivel de espacio de trabajo están habilitados
• webhook_secret — El secret de firma de webhook actual
• webhook_secret_created_at — Cuándo se creó el secret actual
• webhook_secret_rotated_at — Cuándo se rotó el secret por última vez
• ignore_company_webhooks — Si el espacio de trabajo ignora los eventos de webhook a nivel de empresa

​

Cambios

• Se agregó el parámetro opcional workspace_id a POST /webhooks y GET /webhooks
• Se agregaron 5 nuevos campos al esquema Workspace: webhook_enabled, webhook_secret, webhook_secret_created_at, webhook_secret_rotated_at, ignore_company_webhooks
• Se agregaron 2 nuevos endpoints: POST /workspaces/{id}/webhooks/rotate-secret, GET /workspaces/{id}/webhooks/secret-status
• Se aplicó protección SSRF a la validación de URL de webhook

​

Guía de Migración

• Los webhooks a nivel de empresa siguen siendo el predeterminado. El parámetro workspace_id es opcional tanto en la creación como en el listado.
• Los webhooks existentes no se ven afectados. Los nuevos campos de espacio de trabajo en la respuesta de espacio de trabajo son predeterminadamente webhook_enabled: false e ignore_company_webhooks: false.
• Para adoptar los webhooks de espacio de trabajo, crea un webhook con un workspace_id y luego usa el endpoint de rotación de secret del espacio de trabajo para generar un secret de firma para ese espacio de trabajo.

​

v01.14.00

​

Nuevas Funcionalidades

​

Designaciones de Destinatario

• Signer — Firma el documento (comportamiento existente, sigue siendo el predeterminado)
• Approver — Aprueba el documento usando campos específicos de aprobación. Los aprobadores no firman pero deben completar todos los campos de aprobación asignados antes de que la solicitud pueda finalizar.
• CC — Recibe una copia completada del documento firmado. Los destinatarios en CC no pueden firmar ni tener campos asignados.

​

Tipos de Campo de Aprobación

• approval_signature — Un sello de aprobación colocado por el aprobador
• approval_checkmark — Una casilla de aprobación
• approval_date — Fecha auto-completada cuando el aprobador aprueba

​

Destinatarios CC

​

Cambios

• Se amplió el enum designation de ["Signer"] a ["Signer", "Approver", "CC"] en 7 esquemas
• Se agregaron approval_signature, approval_checkmark y approval_date a los enums de tipo de campo en 10 esquemas

​

Guía de Migración

• Los nuevos valores de designation son opcionales. Omitir el campo designation usa "Signer" de forma predeterminada, preservando el comportamiento existente.
• Los nuevos tipos de campo son aditivos. Todos los valores de tipo de campo existentes siguen siendo válidos y sin cambios.
• Si integras flujos de aprobación, asigna la designación "Approver" a los destinatarios relevantes y usa los tipos de campo approval_* para sus campos.

​

v01.13.00

​

Nuevas Funcionalidades

​

Tipo de Campo de Sello

​

Cambios

• Se agregó stamp a los enums de tipo de campo en todos los esquemas relacionados con campos (plantillas, solicitudes de firma, create-and-send)
• Se actualizaron las descripciones de tipo de campo para documentar el comportamiento del sello

​

Guía de Migración

• Si creas campos a través de la API, ahora puedes usar "stamp" como tipo de campo. Los campos de sello deben establecerse como read_only: true con la imagen del sello como una URL de datos PNG en read_only_value.
• Los campos de sello también son compatibles con las etiquetas de anclaje. Al usar etiquetas de anclaje, la imagen del sello debe proporcionarse mediante read_only_value como una URL de datos PNG.

​

v01.12.01

​

Nuevas Funcionalidades

​

variable_defined_name en las Respuestas de Campo

• GET /templates (lista y único)
• GET /templates/{id}/fields
• POST /templates/{id}/replace-document
• GET /signing-requests (lista)
• GET /signing-requests/{id}/fields
• GET /documents (legado)

{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}

​

variable_defined_name como Entrada para la Coincidencia de Campos

{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}

​

Sin Cambios Importantes

​

v01.12.00

​

Nuevas Funcionalidades

​

Integración con Servidor MCP

• Autenticación con clave API a través del encabezado Authorization
• OAuth 2.1 con PKCE para clientes basados en navegador (Claude.ai, Claude Desktop)

• Espacios de trabajo — listar, crear, obtener, actualizar
• Plantillas — CRUD completo, duplicar, ver campos/usuarios/recordatorios
• Solicitudes de Firma — CRUD completo, enviar, cancelar, reenviar, registros de auditoría
• Webhooks — CRUD completo, prueba de entrega
• Empresa — ver y actualizar información de la empresa

​

Sin Cambios Importantes

​

v01.11.00

​

Nuevas Funcionalidades

​

Tipo de Campo de Subida de Archivos

• Los firmantes pueden subir imágenes (JPG, PNG) y/o archivos PDF según la configuración
• Los archivos se validan por bytes mágicos, no solo por la extensión del archivo
• Tamaño máximo de archivo: 10MB

{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}

​

Etiquetas de Anclaje para la Colocación Automática de Campos

• Hasta 100 etiquetas de anclaje por solicitud
• Solo disponible para la creación basada en documentos (no basada en plantillas)
• Los campos creados a partir de etiquetas de anclaje se agregan junto a cualquier campo especificado manualmente

{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}

​

Color de Fondo de Campo

​

Cambios de Esquema

​

Nuevos Esquemas

​

Field / TemplateField / SigningRequestField

​

Enum de Tipo de Campo

• Se agregó file a la lista de tipos de campo aceptados

​

format_rules

• Ahora acepta FileFormatRules (con acceptedFileTypes) además de DateFormatRules y el texto a mostrar de URL

​

Creación de Solicitud de Firma

​

Cambios Importantes

​

Cambio del Valor Predeterminado de use_signing_order

​

Guía de Migración

​

v01.10.00

​

Nuevas Funcionalidades

​

Lógica de Campo Condicional

• required_conditions — Cuando se establece, anula el indicador estático required. El campo es obligatorio solo cuando las condiciones se evalúan como verdaderas según los valores de otros campos.
• visibility_conditions — Cuando se establece, el campo se oculta a menos que las condiciones se evalúen como verdaderas. Los campos ocultos no se validan al enviar.

{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}

​

Soporte de Documentos DOCX

• Creación de plantilla (POST /templates)
• Reemplazo de documento de plantilla (POST /templates/{id}/replace-document)
• Creación de solicitud de firma (POST /signing-requests)
• Actualizaciones de plantilla/solicitud de firma (PUT y PATCH)

​

Endpoint de Registro de Auditoría

​

Control del Marco de Firma

• true — Mostrar el marco de firma con el ID de Firma
• false — Ocultar el marco de firma
• null — Heredar del nivel padre

​

Forzar la Eliminación de Condiciones al Eliminar Usuarios

• false (predeterminado) — La solicitud se rechaza con un error que lista los campos dependientes
• true — Elimina automáticamente las referencias de condición y procede con la eliminación

​

Cambios de Esquema

​

Field

​

Nuevos Esquemas

​

SigningRequestSettings / WorkspaceSettings / Company

​

Eliminación de Usuario de Plantilla y Solicitud de Firma

​

Nuevos Endpoints

​

Guía de Migración

• Las propiedades de campo condicional son predeterminadamente null (sin condiciones)
• show_signature_frame es predeterminadamente null (heredar, que está habilitado de forma predeterminada)
• force_remove_conditions es predeterminadamente false (preservando el comportamiento de rechazo existente)
• El soporte DOCX es transparente: las subidas de PDF existentes siguen funcionando sin cambios
• El endpoint de registro de auditoría es puramente aditivo

​

v01.09.00

​

Nuevas Funcionalidades

​

Verificación OTP por Correo Electrónico

• true — Requerir verificación OTP antes de acceder al documento
• false — No requerir verificación OTP
• null — Heredar del nivel padre (espacio de trabajo → empresa, solicitud de firma → espacio de trabajo)

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}

PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}

​

Reemplazar Documento de Plantilla

• El documento de reemplazo debe tener el mismo número de páginas que el original
• Las dimensiones de página deben coincidir dentro de una tolerancia de 1pt
• El documento debe proporcionarse como un PDF codificado en base64

POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}

​

Cambios de Esquema

​

SigningRequestSettings

​

WorkspaceSettings

​

Nuevos Endpoints

​

Guía de Migración

​

v01.08.00

​

Nuevas Funcionalidades

​

API de Plantillas de Correo

PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}

​

Soporte de Idiomas

​

Cambios de Esquema

​

Correcciones de Marca de Tiempo

​

Esquema Company

​

Esquema Template (Ampliado)

​

Formas de Respuesta de Solicitud de Firma

​

SigningRequestSettings

​

Esquema Reminder

​

Esquema Webhook

​

SendSigningRequestResponse (Corregido)

​

WorkspaceSettings

​

v01.07.00

​

Nuevas Funcionalidades

​

Firmas Solo Manuscritas

• Creación de solicitudes de firma (POST /signing-requests)
• Creación y envío de solicitudes de firma (POST /signing-requests/create-and-send)
• Actualizaciones completas (PUT /signing-requests/{id})
• Actualizaciones parciales (PATCH /signing-requests/{id})
• Creación y actualización de plantillas

{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}

​

Cambios de Esquema

​

Campos de Configuración Heredados Obsoletos

​

Guía de Migración

​

v01.06.00

​

Nuevas Funcionalidades

​

Descargas de PDF Divididas

• Solo disponible cuando la funcionalidad de PDF dividido se ha aplicado a la solicitud de firma
• Las URL expiran después de 1 hora: vuelve a obtener la solicitud de firma para obtener una URL nueva
• Los campos de error devuelven "file_not_accessible" si la ruta del archivo existe pero el archivo falta

{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}

​

Cambios de Esquema

​

Normalización de Tipo de Campo

​

Guía de Migración

​

v01.05.00

​

Nuevas Funcionalidades

​

Advertencias de Validación de Correo Electrónico

{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}

• Las advertencias no son bloqueantes: la solicitud sigue teniendo éxito
• Útil para marcar posibles errores tipográficos o dominios de correo inválidos
• Verifica el campo warnings o warning en la respuesta para mostrar esto a los usuarios

​

Guía de Migración

​

v01.04.00

​

Nuevas Funcionalidades

​

Nuevos Tipos de Campo

• Se establece automáticamente en read_only: true
• Usa read_only_value para establecer la URL de destino
• Usa format_rules.urlDisplayText para personalizar el texto mostrado

{
  "field": {
    "type": "url",
    "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
    "page_number": 1,
    "read_only_value": "https://example.com/terms",
    "format_rules": { "urlDisplayText": "View Terms & Conditions" }
  }
}

​

Operaciones PATCH de Campo

• Ahora puede actualizar propiedades, un solo usuario, O un solo campo
• Incluye el objeto field en el cuerpo de la solicitud
• Incluye field.id para actualizar un campo existente, omítelo para crear uno nuevo

• Ahora puede actualizar propiedades, un solo destinatario, O un solo campo
• Misma estructura de objeto de campo que las plantillas

{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

​

Coincidencia de Usuario de Plantilla para Destinatarios

{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}

• template_user_id es el método preferido para la coincidencia
• order sigue disponible como alternativa

​

Cambios de Esquema

​

Enum de Tipo de Campo

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]

​

Esquema Recipient

• La creación de solicitud de firma ahora usa la referencia del esquema Recipient compartido
• Se agregó la propiedad template_user_id para la coincidencia explícita de usuario de plantilla

​

v01.03.00

​

Nuevas Funcionalidades

​

API de Dominios de Correo

• GET /company/domains - Listar todos los dominios de correo de la empresa
• POST /company/domains - Agregar un nuevo dominio de correo
• GET /company/domains/{id} - Obtener detalles del dominio
• DELETE /company/domains/{id} - Eliminar un dominio
• POST /company/domains/{id}/verify-ownership - Verificar la propiedad del dominio mediante un registro TXT
• POST /company/domains/{id}/finalize - Completar la configuración del dominio con el proveedor de correo
• POST /company/domains/{id}/verify-dns - Verificar los registros SPF, DKIM, DMARC
• POST /company/domains/{id}/set-primary - Establecer el dominio de envío principal

• Domain - Configuración de dominio de correo con estado de verificación
• DomainDnsRecord - Detalles del registro DNS para la verificación del dominio

​

Seguimiento del Coste en Créditos

• Se agregó el campo credit_cost al esquema Template - Número de créditos consumidos al enviar
• Se agregó el campo credit_cost al esquema SigningRequest - Créditos consumidos al enviar

​

Estado Rechazado de la Solicitud de Firma

• Se agregó declined a los valores del enum SigningRequest.status
• Se agregó el campo date_declined al esquema SigningRequest

​

Mejoras de Esquema

​

Campos de Plantilla

• Se agregó el campo date_default para establecer valores de fecha predeterminados (formato ISO 8601)
• Descripción mejorada de multi_group_id: explica la agrupación mutuamente excluyente de campos para casillas de verificación/botones de radio
• Se agregó una aclaración de que page_number comienza en 1 y no debe exceder el número de páginas del documento

​

Campos de Solicitud de Firma

• Descripción mejorada de multi_group_id con las mismas mejoras que los campos de plantilla

​

v01.02.00

​

Información de Usuario Mejorada

​

Mejoras del Esquema TemplateUser

• first_name - Nombre del destinatario
• last_name - Apellido del destinatario
• phone_number - Número de teléfono de contacto
• street_address - Dirección
• city - Ciudad
• state_province - Estado o provincia
• postal_code - Código postal
• country - País
• title - Cargo
• company - Nombre de la empresa

​

Indicadores de Listo para Enviar

• required_fields - Lista de campos de datos de destinatario obligatorios según la configuración de la plantilla
• missing_fields - Lista de campos obligatorios que actualmente están vacíos
• required_read_only_fields - Campos de solo lectura que necesitan valores precompletados
• ready_to_send - Booleano que indica si el destinatario tiene todos los datos obligatorios

​

Mejoras del Esquema SigningRequestUser

• declined_on - Marca de tiempo de cuándo el destinatario rechazó firmar
• decline_reason - Motivo proporcionado por el destinatario para rechazar
• custom_fields - Valores de campo personalizado para el destinatario
• Propiedad has_value en required_read_only_fields - Indica si el campo de solo lectura tiene un valor

​

Cambios en el Formato de Respuesta

{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}

​

v01.01.00

​

Nuevos Endpoints

​

Gestión de Plantillas

• POST /templates - Crear una nueva plantilla con PDF codificado en base64
• PATCH /templates/{id} - Actualización parcial (propiedades O un solo usuario)
• PUT /templates/{id} - Actualización completa (propiedades, usuarios, campos, recordatorios)
• DELETE /templates/{id} - Eliminación suave de una plantilla

​

Sub-Recursos de Plantilla

• GET /templates/{id}/users - Obtener todos los destinatarios de la plantilla
• GET /templates/{id}/fields - Obtener todos los campos de la plantilla
• GET /templates/{id}/reminders - Obtener todos los recordatorios de la plantilla

​

Gestión de Claves API

• POST /workspaces/{id}/api-key/regenerate - Generar una nueva clave API con un período de gracia de 24 horas
• POST /workspaces/{id}/api-key/expire - Expirar inmediatamente las claves pendientes

​

Operaciones Mejoradas

​

Actualizaciones Completas

• template_properties - Actualizar metadatos y configuración
• users - Upsert de usuarios (incluye id para actualizar, omítelo para crear)
• deleted_users - Eliminar usuarios con estrategia de manejo de campos (delete o reassign)
• fields - Upsert de campos
• reminders - Upsert de recordatorios

{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}

​

v01.00.02

​

Nuevas Funcionalidades

​

API de Campos Personalizados

• Custom Fields - Gestión de definiciones de campo personalizado

WorkspaceCustomField

{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}

TemplateCustomField

{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}

SigningRequestCustomField

{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}

​

Mejoras de Esquema

​

Esquema TemplateField

• Propiedad type explícita con valores enum
• Objeto position con x, y, width, height
• read_only y read_only_value para campos precompletados

​

v01.00.01

​

Versión Inicial

​

Etiquetas / Categorías de la API

• Company - Información y configuración de la empresa
• Workspaces - Operaciones de gestión de espacios de trabajo
• Templates - Operaciones de gestión de plantillas
• Signing Requests - Operaciones de solicitud de firma de documentos
• Webhooks - Configuración y gestión de webhooks
• JWT Management - Generación y revocación de tokens JWT
• Legacy - Endpoints obsoletos por compatibilidad con versiones anteriores

​

Autenticación

• Autenticación con clave API mediante el encabezado Authorization
• Soporte opcional de prefijo Bearer

​

Límite de Solicitudes

• Operaciones de lectura (GET): 200 solicitudes/minuto
• Operaciones de escritura (POST/PUT/PATCH/DELETE): 120 solicitudes/minuto
• CRUD de Webhook: 60 solicitudes/minuto
• Prueba de Webhook: 10 solicitudes/minuto
• Operaciones de clave API: 1 solicitud/minuto
• Rotación de secretos: 1 solicitud/minuto

​

Esquemas Principales

Company

• id, company_name, account_owner, account_owner_email
• website, icon_url, credits (solo lectura)
• date_created, date_changed

Workspace

• id, name, protected, api_key
• date_created, date_changed

Template

• id, name, description
• document_url (pre-firmada, expira)
• document_url_expires_at
• date_created, date_changed

SigningRequest

• id, name, description
• document_url, document_url_expires_at
• document_page_count, status, expiration_hours
• settings, template_id
• Campos de fecha: date_created, date_sent, date_finished, date_cancelled, expires_at
• Objeto certificate con estado de generación
• final_document_download_url, final_document_download_error

Recipient

• Principal: id, first_name, last_name, email, designation, order
• Dirección: street_address, city, state_province, postal_code, country
• Profesional: phone_number, title, company
• custom_fields para datos adicionales
• Soporte de ID temporal para la creación basada en documentos

Field

• id, type, position, page_number, required
• recipient_id, variable_name
• Específico del tipo: dropdown_options, date_default, date_signing_default
• Solo lectura: read_only, read_only_value, prefilled_data
• Formato: format_rules, validation_rules

Webhook

• id, url, events, enabled
• date_created, date_changed

​

Gestión JWT

• Generar JWT para la incrustación de plantillas
• Generar JWT para la incrustación de solicitudes de firma
• Revocar tokens JWT

​

Guía de Migración

​

Migración de v01.00.01 a v01.00.02

• Sin cambios importantes
• API de Campos Personalizados disponible para su uso

​

Migración de v01.00.02 a v01.01.00

• Sin cambios importantes
• Nuevos endpoints de gestión de plantillas disponibles
• Endpoints de regeneración de clave API disponibles

​

Migración de v01.01.00 a v01.02.00

• Sin cambios importantes
• Los usuarios de plantilla y de solicitud de firma ahora incluyen campos adicionales
• Booleano ready_to_send disponible para verificar la preparación del destinatario

​

Migración de v01.02.00 a v01.03.00

• Sin cambios importantes
• Configuración de dominio de correo disponible para dominios de envío personalizados
• Estado declined agregado al enum de estado de la solicitud de firma
• Seguimiento del coste en créditos disponible en plantillas y solicitudes de firma

​

Migración de v01.03.00 a v01.04.00

• Sin cambios importantes
• El tipo de campo radio se renombró a radio_buttons (ambos siguen siendo aceptados)
• Nuevos tipos de campo disponibles: textarea, url
• Los endpoints PATCH ahora admiten operaciones de campo único
• Usa template_user_id para la coincidencia explícita de usuario de plantilla en solicitudes de firma

​

Migración de v01.04.00 a v01.05.00

• Sin cambios importantes
• Las advertencias de validación de correo electrónico son puramente aditivas

​

Migración de v01.05.00 a v01.06.00

• Sin cambios importantes
• URL de descarga de PDF dividido disponibles en solicitudes de firma completadas
• Las entradas de tipo de campo initials/initial y textarea/text_area se aceptan ambas con normalización automática

​

Migración de v01.06.00 a v01.07.00

• Sin cambios importantes
• Nueva configuración hand_drawn_only disponible en la configuración de solicitud de firma (predeterminado false)
• Los campos enteros obsoletos de nivel superior ahora son visibles en el esquema SigningRequest: usa el objeto settings en su lugar

​

Migración de v01.07.00 a v01.08.00

• Sin cambios importantes: las correcciones de nombres de campo del esquema reflejan las respuestas reales de la API
• Nueva API de Plantillas de Correo para personalizar los correos de notificación de firma
• Campo language agregado a Company y WorkspaceSettings
• Esquema Template ampliado con recipients, fields, settings, page_count, expiration_hours en línea
• use_signing_order agregado a SigningRequestSettings
• El esquema Webhook incluye description, consecutive_failures, auto_disabled_at
• Las respuestas de solicitud de firma se dividieron en formas específicas por endpoint con datos en línea

​

Migración de v01.08.00 a v01.09.00

• Sin cambios importantes
• Nueva configuración require_otp_verification disponible a nivel de empresa, espacio de trabajo y solicitud de firma
• Nuevo endpoint POST /templates/{id}/replace-document para reemplazar los PDF de plantilla preservando los campos

​

Migración de v01.09.00 a v01.10.00

• Sin cambios importantes
• Lógica de campo condicional disponible mediante required_conditions y visibility_conditions en los campos
• Ahora se aceptan archivos DOCX junto con PDF en todos los endpoints de subida de documentos
• Nuevo endpoint GET /signing-requests/{id}/audit para recuperar registros de auditoría
• Nueva configuración show_signature_frame a nivel de empresa, espacio de trabajo y solicitud de firma
• Nuevo parámetro force_remove_conditions en las operaciones de eliminación de usuario

​

Migración de v01.10.00 a v01.11.00

• Cambio importante: el valor predeterminado de use_signing_order cambió de false a true; establece explícitamente use_signing_order: false si dependes de la entrega simultánea
• Nuevo tipo de campo file para las subidas de archivos del firmante
• Etiquetas de anclaje para la colocación automática de campos a partir de marcadores de texto en PDF
• Propiedad background_color disponible en todos los tipos de campo

​

Migración de v01.11.00 a v01.12.00

• Sin cambios importantes
• Integración con servidor MCP para el acceso de asistentes de IA a la API de Firma
• Sin nuevos endpoints de API ni cambios de esquema: la especificación OpenAPI no ha cambiado desde v1.11.0

​

Migración de v01.12.00 a v01.12.01

• Sin cambios importantes
• Nuevo campo variable_defined_name en todas las respuestas de campo: devuelve el nombre legible por humanos de la definición de campo personalizado junto al variable_name interno
• variable_defined_name aceptado como entrada para la coincidencia de campos en POST /signing-requests/create-and-send

​

Migración de v01.15.03 a v01.16.00

• Sin cambios importantes
• Nuevo endpoint GET /signing-requests/{id}/download para recuperar una URL de descarga del documento firmado
• Descargas parciales disponibles cuando allow_partial_download está habilitado en la configuración de solicitud de firma

​

Migración de v01.16.00 a v01.17.00

• Sin cambios importantes
• Seis nuevos campos de color anulables (color_primary, color_primary_fg, color_background, color_foreground, color_card, color_border) en Company y Workspace Settings
• Nuevo esquema ColorPalette para los colores resueltos de la experiencia de firma
• Los colores siguen una cascada de 3 niveles: predeterminados de Firma -> Empresa -> Espacio de Trabajo

​

Migración de v1.19.0 a v1.20.0

• Sin cambios importantes
• Nueva configuración disable_guided_navigation disponible a nivel de empresa, espacio de trabajo, plantilla y solicitud de firma
• Sigue el mismo patrón de cascada que require_otp_verification: solicitud de firma -> espacio de trabajo -> empresa (el primer valor no nulo gana)
• Predeterminado false (desplazamiento automático habilitado), preservando el comportamiento existente

​

Migración de v1.20.0 a v1.21.0

• Sin cambios importantes
• Nueva configuración email_local_part en Company (GET/PATCH /company) y Workspace Settings (GET/PUT /workspace/{id}/settings)
• El valor del espacio de trabajo tiene prioridad sobre el valor de la empresa; el predeterminado es "support"
• Solo aplica cuando hay un dominio personalizado verificado configurado