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 die bisher funktionsreichste Version und bringt fünf zusätzliche Features ohne inkompatible Änderungen. Wenn Sie v1.9.0 verwenden, funktioniert Ihre bestehende Integration ohne Anpassungen. Alles hier ist neue Funktionalität, keine Migrationsarbeit.

Hier ist, was enthalten ist.

Was ist in v1.10.0 enthalten

Alle fünf Features sind additive Erweiterungen. Neue Felder haben standardmäßig null oder false. Keine Schema-Entfernungen, keine Verhaltensänderungen.

Bedingte Feldlogik

Das ist das Hauptfeature. Felder können jetzt dynamische required_conditions und visibility_conditions haben, die zum Zeitpunkt der Unterzeichnung anhand anderer Feldwerte ausgewertet werden. Anstatt bedingte Formularlogik in Ihrer eigenen UI zu bauen, 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 komponierbar. 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 die Gruppen zueinander in Beziehung stehen, während Bedingungen innerhalb einer Gruppe den jeweils 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. Nehmen wir einen Arbeitsvertrag, bei dem ein Feld für den Namen des Ehepartners nur erscheinen soll, wenn der Unterzeichner ein "Verheiratet"-Kontrollkästchen 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 Namen des Ehepartners verborgen und wird vollständig von der Validierung ausgenommen. Wenn es aktiviert ist, wird es angezeigt und kann über eine separate Regel required_conditions mithilfe derselben Struktur als erforderlich festgelegt werden.

Einige Anwendungsfälle, die dadurch direkt möglich werden:

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

• Abhängige Genehmigungsabschnitte, in denen zusätzliche Freigabefelder basierend auf einem Geldbetrag oder Risikoniveau angezeigt werden

• Progressive Formulare, die sich anpassen, während der Unterzeichner Informationen eingibt, und die Anfangsansicht sauber halten

Das entscheidende Detail für compliance-sensible Integrationen: Bedingungen werden beim Absenden serverseitig durchgesetzt. Ein Unterzeichner kann Sichtbarkeits- oder Pflichtregeln nicht durch Manipulation auf der Client-Seite umgehen. Wenn ein Feld basierend auf dem Wert eines anderen Feldes erforderlich sein soll, validiert Firma.dev dies serverseitig, bevor das signierte Dokument angenommen wird.

DOCX-Dokumentunterstützung

Alle Endpunkte zum Hochladen von Dokumenten akzeptieren jetzt .docx-Dateien zusätzlich zu PDF. Wenn Sie ein Word-Dokument hochladen, konvertiert Firma.dev es automatisch serverseitig in PDF. Keine Vorverarbeitung auf der Client-Seite, keine zusätzlichen Abhängigkeiten in Ihrer Pipeline.

Dies gilt für das Erstellen von Vorlagen, den Austausch von Vorlagendokumenten, das Erstellen von Signieranfragen 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 vollständig unbeeinträchtigt. Wenn Sie bereits PDFs hochladen, ändert sich nichts. Dadurch entfällt lediglich der Konvertierungsschritt für Teams, die Dokumente in Word erstellen.

Audit-Trail-Endpunkt

Ein neuer GET /signing-requests/{id}/audit-Endpunkt liefert das vollständige chronologische Ereignisprotokoll für jede Signieranfrage. Er kombiniert sowohl Admin-Aktionen (erstellt, bearbeitet, gesendet, storniert) als auch Unterzeichner-Aktionen (angezeigt, signiert, abgelehnt, heruntergeladen) in einer einzigen Zeitleiste.

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

Dieser Endpunkt deckt die häufigste Compliance-Anforderung ab: ein Nachweispaket bereitzustellen, das genau zeigt, wer was, wann und von wo aus getan hat. Ob Sie es für interne Audit-Protokolle, regulatorische Berichterstattung oder kundennahe Aktivitäts-Feeds benötigen, die Daten sind mit einem einzigen Aufruf verfügbar.

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

Steuerung des Signaturrahmens

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

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

2. Arbeitsbereich überschreibt die Firma (null wird vererbt)

3. Signieranfrage überschreibt den Arbeitsbereich (null wird vererbt)

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 Hauptanwendungsfall hier ist White-Labeling. Wenn Sie Firma.dev in Ihr eigenes Produkt einbetten und saubere Signaturen ohne jeglichen Firma.dev-Rahmen auf dem finalen Dokument wünschen, setzen Sie dies auf Arbeitsbereichsebene auf false, und jede Signieranfrage in diesem Arbeitsbereich übernimmt diese Einstellung. Umgekehrt können regulierte Branchen, die sichtbare Signaturkennungen benötigen, die Funktion ausdrücklich aktiviert lassen.

Bedingungen beim Löschen von Benutzern zwangsweise entfernen

Dies ist eine Verbesserung der Entwicklerfreundlichkeit. Wenn Sie einen Empfänger löschen, dessen Felder in den Bedingungen anderer Felder referenziert werden (aus der obigen bedingten Logik), gab es über die API bisher keine Möglichkeit, mit dieser Abhängigkeit umzugehen. 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 die Bedingungsreferenzen automatisch und fährt mit dem Löschen fort

Das ist wichtig, wenn Sie Empfänger in dynamischen Workflows programmgesteuert verwalten. Ohne force_remove_conditions würde das Löschen eines Empfängers, dessen Felder in Bedingungen anderer Felder einfließen, erfordern, dass Sie zunächst jede einzelne Bedingungsreferenz manuell bereinigen.

Technische Zusammenfassung

Neue Schemata: ConditionSet, ConditionGroup, Condition

Upgrade von v1.9.0

Keine inkompatiblen Änderungen. Keine Feldentfernungen. Keine Verhaltensänderungen. Neue Felder haben standardmäßig null oder false, daher benötigen bestehende Integrationen keinerlei Anpassung. Wenn Sie von einer früheren Version kommen, gilt dasselbe für jede Version seit v1.0.0. Prüfen Sie die vollständige API-Änderungshistorie für die gesamte Versionshistorie.

Details zu v1.9.0 (OTP-Verifizierung, Austausch von Vorlagendokumenten) finden Sie im Änderungshistorienabschnitt zu v1.9.0.

Los geht's

Neu bei Firma.dev? Preisgestaltung ab $0.029 pro Envelope, keine Verträge oder Mindestmengen. 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.