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 estás integrado hoy, nada se rompe. Dos nuevas capacidades están ahora disponibles cuando las necesites: verificación de OTP por correo electrónico y Reemplazo de Documento en Plantilla.

Lo que hay en v1.9.0

Ambos cambios son aditivos. No se eliminaron campos, no se cambió el comportamiento de los puntos de conexión, no se requiere migración de v1.8.0.

Nuevo: Verificación de OTP por correo electrónico de firmante

La configuración require_otp_verification agrega un paso de verificación de identidad antes de que un firmante pueda acceder a un documento. Cuando está habilitado, 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 se cargue el documento.

La configuración es un campo de tres estados: true, false o null. Nulo significa heredar del nivel superior. La cadena de anulaciones se ejecuta empresa → espacio de trabajo → plantilla → solicitud de firma, donde la solicitud de firma tiene la mayor prioridad.

Habilitar OTP en el 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.

Anular OTP desactivado 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 de Esquema

Nuevo: Reemplazo de Documento de Plantilla

El nuevo punto de conexión POST /templates/{id}/replace-document te permite intercambiar el PDF subyacente en una plantilla mientras mantienes todas las ubicaciones de los campos, las asignaciones de firmantes y las configuraciones intactas.

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

Actualización de v1.8.0

No se requiere acción. La lista de verificación:

• No se eliminaron campos de ningún objeto existente

• No se producen cambios de comportamiento en los puntos de conexión existentes

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

• POST /templates/{id}/replace-document es un nuevo punto de conexión, no un reemplazo de algo

La documentación completa de API está en docs.firma.dev. El registro de cambios completo de 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.