Firma.dev API v1.10.0: Bedingte Felder, DOCX-Unterstützung, Prüfpfad und mehr

Die Firma.dev-API v1.10.0 ist live. Dies ist das bisher funktionsreichste Release, das fünf additive Funktionen ohne bahnbrechende Änderungen bereitstellt. Wenn Sie v1.9.0 verwenden, funktioniert Ihre bestehende Integration ohne Änderungen. Alles hier ist eine neue Funktion, keine Migrationsarbeit.

Hier ist, was enthalten ist.

Was ist neu in v1.10.0

Alle fünf Funktionen sind additiv. Neue Felder sind standardmäßig auf null oder false gesetzt. Keine Schema-Entfernungen, keine Verhaltensänderungen.

Bedingte Feldlogik

Dies ist das Hauptfeature. Felder können jetzt dynamische required_conditions und visibility_conditions haben, die basierend auf anderen Feldwerten zum Zeitpunkt der Signierung ausgewertet werden. Anstatt die bedingte Formularlogik in Ihrer eigenen Benutzeroberfläche aufzubauen, definieren Sie die Regeln einmal in der API und Firma.dev übernimmt die Auswertung sowohl auf der Client- als auch auf der Serverseite.

Die Struktur ist zusammensetzbar. Ein ConditionSet enthält ein oder mehrere ConditionGroup-Objekte, und jede Gruppe enthält einzelne Condition-Objekte. Der logic-Operator auf Set-Ebene (and oder or) steuert, wie Gruppen zueinander in Beziehung stehen, während Bedingungen innerhalb einer Gruppe den entgegengesetzten Operator verwenden.

Zehn Vergleichsoperatoren sind verfügbar: is_filled, is_empty, equals, not_equals, contains, not_contains, greater_than, less_than, greater_than_or_equal und less_than_or_equal.

Hier ist ein praktisches Beispiel. Angenommen, Sie haben einen Arbeitsvertrag, bei dem das Feld für den Namen des Ehepartners nur angezeigt werden soll, wenn der Unterzeichner ein Kontrollkästchen "Verheiratet" aktiviert:

{
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "married-checkbox-field-id",
            "operator": "equals",
            "value": "true"
          }
        ]
      }
    ]
  }
}

{
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "married-checkbox-field-id",
            "operator": "equals",
            "value": "true"
          }
        ]
      }
    ]
  }
}

{
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "married-checkbox-field-id",
            "operator": "equals",
            "value": "true"
          }
        ]
      }
    ]
  }
}

Wenn das Kontrollkästchen nicht markiert ist, bleibt das Feld für den Namen des Ehepartners ausgeblendet und überspringt die Validierung vollständig. Wenn es markiert ist, wird es angezeigt und kann über eine separate required_conditions-Regel mit derselben Struktur als Pflichtfeld festgelegt werden.

Einige Anwendungsfälle, die dies direkt ermöglicht:

• Bedingte Offenlegungsfelder, die nur angezeigt werden, wenn ein Unterzeichner eine bestimmte Option auswählt

• Abhängige Überprüfungsabschnitte, in denen zusätzliche Genehmigungsfelder basierend auf einem Dollarbetrag oder einer Risikostufe erscheinen

• Progressive Formulare, die sich anpassen, während der Unterzeichner Informationen ausfüllt, wodurch die ursprüngliche Ansicht übersichtlich bleibt

Das wichtigste Detail für Compliance-relevante Integrationen: Bedingungen werden serverseitig bei der Übermittlung erzwungen. Ein Unterzeichner kann Sichtbarkeits- oder Pflichtfeldregeln nicht durch clientseitige Manipulationen umgehen. Wenn ein Feld basierend auf dem Wert eines anderen Feldes erforderlich sein soll, validiert Firma.dev dies serverseitig, bevor das signierte Dokument akzeptiert wird.

DOCX-Dokumentenunterstützung

Alle Dokumenten-Upload-Endpunkte akzeptieren jetzt neben PDF auch .docx-Dateien. Wenn Sie ein Word-Dokument hochladen, konvertiert Firma.dev es automatisch serverseitig in das PDF-Format. Keine clientseitige Vorverarbeitung, keine zusätzlichen Abhängigkeiten in Ihrer Pipeline.

Dies gilt für die Vorlagenerstellung, das Ersetzen von Vorlagendokumenten, das Erstellen von Signaturanforderungen und alle PUT/PATCH-Aktualisierungsvorgänge.

curl -X POST https://api.firma.dev/v1.10.0/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Agreement",
    "document": "BASE64_ENCODED_DOCX_CONTENT"
  }'

curl -X POST https://api.firma.dev/v1.10.0/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Agreement",
    "document": "BASE64_ENCODED_DOCX_CONTENT"
  }'

curl -X POST https://api.firma.dev/v1.10.0/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Agreement",
    "document": "BASE64_ENCODED_DOCX_CONTENT"
  }'

Bestehende PDF-Integrationen sind völlig unberührt. Wenn Sie bereits PDFs hochladen, ändert sich nichts. Dies entfernt lediglich den Konvertierungsschritt für Teams, die Dokumente in Word erstellen.

Audit-Trail-Endpunkt

Ein neuer Endpunkt GET /signing-requests/{id}/audit gibt das vollständige chronologische Ereignisprotokoll für jede Signaturanforderung zurück. Er kombiniert sowohl Administratoraktionen (erstellt, bearbeitet, gesendet, abgebrochen) als auch Unterzeichneraktionen (angesehen, signiert, abgelehnt, heruntergeladen) in einer einzigen Timeline.

Jedes Ereignis enthält einen Zeitstempel, eine Quelle (admin oder signer), einen Ereignistyp, die Identität des Akteurs, eine IP-Adresse (für Unterzeichnerereignisse) und ereignisspezifische Metadaten.

Dieser Endpunkt deckt die häufigste Compliance-Anforderung ab: Die Bereitstellung eines Nachweispakets, das genau zeigt, wer was, wann und von wo aus getan hat. Egal, ob Sie es für interne Audit-Protokolle, die aufsichtsrechtliche Berichterstattung oder kundenorientierte Aktivitäts-Feeds benötigen – die Daten sind alle in einem einzigen Aufruf verfügbar.

Das vollständige Antwortschema und die Endpunktdetails finden Sie in der Audit-Trail-API-Referenz.

Signature-Frame-Steuerung

Standardmäßig enthalten ausgefüllte PDFs einen visuellen Rahmen um jede Signatur mit einer Signatur-ID. Mit der neuen Einstellung show_signature_frame können Sie dies auf drei Ebenen mit einer sauberen Vererbungskette steuern:

1. Unternehmen legt den Standard fest (standardmäßig aktiviert)

2. Arbeitsbereich überschreibt Unternehmen (null erbt)

3. Signaturanforderung überschreibt Arbeitsbereich (null erbt)

So deaktivieren Sie den Rahmen auf Arbeitsbereichsebene:

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "show_signature_frame": false
  }
}

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "show_signature_frame": false
  }
}

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "show_signature_frame": false
  }
}

Der Hauptanwendungsfall hierfür ist das White-Labeling. Wenn Sie Firma.dev in Ihr eigenes Produkt einbetten und saubere Signaturen ohne Firma.dev-Rahmen auf dem endgültigen Dokument wünschen, setzen Sie dies auf der Arbeitsbereichsebene auf false, und jede Signaturanforderung in diesem Arbeitsbereich erbt diese Einstellung. Umgekehrt können regulierte Branchen, die sichtbare Signatur-Identifikatoren verlangen, dies explizit aktiviert lassen.

Bedingungen beim Löschen von Benutzern forced entfernen

Dies ist eine Verbesserung der Usability für Entwickler. Wenn Sie einen Empfänger gelöscht haben, auf dessen Felder in den Bedingungen anderer Felder verwiesen wird (aus der bedingten Logik oben), hatte die API zuvor keine Möglichkeit, mit der Abhängigkeit umzugehen. Jetzt steuert der Parameter force_remove_conditions das Verhalten:

• false (Standard): Die Anforderung wird mit einer Fehlermeldung abgelehnt, die die abhängigen Felder auflistet

• true: Entfernt automatisch die Bedingungsreferenzen und fährt mit dem Löschen fort

Dies ist wichtig, wenn Sie Empfänger in dynamischen Workflows programmatisch verwalten. Ohne force_remove_conditions müssten Sie beim Löschen eines Empfängers, dessen Felder in Bedingungen anderer Felder einfließen, zuerst jede Bedingungsreferenz manuell bereinigen.

Technische Zusammenfassung

Neue Schemata: ConditionSet, ConditionGroup, Condition

Upgrade von v1.9.0

Keine bahnbrechenden Änderungen. Keine Feldentfernungen. Keine Verhaltensänderungen. Neue Felder sind standardmäßig auf null oder false gesetzt, sodass bestehende Integrationen keine Änderungen erfordern. Wenn Sie von einer älteren Version kommen, gilt dasselbe für jedes Release seit v1.0.0. Den vollständigen Versionsverlauf finden Sie im vollständigen API-Changelog.

Details zu v1.9.0 (OTP-Verifizierung, Ersatz von Vorlagendokumenten) finden Sie im v1.9.0 Changelog-Bereich.

Erste Schritte

Neu bei Firma.dev? Nutzungsbasierte Preise ab $0,049 pro Umschlag, keine Verträge oder Mindestlaufzeiten. Starten Sie kostenlos mit Firma.dev, keine Kreditkarte erforderlich.

API-Schlüssel holen

Die vollständige API-Referenz finden Sie in der Firma.dev-Dokumentation.