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 construida sobre v1.8.0 sin cambios disruptivos. Si hoy estás integrado, nada se rompe. Dos nuevas capacidades están ahora disponibles cuando las necesites: Verificación OTP por correo electrónico del firmante y Reemplazo de Documento de Plantilla.

¿Qué incluye v1.9.0?

Ambos cambios son aditivos. No se eliminaron campos, no se cambió el comportamiento del endpoint, no se requiere migración desde v1.8.0.

Nuevo: Verificación OTP de 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 está habilitada, 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 ingresarlo antes de que el documento se cargue.

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

Habilitar OTP al 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 por defecto.

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 de Documento de Plantilla

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

El documento de reemplazo debe cumplir con dos requisitos de validación: mismo número de páginas que el original y dimensiones de página dentro de una tolerancia de 1pt. Estas restricciones existen para asegurar que las posiciones de los campos sigan siendo válidas después del intercambio. Si alguna verificació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 se requiere acción. La lista de verificación:

• No se eliminaron campos de ningún objeto existente

• No se hicieron cambios en el comportamiento de los endpoints existentes

• require_otp_verification predetermina a null (hereda), de modo que las integraciones existentes no se ven afectadas hasta que lo configures explícitamente

• POST /templates/{id}/replace-document es un nuevo endpoint, no un reemplazo 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 API y comienza a construir gratis, no se requiere tarjeta de crédito.