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 und keine breaking changes enthält. Wenn Sie heute integriert sind, bricht nichts. Zwei neue Funktionen sind jetzt verfügbar, wenn Sie sie benötigen: Signer-Email-OTP-Verifizierung und Vorlagen-Dokumentersatz.

Was ist in v1.9.0 enthalten

Beide Änderungen sind additiv. Keine Felder wurden entfernt, kein Endpoint-Verhalten wurde geändert, keine Migration von v1.8.0 ist erforderlich.

Neu: Signer Email OTP-Verifizierung

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

Die Einstellung ist ein Tri-State-Feld: true, false oder null. Null bedeutet, von der höheren Ebene erben. Die Override-Kette läuft Firma → Arbeitsbereich → Vorlage → Signieranfrage, wobei die Signieranfrage höchste Priorität hat.

OTP im Arbeitsbereich 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 Arbeitsbereich erfordern jetzt standardmäßig OTP.

OTP für eine spezifische Signieranfrage überschreiben

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 umgeht OTP unabhängig von der Einstellung des Arbeitsbereichs.

Schema-Änderungen

Neu: Ersetzen des Vorlagendokuments

Der neue POST /templates/{id}/replace-document-Endpunkt ermöglicht Ihnen das Austauschen des zugrundeliegenden PDFs in einer Vorlage, während alle Feldplatzierungen, Unterzeichnerzuweisungen und Einstellungen intakt bleiben.

Das Ersatzdokument muss zwei Validierungsanforderungen erfüllen: gleiche Seitenzahl wie das Original und Seitenabmessungen innerhalb einer Toleranz von 1pt. Diese Einschränkungen existieren, um sicherzustellen, dass Feldpositionen nach dem Austausch gültig bleiben. Wenn eine der beiden Überprüfungen fehlschlägt, gibt die API einen 400 Fehler 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 Handlung erforderlich. Die Checkliste:

• Keine Felder aus bestehenden Objekten entfernt

• Keine Verhaltensänderungen bei bestehenden Endpunkten

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

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

Vollständige API-Dokumentation ist unter docs.firma.dev. Der komplette API-Änderungslog ist unter docs.firma.dev/guides/api-changelog.

Holen Sie sich Ihren API-Schlüssel und beginnen Sie kostenlos zu entwickeln, keine Kreditkarte erforderlich.