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

Firma.dev API v1.10.0 ist live. Dies ist die Version mit den meisten Funktionen bis heute, die fünf zusätzliche Funktionen ohne Breaking Changes liefert. Wenn du auf v1.9.0 bist, funktioniert deine bestehende Integration ohne Änderungen. Alles hier ist neue Funktionalität, keine Migrationsarbeit.

Hier ist, was enthalten ist.

Was ist in v1.10.0

Alle fünf Funktionen sind zusätzlich. Neue Felder haben standardmäßig den Wert null oder false. Keine Schemaänderungen, keine Verhaltensänderungen.

Bedingte Feldlogik

Dies ist die Hauptfunktion. Felder können jetzt dynamische required_conditions und visibility_conditions haben, die basierend auf anderen Feldwerten zur Signaturzeit ausgewertet werden. Anstatt bedingte Formularlogik in deinem eigenen UI zu erstellen, definierst du die Regeln einmal in der API und Firma.dev übernimmt die Auswertung sowohl auf der Client- als auch 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 stehen, während Bedingungen innerhalb einer Gruppe den entgegengesetzten Operator verwenden.

Es stehen zehn Vergleichsoperatoren zur Verfügung: 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, du hast einen Arbeitsvertrag, bei dem ein 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 aktiviert ist, bleibt das Feld für den Ehepartnernamen ausgeblendet und umgeht die Validierung vollständig. Wenn es aktiviert ist, wird es angezeigt und kann durch eine separate required_conditions-Regel mit derselben Struktur als erforderlich festgelegt werden.

Einige Anwendungsfälle, die dies direkt freischaltet:

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

• Abhängige Genehmigungsabschnitte, bei denen zusätzliche Freigabefelder basierend auf einem Dollarbetrag oder Risikolevel angezeigt werden

• Progressive Formulare, die sich anpassen, während der Unterzeichner Informationen ausfüllt, um die Anfangsansicht sauber zu halten

Das wichtigste Detail für compliance-sensitive Integrationen: Bedingungen werden serverseitig bei der Einreichung durchgesetzt. Ein Unterzeichner kann Sichtbarkeits- oder Erforderlichkeitsregeln nicht durch clientseitige Manipulation umgehen. Wenn ein Feld basierend auf dem Wert eines anderen Feldes erforderlich sein sollte, validiert Firma.dev dies serverseitig, bevor das unterschriebene Dokument angenommen wird.

DOCX-Dokument Unterstützung

Alle Dokument-Upload-Endpunkte akzeptieren nun .docx-Dateien neben PDF. Wenn du ein Word-Dokument hochlädst, konvertiert Firma.dev es automatisch serverseitig in ein PDF. Keine clientseitige Vorverarbeitung, keine zusätzlichen Abhängigkeiten in deiner Pipeline.

Dies gilt für die Vorlagenerstellung, den Vorlagendokumentaustausch, die Erstellung von Signieranforderungen und alle PUT/PATCH-Update-Operationen.

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 du bereits PDFs hochlädst, ändert sich nichts. Dies entfernt lediglich den Konvertierungsschritt für Teams, die Dokumente in Word verfassen.

Audit-Trail-Endpunkt

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

Jedes Ereignis umfasst einen Zeitstempel, die Quelle (admin oder signer), den Ereignistyp, die Identität des Akteurs, die IP-Adresse (bei Unterzeichnerereignissen) und ereignisspezifische Metadaten.

Dieser Endpunkt deckt die häufigste Compliance-Anforderung ab: die Erstellung eines Beweispakets, das genau zeigt, wer was wann und von wo getan hat. Egal, ob du es für interne Audit-Protokolle, behördliche Berichte oder kundenorientierte Aktivitätsfeeds benötigst, die Daten sind alle in einem Aufruf verfügbar.

Für das vollständige Antw Schema und die Endpunktdetails siehe die Audit-Trail-API-Referenz.

Signaturrahmen-Steuerung

Standardmäßig enthalten abgeschlossene PDFs einen visuellen Rahmen um jede Signatur mit einer Signatur-ID. Die neue show_signature_frame-Einstellung ermöglicht es dir, dies auf drei Ebenen mit einer sauberen Vererbungskette zu steuern:

1. Firma setzt den Standard (standardmäßig aktiviert)

2. Arbeitsbereich überschreibt Firma (null erbt)

3. Signieranfrage überschreibt Arbeitsbereich (null erbt)

Um den Rahmen auf Arbeitsbereichsebene zu deaktivieren:

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 primäre Anwendungsfall hierfür ist das White-Labeling. Wenn du Firma.dev in dein eigenes Produkt einbettest und saubere Signaturen ohne irgendeine Firma.dev-Rahmung auf dem endgültigen Dokument willst, setze dies auf false auf der Arbeitsbereichsebene und jede Signieranfrage in diesem Arbeitsbereich erbt es. Im Gegensatz dazu können regulierte Branchen, die sichtbare Signaturkennungen erfordern, diese ausdrücklich aktiviert lassen.

Bedingungen zwangsweise entfernen beim Benutzerlöschen

Dies ist eine Verbesserung der Entwicklerfreundlichkeit. Wenn du einen Empfänger löschst, dessen Felder in den Bedingungen anderer Felder referenziert sind (aus der oben beschriebenen bedingten Logik), hatte die API zuvor keine Möglichkeit, die Abhängigkeit zu handhaben. Jetzt steuert der Parameter force_remove_conditions das Verhalten:

• false (Standard): Die Anfrage wird mit einem Fehler abgelehnt, der die abhängigen Felder auflistet

• true: Entfernt automatisch die Bedingungsverweise und fährt mit der Löschung fort

Dies ist wichtig, wenn du Empfänger in dynamischen Workflows programmatisch verwaltest. Ohne force_remove_conditions würde das Löschen eines Empfängers, dessen Felder in Bedingungen anderer Felder eingehen, erfordern, dass du jedes Bedingungsverweis manuell bereinigst.

Technische Zusammenfassung

Neue Schemas: ConditionSet, ConditionGroup, Condition

Upgrade von v1.9.0

Keine Breaking Changes. Keine Feldentfernungen. Keine Verhaltensänderungen. Neue Felder haben standardmäßig den Wert null oder false, sodass bestehende Integrationen keine Änderungen erfordern. Wenn du von einer früheren Version kommst, gilt das gleiche für jede Version seit v1.0.0. Überprüfe das vollständige API-Changelog für die gesamte Versionsgeschichte.

Für Details zu v1.9.0 (OTP-Verifikation, Vorlagendokumentersatz), siehe den v1.9.0-Changelog-Abschnitt.

Erste Schritte

Neu bei Firma.dev? Pay-as-you-go Preise bei $0,029 pro Umschlag, keine Verträge oder Mindestbestellungen. Starte kostenlos mit Firma.dev, keine Kreditkarte erforderlich.

API-Schlüssel holen

Für die vollständige API-Referenz, siehe die Firma.dev Dokumentation.