Firma.dev API v1.9.0: OTP-Verifizierung, Dokumentvorlagenersatz und Schema-Aktualisierungen

v1.9.0 ist ein fokussiertes Release, das auf v1.8.0 aufbaut, ohne breaking changes. Wenn Sie heute integriert sind, funktioniert alles weiter. Zwei neue Funktionen sind jetzt verfügbar, wenn Sie sie benötigen: Signer-Email-OTP-Verifizierung und Ersetzung von Vorlagendokumenten.

Was ist in v1.9.0

Beide Änderungen sind additiv. Es wurden keine Felder entfernt, das Verhalten von Endpunkten wurde nicht geändert, und es ist keine Migration von v1.8.0 erforderlich.

Neu: Signer-Email-OTP-Verifizierung

Die Einstellung require_otp_verification fügt einen Identitätsüberprüfungsschritt hinzu, bevor ein Unterzeichner auf ein Dokument zugreifen kann. Bei Aktivierung sehen die Unterzeichner beim Öffnen ihres Signierlinks einen Verifizierungsbildschirm, erhalten einen 6-stelligen Code per E-Mail und müssen diesen eingeben, bevor das Dokument geladen wird.

Die Einstellung ist ein tri-state Feld: true, false oder null. Null bedeutet, dass von der oberen Ebene vererbt wird. Die Übersteuerungskette läuft folgendermaßen: firma → Arbeitsplatz → Vorlage → Signieranfrage, wobei die Signieranfrage die höchste Priorität hat.

OTP auf der Arbeitsebene aktivieren

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

Alle Signieranfragen in diesem Arbeitsplatz erfordern jetzt standardmäßig OTP.

OTP für eine bestimmte Signieranfrage deaktivieren

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

Diese Anfrage überspringt OTP unabhängig von der Arbeitseinstellung.

Schemaänderungen

Neu: Vorlagendokument ersetzen

Der neue POST /templates/{id}/replace-document Endpoint ermöglicht es Ihnen, das zugrunde liegende PDF einer Vorlage zu tauschen, während alle Feldplatzierungen, Unterzeichnerzuweisungen und Einstellungen intakt bleiben.

Das Ersatzzdokument muss zwei Validierungsanforderungen erfüllen: gleiche Seitenanzahl wie das Original und Seitenabmessungen innerhalb einer Toleranz von 1 Punkt. Diese Einschränkungen stellen sicher, dass die Feldpositionen nach dem Tausch gültig bleiben. Wenn eine der Prüfungen fehlschlägt, gibt die API einen 400 mit einem klaren Fehler zurück.

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();

Fehlerfälle:

Neue Endpunkte

Upgrade von v1.8.0

Keine Maßnahmen erforderlich. Die Checkliste:

• Keine Felder von bestehenden Objekten entfernt

• Keine Verhaltensänderungen an bestehenden Endpunkten

• require_otp_verification Standard ist null (vererbt), daher sind bestehende Integrationen nicht betroffen, bis Sie es explizit einstellen

• POST /templates/{id}/replace-document ist ein neuer Endpoint, keine Ersetzung für irgendetwas

Vollständige API-Dokumentation ist unter docs.firma.dev verfügbar. Das vollständige API-Änderungsprotokoll ist unter docs.firma.dev/guides/api-changelog.

Holen Sie sich Ihren API-Schlüssel und beginnen Sie kostenlos mit dem Erstellen, keine Kreditkarte erforderlich.