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 v1.8.0, sem alterações incompatíveis. Se já está integrado hoje, nada se quebra. Duas novas funcionalidades estão agora disponíveis quando precisar delas: verificação OTP por e-mail do signatário e substituição do documento do modelo.

O que há na v1.9.0

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

Novo: Verificação OTP por e-mail do signatário

A definição require_otp_verification adiciona uma etapa de verificação de identidade antes de um signatário poder aceder a um documento. Quando ativada, os signatários veem um ecrã de verificação ao abrirem o respetivo link de assinatura, recebem um código de 6 dígitos por e-mail e têm de o introduzir antes de o documento carregar.

A definição é um campo de três estados: true, false ou null. null significa herdar do nível acima. A cadeia de substituição segue empresa → workspace → template → 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 passam agora a requerer OTP por predefinição.

Desativar OTP 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 o OTP independentemente da definição do espaço de trabalho.

Alterações ao esquema

Novo: Substituir documento do modelo

O novo endpoint POST /templates/{id}/replace-document permite substituir o PDF subjacente de um modelo mantendo intactos todos os posicionamentos dos campos, as atribuições dos signatários e as definições.

O documento de substituição tem de cumprir dois requisitos de validação: o mesmo número de páginas que o original e dimensões de página dentro de uma tolerância de 1pt. Estes constrangimentos existem para garantir que as posições dos campos permanecem válidas após a substituição. 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

Atualizar a partir da v1.8.0

Não é necessária qualquer ação. Lista de verificação:

• Nenhum campo foi removido de qualquer objeto existente

• Sem alterações de comportamento nos endpoints existentes

• require_otp_verification tem por predefinição null (herda), pelo que as integrações existentes não são afetadas até o definir 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 registo completo de alterações da API está em docs.firma.dev/guides/api-changelog.

Obtenha a sua chave de API e comece a desenvolver gratuitamente, não é necessário cartão de crédito.