Leitfäden
Bedingte Felder: Erstellen Sie intelligente, verzweigte Signatur-Workflows über die API
Die meisten Signaturdokumente sind nicht statisch. Ein Feld für den Namen des Ehepartners sollte nur erscheinen, wenn jemand "Verheiratet" auswählt. Ein zusätzlicher Offenlegungsabschnitt sollte erforderlich werden, wenn eine Transaktion einen bestimmten Dollarbetrag überschreitet. Ein Block für die Lieferadresse ist nur relevant, wenn der Unterzeichner "An andere Adresse versenden" auswählt.
Ohne bedingte Felder bauen Sie all diese Logik in Ihrer eigenen UI-Schicht auf. Sie verwalten Sichtbarkeitsschalter, Validierungsregeln und Sonderfälle clientseitig und hoffen, dass nichts umgangen wird. Es funktioniert, bis es das nicht mehr tut.
Firma.dev's API unterstützt bedingte Felder jetzt nativ. Sie definieren die Regeln in Ihrem Feldschema, und die API übernimmt Sichtbarkeit, Erforderlichkeitsstatus und serverseitige Durchsetzung bei der Übermittlung. 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 eines Felds. Wenn Sie required_conditions setzen, wird das Feld nur dann erforderlich, wenn die Bedingungen auf Grundlage anderer Feldwerte zum Zeitpunkt der Übermittlung als wahr ausgewertet werden. 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 gesetzt, bleibt das Feld verborgen, es sei denn, die Bedingungen werden als wahr ausgewertet. Verborgene Felder werden bei der Validierung vollständig übersprungen, sodass Sie keine Fehler für Felder erhalten, die der Unterzeichner nie gesehen hat.
Beide Eigenschaften sind nullable. Wenn sie auf null gesetzt bleiben (der Standard), verhält sich das Feld genau wie zuvor: Das statische required-Flag bestimmt, ob es erforderlich ist, und das Feld ist immer sichtbar. Bestehende Integrationen benötigen keine Änderungen.
Das Bedingungsschema
Bedingungen verwenden eine dreistufig verschachtelte Struktur: ConditionSet, ConditionGroup und Condition. Das ist der Teil, den man sorgfältig verstehen sollte, denn er ermöglicht Ihnen zusammensetzbare boolesche Logik ohne tief verschachtelte Bäume.
ConditionSet ist der Container auf oberster Ebene. Er hat zwei Eigenschaften: einen logic-Operator (entweder and oder or) und ein Array von groups (ConditionGroup-Objekten). Der Logikoperator bestimmt, wie die Gruppen zusammenwirken. Wenn logic and ist, müssen alle Gruppen als wahr ausgewertet werden. Wenn logic or ist, reicht eine einzige Gruppe, die als wahr ausgewertet wird.
ConditionGroup enthält ein Array von conditions (einzelne Condition-Objekte). Hier ist das entscheidende Detail: Bedingungen innerhalb einer Gruppe werden mit der gegensätzlichen Logik des übergeordneten ConditionSet verknüpft. Wenn das ConditionSet and verwendet, werden Bedingungen innerhalb jeder Gruppe mit or verknüpft. Wenn das ConditionSet or verwendet, nutzen Bedingungen innerhalb jeder Gruppe and.
Dieses gegensätzliche Logikmuster macht das Schema ausdrucksstark, ohne tiefe Verschachtelung zu erfordern. Damit können Sie Aussagen wie "(amount > 50000 ODER Kundentyp entspricht Enterprise) UND Region ist nicht leer" mit nur zwei Gruppen in einem and-ConditionSet erstellen. Die erste Gruppe würde zwei Bedingungen enthalten (amount und customer type, mit or kombiniert, weil das übergeordnete Element and ist), und die zweite Gruppe würde eine Bedingung für die Regionsprüfung enthalten.
Condition ist eine einzelne Auswertung. Sie referenziert eine field_id (die UUID eines anderen Felds auf dem Dokument), einen operator und einen optionalen value für den Vergleich.
Operator-Referenz
Firma.dev unterstützt 10 Vergleichsoperatoren für bedingte Felder:
is_filled prüft, ob ein Feld überhaupt irgendeinen Wert hat. Nützlich, um Folgefelder anzuzeigen, wenn ein Unterzeichner beginnt, einen Abschnitt auszufüllen. is_empty ist das Gegenstück und eignet sich gut dafür, ein Ausweichfeld zu verlangen, wenn ein Primärfeld leer bleibt.
equals und not_equals führen exakte Wertvergleiche durch. Zeigen Sie Felder für den Ehepartner an, wenn der Familienstand "Verheiratet" entspricht, oder blenden Sie einen Abschnitt aus, wenn das Land nicht "US" entspricht.
contains und not_contains prüfen auf Teilzeichenfolgen. Sie könnten compliancebezogene Felder anzeigen, wenn ein Beschreibungsfeld "reguliert" enthält, oder einen Abschnitt überspringen, wenn Notizen kein bestimmtes Schlüsselwort erwähnen.
greater_than, less_than, greater_than_or_equal und less_than_or_equal behandeln numerische Vergleiche. Das sind die Operatoren, zu denen Sie greifen würden, wenn Sie Logik auf Basis von Schwellenwerten bauen, etwa wenn bei einem Betrag über 10.000 eine Genehmigung durch den Manager erforderlich ist oder wenn bei einem Vertragswert unter einer bestimmten Zahl vereinfachte Bedingungen angewendet werden.
Wie Bedingungen in der Praxis aussehen
Das API-Änderungsprotokoll 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 Eigenschaft required_conditions nimmt ein ConditionSet mit and-Logik, einer einzelnen Gruppe und einer einzelnen Bedingung mit dem Operator is_filled auf:
Die field_id verweist auf die UUID des Felds, das Sie auswerten. In diesem Fall wird das aktuelle Feld immer dann erforderlich, wenn das referenzierte Feld irgendeinen Wert hat. Wenn es leer ist, wird das Feld wieder optional.
Sie können auf diesem Muster in mehrere Richtungen aufbauen. Für bedingte Sichtbarkeit würden Sie dieselbe ConditionSet-Struktur unter visibility_conditions statt unter required_conditions verwenden. Ein Textfeld "Spouse Name", das nur erscheint, wenn eine Checkbox "Married" aktiviert ist, würde visibility_conditions mit einer einzelnen is_filled-Bedingung verwenden, die auf die UUID des Checkbox-Felds zeigt.
Für Logik mit mehreren Bedingungen fügen Sie mehr Gruppen oder mehr Bedingungen innerhalb von Gruppen hinzu. Wenn ein Feld für eine Compliance-Zertifizierung nur dann erforderlich sein soll, 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, jeweils mit einer Bedingung. Die erste Gruppe prüft den Betrag mit greater_than, die zweite prüft das Land mit equals.
Das ausdrucksstärkste Muster verwendet die Regel der gegensätzlichen Logik. Angenommen, Sie möchten einen Abschnitt "Special Terms" anzeigen, wenn (amount > 50.000 ODER Kundentyp entspricht "Enterprise") UND Region ist nicht leer. Sie würden die logic des ConditionSet auf and setzen und zwei Gruppen verwenden. Die erste Gruppe enthält zwei Bedingungen (amount und customer type), 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, gut lesbare Struktur, die sonst verschachtelte boolesche Bäume erfordern würde.
Serverseitige Durchsetzung
Alle Bedingungen werden serverseitig ausgewertet, wenn der Unterzeichner sie übermittelt. Das ist nicht optional, und es ist nichts, was durch clientseitige Manipulation umgangen werden kann.
Wenn ein Feld bedingt erforderlich ist und die Bedingung zum Zeitpunkt der Übermittlung als wahr ausgewertet wird, gibt die API einen Validierungsfehler zurück, wenn dieses Feld leer ist. Wenn visibility_conditions eines Felds als falsch ausgewertet werden, wird das Feld verborgen und bei der Validierung vollständig übersprungen. Keine Sonderfälle, keine Race Conditions zwischen Ihrer UI und dem Backend.
Für Compliance-Workflows ist das wichtig. Die Bedingungen, die Sie in der API definieren, sind die Bedingungen, die durchgesetzt werden, ohne Ausnahme. Ihre clientseitige UI kann die Sichtbarkeit und Erforderlichkeitszustände in Echtzeit rendern, damit der Unterzeichner ein gutes Erlebnis hat, aber die maßgebliche Quelle liegt serverseitig.
Wo Bedingungen funktionieren
Bedingte Felder sind in jeder Oberfläche von Firma.dev verfügbar: in der UI des Vorlageneditors, in der UI des Editors für Signaturanforderungen, im eingebetteten Vorlageneditor, im eingebetteten Editor für Signaturanforderungen und in der vollständigen REST-API für sowohl Vorlagen als auch Signaturanforderungen.
Bedingungen, die über die API gesetzt werden, erscheinen und werden in allen UI-Oberflächen korrekt ausgewertet, und Bedingungen, die über die Editoren konfiguriert werden, sind vollständig über die API zugänglich. Zwischen den visuellen Werkzeugen und der programmatischen Schnittstelle gibt es keine Funktionslücke.
Erste Schritte
Bedingte Felder wurden als Teil von Firma.dev API v1.10.0 veröffentlicht. Sie sind vollständig ergänzend und bringen keine inkompatiblen Änderungen mit sich. Felder ohne Bedingungen funktionieren weiterhin genau so wie zuvor, und bestehende Integrationen benötigen keine Anpassungen.
Sie können required_conditions und visibility_conditions ab heute bei jedem Feldobjekt verwenden. Sehen Sie sich das API-Änderungsprotokoll für die vollständige Schemakonfiguration und die API-Dokumentation für die komplette Feldspezifikation an.
Firma.dev berechnet €0.029 pro Umschlag ohne monatliche Mindestbeträge, ohne Sitzplatzgebühren und ohne Vorabverpflichtungen. Wenn Sie Signatur-Workflows aufbauen, die sich anhand der Eingaben des Unterzeichners anpassen müssen, ermöglichen bedingte Felder es Ihnen, diese Logik dorthin zu verlagern, wo sie hingehört: in die API, bei jeder Übermittlung durchgesetzt.
Starten Sie kostenlos mit Firma.dev, keine Kreditkarte erforderlich.
Verwandte Artikel
Unsere Plattform wurde entwickelt, um Unternehmen jeder Größe zu befähigen, intelligenter zu arbeiten und ihre Ziele mit Zuversicht zu erreichen.
