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

v1.9.0 ist ein fokussiertes Release auf Basis von v1.8.0 ohne Breaking Changes. Wenn Sie heute integriert sind, geht nichts kaputt. Zwei neue Funktionen sind jetzt verfügbar, wenn Sie sie brauchen: OTP-Verifizierung per E-Mail für Unterzeichner und Ersetzen des Vorlagendokuments.

Was ist in v1.9.0 enthalten

Beide Änderungen sind additiv. Es wurden keine Felder entfernt, kein Endpunktverhalten wurde geändert, und von v1.8.0 ist keine Migration erforderlich.

Neu: OTP-Verifizierung per E-Mail für Unterzeichner

Die Einstellung require_otp_verification fügt einen Identitätsprüfungs-Schritt hinzu, bevor ein Unterzeichner auf ein Dokument zugreifen kann. Wenn sie aktiviert ist, sehen Unterzeichner beim Öffnen ihres Signaturlinks einen Verifizierungsbildschirm, erhalten einen 6-stelligen Code per E-Mail und müssen ihn eingeben, bevor das Dokument geladen wird.

Die Einstellung ist ein Drei-Werte-Feld: true, false oder null. null bedeutet, dass von der darüberliegenden Ebene geerbt wird. Die Überschreibungsreihenfolge verläuft Unternehmen → Arbeitsbereich → Vorlage → Signaturanforderung, wobei die Signaturanforderung die höchste Priorität hat.

OTP auf Arbeitsbereichsebene 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 Signaturanforderungen in diesem Arbeitsbereich erfordern jetzt standardmäßig OTP.

OTP für eine bestimmte Signaturanforderung 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 Arbeitsbereichseinstellung.

Schemaänderungen

Neu: Vorlagendokument ersetzen

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

Das Ersatzdokument muss zwei Validierungsanforderungen erfüllen: gleiche Seitenanzahl wie das Original und Seitenabmessungen innerhalb einer Toleranz von 1 pt. Diese Einschränkungen dienen dazu, sicherzustellen, dass die Feldpositionen nach dem Austausch gültig bleiben. Wenn eine der Prüfungen fehlschlägt, gibt die API einen 400 mit einer klaren Fehlermeldung 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 Aktion erforderlich. Die Checkliste:

• Keine Felder aus einem bestehenden Objekt entfernt

• Keine Verhaltensänderungen an bestehenden Endpunkten

• require_otp_verification hat standardmäßig null (erbt), daher sind bestehende Integrationen nicht betroffen, bis Sie es explizit setzen

• POST /templates/{id}/replace-document ist ein neuer Endpunkt, kein Ersatz für etwas anderes

Die vollständige API-Dokumentation finden Sie unter docs.firma.dev. Das vollständige API-Änderungsprotokoll finden Sie unter docs.firma.dev/guides/api-changelog.

Holen Sie sich Ihren API-Schlüssel und legen Sie kostenlos los, keine Kreditkarte erforderlich.