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

v1.9.0 é um lançamento focado construído sobre v1.8.0 sem alterações de compatibilidade. Se você está integrado hoje, nada quebra. Duas novas capacidades estão agora disponíveis quando você precisar: Verificação OTP por E-mail do Assinante e Substituição de Documento de Modelo.

O que está 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 por E-mail do Assinante

A configuração require_otp_verification adiciona uma etapa de verificação de identidade antes que um assinante possa acessar um documento. Quando ativado, os assinantes veem uma tela de verificação ao abrir o link de assinatura, recebem um código de 6 dígitos por e-mail e devem inseri-lo antes que o documento seja carregado.

A configuração é um campo de três estados: true, false, ou null. Nulo significa herdar do nível acima. A cadeia de sobreposição é empresa → espaço de trabalho → modelo → solicitação de assinatura, com solicitação de assinatura tendo maior prioridade.

Ativar OTP no 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
  }
}

Todas as solicitações de assinatura neste espaço de trabalho agora exigem OTP por padrão.

Sobrescrever OTP desligado para uma solicitação de assinatura 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 solicitação ignora OTP independentemente da configuração do espaço de trabalho.

Alterações de Esquema

Novo: Substituir Documento de Modelo

O novo endpoint POST /templates/{id}/replace-document permite trocar o PDF subjacente em um modelo enquanto mantém todos os posicionamentos de campo, atribuições de assinantes e configurações intactos.

O documento de substituição deve atender a 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. Essas restrições existem para garantir que as posições dos campos continuem válidas após a troca. Se qualquer uma das verificações falhar, a API retorna 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 lista de verificação:

• Nenhum campo removido de qualquer objeto existente

• Nenhuma alteração de comportamento nos endpoints existentes

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

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

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 integrar de graça, sem necessidade de cartão de crédito.