Bedingte Felder: Erstellen Sie intelligente, verzweigte Signatur-Workflows über die API

Die meisten Signaturdokumente sind nicht statisch. Ein Ehepartnerfeld sollte nur erscheinen, wenn jemand "Verheiratet" auswählt. Ein zusätzlicher Offenlegungsbereich sollte erforderlich werden, wenn ein Geschäft einen bestimmten Dollarbetrag überschreitet. Ein Versandadressblock ist nur relevant, wenn der Unterzeichner "An eine andere Adresse liefern" auswählt.

Ohne bedingte Felder bauen Sie all diese Logik in Ihre eigene UI-Schicht ein. Sie verwalten Sichtbarkeitsschaltungen, Validierungsregeln und Randfälle clientseitig und hoffen, dass nichts umgangen wird. Es funktioniert, bis es nicht mehr funktioniert.

Die API von Firma.dev unterstützt jetzt native bedingte Felder. Sie definieren die Regeln in Ihrem Feldschema, und die API verwaltet Sichtbarkeit, erforderlichen Status und serverseitige Durchsetzung bei der Einreichung. Keine benutzerdefinierte UI-Logik erforderlich.

Zwei Arten von Bedingungen

Jedes Feldobjekt in der Firma.dev API akzeptiert jetzt zwei neue Nullable-Eigenschaften: required_conditions und visibility_conditions.

required_conditions überschreibt das statische required-Flag auf einem Feld. Wenn Sie required_conditions festlegen, wird das Feld nur dann erforderlich, wenn die Bedingungen sich auf andere Feldwerte zur Einreichungszeit als wahr auswerten. Wenn die Bedingungen als falsch ausgewertet werden, ist das Feld optional, unabhängig davon, was das required-Flag sagt.

visibility_conditions steuert, ob der Unterzeichner das Feld überhaupt sieht. Wenn diese festgelegt sind, bleibt das Feld verborgen, es sei denn, die Bedingungen werden als wahr ausgewertet. Verborgene Felder werden während der Validierung vollständig übersprungen, sodass Sie keine Fehler bei Feldern erhalten, die der Unterzeichner nie gesehen hat.

Beide Eigenschaften sind nullable. Wenn sie als null (der Standard) belassen werden, verhält sich das Feld genauso wie zuvor: Das statische required-Flag bestimmt, ob es erforderlich ist, und das Feld ist immer sichtbar. Vorhandene Integrationen erfordern keine Änderungen.

Das Bedingungsschema

Bedingungen verwenden eine dreistufig verschachtelte Struktur: ConditionSet, ConditionGroup und Condition. Dies ist der Teil, den es wert ist, sorgfältig verstanden zu werden, da er Ihnen eine komposable boolesche Logik ohne tief verschachtelte Bäume bietet.

ConditionSet ist der oberste Container. Es hat zwei Eigenschaften: einen logic-Operator (entweder and oder or) und ein Array von groups (ConditionGroup-Objekte). Der Logik-Operator bestimmt, wie die Gruppen kombiniert werden. Wenn logic and ist, müssen alle Gruppen als wahr ausgewertet werden. Wenn logic or ist, reicht jede einzelne Gruppe, die als wahr ausgewertet wird, aus.

ConditionGroup enthält ein Array von conditions (einzelne Bedingungsobjekte). Hier ist das Hauptdetail: Bedingungen innerhalb einer Gruppe werden unter Verwendung der entgegengesetzten Logik des übergeordneten ConditionSet kombiniert. Wenn das ConditionSet and verwendet, werden Bedingungen in jeder Gruppe mit or kombiniert. Wenn das ConditionSet or verwendet, verwenden Bedingungen innerhalb jeder Gruppe and.

Dieses entgegengesetzte Logikmuster ist das, was das Schema ausdrucksstark macht, ohne tiefe Verschachtelung zu erfordern. Es ermöglicht Ihnen, Aussagen zu erstellen wie "(Betrag > 50000 ODER Kundentyp ist gleich Enterprise) UND Region ist nicht leer" mit nur zwei Gruppen innerhalb eines and ConditionSet. Die erste Gruppe würde zwei Bedingungen (Betrag und Kundentyp, kombiniert mit or, weil die übergeordnete Bedingung and ist) enthalten, und die zweite Gruppe würde eine Bedingung für die Regionsüberprüfung enthalten.

Condition ist eine einzelne Bewertung. Es bezieht sich auf eine field_id (die UUID eines anderen Feldes im Dokument), einen operator und möglicherweise einen value zum Vergleich.

Operatorreferenz

Firma.dev unterstützt 10 Vergleichsoperatoren in den bedingten Feldern:

is_filled überprüft, ob ein Feld einen Wert überhaupt hat. Nützlich für das Anzeigen von Nachfüllfeldern, wenn ein Unterzeichner beginnt, einen Abschnitt auszufüllen. is_empty ist das Gegenteil und funktioniert gut, um ein Ersatzfeld zu verlangen, wenn ein primäres Feld leer gelassen wird.

equals und not_equals führen eine genaue Wertematch durch. Zeigen Sie Ehepartnersfelder an, wenn der Familienstand "Verheiratet" ist, oder verbergen Sie einen Bereich, wenn das Land nicht "US" entspricht.

contains und not_contains überprüfen auf Teilzeichenfolgen. Sie könnten compliance-bezogene Felder anzeigen, wenn ein Beschreibungsfeld "reguliert" enthält, oder einen Abschnitt überspringen, wenn Hinweise kein spezifisches Schlüsselwort erwähnen.

greater_than, less_than, greater_than_or_equal und less_than_or_equal behandeln numerische Vergleiche. Dies sind die Operatoren, die Sie verwenden, wenn Sie auf Schwellenwert basierende Logik aufbauen, wie z.B. Managergenehmigung zu verlangen, wenn ein Betrag 10.000 überschreitet oder vereinfachte Bedingungen anzuwenden, wenn ein Vertragswert unter eine bestimmte Zahl fällt.

Wie Bedingungen in der Praxis aussehen

Das API-Change-Log enthält ein Beispiel für das einfachste bedingte Muster: Ein Feld nur dann erforderlich zu machen, wenn ein anderes Feld ausgefüllt wurde. Die required_conditions-Eigenschaft nimmt ein ConditionSet mit and-Logik, einer einzigen Gruppe und einer einzigen Bedingung, die den is_filled-Operator verwendet:

{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}

{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}

{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}

Die field_id bezieht sich auf die UUID des Feldes, das Sie bewerten. In diesem Fall wird das aktuelle Feld erforderlich, wenn dieses referenzierte Feld einen beliebigen Wert hat. Wenn es leer ist, wird das Feld wieder optional.

Sie können dieses Muster in mehrere Richtungen erweitern. Für bedingte Sichtbarkeit würden Sie dieselbe ConditionSet-Struktur unter visibility_conditions anstelle von required_conditions verwenden. Ein "Ehepartner-Name"-Textfeld, das nur erscheint, wenn ein "Verheiratet"-Checkbox aktiviert ist, würde visibility_conditions mit einer einzigen is_filled-Bedingung verwenden, die auf die UUID des Checkbox-Feldes zeigt.

Für Mehrfachbedingungslogik können Sie mehr Gruppen oder mehr Bedingungen innerhalb von Gruppen hinzufügen. Wenn Sie möchten, dass ein Feld für das Compliance-Zertifikat nur dann erforderlich ist, wenn der Transaktionsbetrag größer als 10.000 ist UND das Land "US" entspricht, würden Sie ein ConditionSet mit and-Logik erstellen, das zwei Gruppen enthält, jede mit einer Bedingung. Die erste Gruppe überprüft den Betrag mit greater_than, die zweite überprüft das Land mit equals.

Das ausdrucksstärkste Muster verwendet die entgegengesetzte Logikregel. Angenommen, Sie möchten einen "Sonderbedingungen"-Bereich anzeigen, wenn (Betrag > 50.000 ODER Kundentyp ist gleich "Enterprise") UND die Region nicht leer ist. Sie würden das logic-Attribut des ConditionSet auf and mit zwei Gruppen setzen. Die erste Gruppe enthält zwei Bedingungen (Betrag und Kundentyp), die automatisch mit or kombiniert werden, weil das übergeordnete Element and verwendet. Die zweite Gruppe enthält die einzelne Regionsbedingung. Das Ergebnis ist eine saubere, lesbare Struktur, die sonst verschachtelte boolesche Bäume erfordern würde.

Server-seitige Durchsetzung

Alle Bedingungen werden serverseitig ausgewertet, wenn der Unterzeichner einreicht. Dies ist nicht optional und kann nicht durch clientseitige Manipulation umgangen werden.

Wenn ein Feld bedingt erforderlich ist und die Bedingung zur Einreichungszeit als wahr bewertet wird, gibt die API einen Validierungsfehler zurück, wenn dieses Feld leer ist. Wenn die visibility_conditions eines Feldes als falsch bewertet werden, wird das Feld verborgen und während der Validierung vollständig übersprungen. Keine Randfälle, keine Rennbedingungen zwischen Ihrer UI und dem Backend.

Für Compliance-Workflows ist dies wichtig. Die Bedingungen, die Sie in der API definieren, sind die Bedingungen, die durchgesetzt werden, Punkt. Ihre clientseitige UI kann die Sichtbarkeits- und Erforderlichkeitszustände in Echtzeit für eine gute Unterzeichnererfahrung rendern, aber die Quelle der Wahrheit lebt serverseitig.

Wo Bedingungen funktionieren

Bedingte Felder sind auf jeder Oberfläche in Firma.dev verfügbar: im Vorlageneditor-UI, im UI des Signaturanfrageeditors, im eingebetteten Vorlageneditor, im eingebetteten Signaturanfrageeditor und in der vollständigen REST-API für sowohl Vorlagen als auch Signaturanfragen.

Durch die API festgelegte Bedingungen erscheinen und werden in allen UI Oberflächen korrekt ausgewertet, und durch die Editoren konfigurierte Bedingungen sind vollständig über die API zugänglich. Es gibt keine Lücke zwischen den visuellen Werkzeugen und der programmatischen Schnittstelle.

Erste Schritte

Bedingte Felder wurden als Teil von Firma.dev API v1.10.0 ausgeliefert. Sie sind vollständig additiv ohne Breaking Changes. Felder ohne Bedingungen funktionieren weiterhin genau so, wie sie zuvor funktionierten, und bestehende Integrationen erfordern keine Änderungen.

Sie können required_conditions und visibility_conditions ab sofort bei jedem Feldobjekt verwenden. Überprüfen Sie das API-Change-Log für die vollständige Schema-Referenz und die API-Dokumentation für die vollständige Feldspezifikation.

Firma.dev berechnet €0.029 pro Umschlag ohne monatliche Mindestbeträge, keine Sitzgebühren und keine Vorausverpflichtungen. Wenn Sie Signatur-Workflows erstellen, die sich basierend auf Eingaben des Unterzeichners anpassen müssen, ermöglichen Ihnen bedingte Felder, diese Logik dorthin zu verschieben, wo sie hingehört: in die API, zur Durchsetzung bei jeder Einreichung.

Starten Sie kostenlos mit Firma.dev, keine Kreditkarte erforderlich.