Firma.dev API v1.9.0: Verificação OTP, Substituição de Documento de Modelo e Atualizações de Esquema

v1.9.0 é uma versão focada construída sobre a v1.8.0 sem alterações disruptivas. Se está integrado hoje, nada fica quebrado. Duas novas funcionalidades estão agora disponíveis quando precisar delas: verificação OTP de Email do Assinante e Substituição de Documento de Modelo.

O que há na v1.9.0

Ambas as alterações são aditivas. Nenhum campo foi removido, nenhum comportamento de endpoint foi alterado, nenhuma migração é necessária da v1.8.0.

Novo: Verificação OTP de Email do Assinante

A configuração require_otp_verification adiciona um passo de verificação de identidade antes de um assinante poder aceder a um documento. Quando ativada, os assinantes veem uma tela de verificação ao abrir o seu link de assinatura, recebem um código de 6 dígitos no seu email, e devem inseri-lo antes do documento carregar.

A configuração é um campo de estado triplo: true, false, ou null. Nulo significa herdar do nível acima. A cadeia de subscrição executa-se por empresa → espaço de trabalho → modelo → pedido de assinatura, sendo o pedido de assinatura o de maior prioridade.

Ativar OTP ao nível do espaço de trabalho

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
  }
}

Todos os pedidos de assinatura neste espaço de trabalho agora requerem OTP por padrão.

Sobrescrever OTP desligado para um pedido de assinatura específico

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
  }
}

Este pedido ignora OTP independentemente das configurações do espaço de trabalho.

Alterações no Esquema

Novo: Substituir Documento de Modelo

O novo endpoint POST /templates/{id}/replace-document permite trocar o PDF subjacente num modelo enquanto mantém todas as posições de campo, atribuições de assinante e configurações intactas.

O documento de substituição deve satisfazer dois requisitos de validação: mesma contagem de páginas que o original e dimensões da página dentro de uma tolerância de 1pt. Estas restrições existem para garantir que as posições dos campos permanecem válidas após a troca. Se qualquer uma das verificações falhar, a API devolve um 400 com um erro 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 erro:

Novos Endpoints

Atualizando da v1.8.0

Nenhuma ação necessária. A checklist:

• Nenhum campo removido de qualquer objeto existente

• Nenhuma alteração de comportamento para endpoints existentes

• require_otp_verification por padrão é null (herda), então as integrações existentes não são afetadas até que a defina explicitamente

• POST /templates/{id}/replace-document é um novo endpoint, não uma substituição de nada

A documentação completa da API está em docs.firma.dev. O changelog completo da API está em docs.firma.dev/guides/api-changelog.

Obtenha sua chave de API e comece a construir gratuitamente, sem necessidade de cartão de crédito.