Firma.dev API v1.9.0: Verificación de OTP, Reemplazo de Documento de Plantilla y Actualizaciones de Esquema

v1.9.0 es una versión enfocada basada en v1.8.0, sin cambios incompatibles. Si ya estás integrado, nada se rompe. Ahora están disponibles dos nuevas capacidades cuando las necesites: verificación OTP por correo electrónico del firmante y sustitución del documento de plantilla.

Qué incluye v1.9.0

Ambos cambios son aditivos. No se eliminó ningún campo, no se cambió el comportamiento de ningún endpoint y no se requiere migración desde v1.8.0.

Nuevo: verificación OTP por correo electrónico del firmante

La configuración require_otp_verification añade un paso de verificación de identidad antes de que un firmante pueda acceder a un documento. Cuando se activa, los firmantes ven una pantalla de verificación al abrir su enlace de firma, reciben un código de 6 dígitos en su correo electrónico y deben introducirlo antes de que se cargue el documento.

La configuración es un campo de tres estados: true, false o null. Null significa heredar del nivel superior. La cadena de anulación va de empresa → espacio de trabajo → plantilla → solicitud de firma, siendo la solicitud de firma la de mayor prioridad.

Activar OTP a nivel de espacio de trabajo

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

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

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

Todas las solicitudes de firma en este espacio de trabajo ahora requieren OTP de forma predeterminada.

Desactivar OTP para una solicitud de firma específica

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

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

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

Esta solicitud omite OTP independientemente de la configuración del espacio de trabajo.

Cambios en el esquema

Nuevo: reemplazo del documento de plantilla

El nuevo POST /templates/{id}/replace-document endpoint permite sustituir el PDF subyacente de una plantilla manteniendo intactas todas las ubicaciones de campos, asignaciones de firmantes y configuraciones.

El documento de reemplazo debe cumplir dos requisitos de validación: el mismo número de páginas que el original y unas dimensiones de página dentro de una tolerancia de 1 pt. Estas restricciones existen para garantizar que las posiciones de los campos sigan siendo válidas después del intercambio. Si alguna comprobación falla, la API devuelve un 400 con un error claro.

const fs = require("fs");

const base64PDF = fs.readFileSync("./updated-contract.pdf").toString("base64");

const response = await fetch(
  `https://api.firma.dev/v1/templates/${templateId}/replace-document`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ document: base64PDF })
  }
);

const updatedTemplate = await response.json();

const fs = require("fs");

const base64PDF = fs.readFileSync("./updated-contract.pdf").toString("base64");

const response = await fetch(
  `https://api.firma.dev/v1/templates/${templateId}/replace-document`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ document: base64PDF })
  }
);

const updatedTemplate = await response.json();

const fs = require("fs");

const base64PDF = fs.readFileSync("./updated-contract.pdf").toString("base64");

const response = await fetch(
  `https://api.firma.dev/v1/templates/${templateId}/replace-document`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ document: base64PDF })
  }
);

const updatedTemplate = await response.json();

Casos de error:

Nuevos endpoints

Actualización desde v1.8.0

No es necesaria ninguna acción. Lista de comprobación:

• No se eliminó ningún campo de ningún objeto existente

• No hay cambios de comportamiento en los endpoints existentes

• require_otp_verification tiene como valor predeterminado null (hereda), por lo que las integraciones existentes no se ven afectadas hasta que lo establezcas explícitamente

• POST /templates/{id}/replace-document es un endpoint nuevo, no un sustituto de nada

La documentación completa de la API está en docs.firma.dev. El registro completo de cambios de la API está en docs.firma.dev/guides/api-changelog.

Obtén tu clave de API y empieza a construir gratis, no se requiere tarjeta de crédito.