Firma.dev API v1.3 + v1.4: Neue Feldtypen, Benutzerdefinierte E-Mail-Domains und Granulare Kontrolle

Wir haben direkt nacheinander zwei neue API-Releases veröffentlicht, erst in der letzten Woche. Keine Breaking Changes, dafür neue Funktionen … alles im Februar 2026. 👊

Version 1.3 wurde mit benutzerdefinierten E-Mail-Domains und der Nachverfolgung von Guthabenkosten freigegeben. Version 1.4 folgte mit drei neuen Feldtypen und granularen PATCH-Operationen für einzelne Felder.

Beide Releases teilen dasselbe Motto: mehr Kontrolle ohne mehr Komplexität. Und keines von beiden führt zu Breaking Changes, sodass Sie diese Funktionen in Ihrem eigenen Tempo einführen können.

Wenn Sie nach einer API-Signaturlösung suchen, die Ihnen Flexibilität bietet, ohne Sie zu Migrationen zu zwingen, dann sieht das genau so aus.

Hier ist alles Neue in v1.3 und v1.4.

v1.4.0: Neue Feldtypen und granulare Updates

Veröffentlichungsdatum: 31. Januar 2026

Version 1.4 erweitert die Möglichkeiten für Dokumentenfelder und deren Aktualisierung. Drei neue Feldtypen bieten Ihnen mehr Optionen zur Datenerfassung. PATCH-Operationen unterstützen jetzt Aktualisierungen einzelner Felder. Und ein neuer Parameter template_user_id macht den Empfängerabgleich explizit.

Drei neue Feldtypen

Das Feldtyp-Enum enthält jetzt textarea, url und radio_buttons:

Der Typ radio funktioniert aus Gründen der Abwärtskompatibilität weiterhin, aber radio_buttons ist ab jetzt der kanonische Name.

Die url-Feldtypen

Der neue Feldtyp url ermöglicht es Ihnen, anklickbare Links direkt in Ihre Signaturdokumente einzubetten. Das Feld ist automatisch auf read_only: true gesetzt, da Unterzeichner den Link anklicken, anstatt ihn zu bearbeiten.

Verwenden Sie read_only_value, um die Ziel-URL festzulegen, und format_rules.urlDisplayText, um anzupassen, was die Unterzeichner sehen:

{
  "field": {
    "type": "url",
    "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
    "page_number": 1,
    "read_only_value": "https://example.com/terms",
    "format_rules": { "urlDisplayText": "Allgemeine Geschäftsbedingungen anzeigen" }
  }
}

{
  "field": {
    "type": "url",
    "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
    "page_number": 1,
    "read_only_value": "https://example.com/terms",
    "format_rules": { "urlDisplayText": "Allgemeine Geschäftsbedingungen anzeigen" }
  }
}

{
  "field": {
    "type": "url",
    "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
    "page_number": 1,
    "read_only_value": "https://example.com/terms",
    "format_rules": { "urlDisplayText": "Allgemeine Geschäftsbedingungen anzeigen" }
  }
}

Anwendungsfall: Eingebettete Bedingungen und Richtlinien. Wenn Ihr Signatur-Workflow erfordert, dass Unterzeichner Nutzungsbedingungen, Datenschutzrichtlinien oder externe Verträge bestätigen, hält der Feldtyp url alles in einem Dokument zusammen. Die Unterzeichner klicken auf den Link, prüfen den referenzierten Inhalt und fahren mit der Unterzeichnung fort. Es ist nicht nötig, mehrere PDFs anzuhängen oder Unterzeichner auf externe Seiten umzuleiten, bevor sie den Workflow abschließen können.

Dies ist besonders nützlich für SaaS-Plattformen, bei denen sich Bedingungen häufig ändern. Aktualisieren Sie die verlinkte URL einmal, und jede neue Signaturanforderung verweist auf die aktuelle Version.

Der Feldtyp textarea

Der Feldtyp textarea unterstützt mehrzeilige Texteingaben. Verwenden Sie ihn, wenn Unterzeichner längere Antworten geben müssen: spezielle Anweisungen, Lieferhinweise oder jeden Freitext, der nicht in ein einzeiliges text-Feld passt.

PATCH-Operationen für einzelne Felder

Bisher bedeutete die Aktualisierung eines einzelnen Feldes in einer Vorlage das Senden des vollständigen Vorlagen-Payloads oder die Nutzung des umfassenden PUT-Endpunkts. Jetzt unterstützen sowohl die Vorlagen- als auch die Signaturanforderungs-PATCH-Endpunkte Operationen für einzelne Felder.

Vorlagen-PATCH (PATCH /templates/{id}) kann Folgendes aktualisieren:

• Vorlageneigenschaften

• Einen einzelnen Benutzer

• Ein einzelnes Feld (neu in v1.4)

Signaturanforderungs-PATCH (PATCH /signing-requests/{id}) kann Folgendes aktualisieren:

• Eigenschaften der Signaturanforderung

• Einen einzelnen Empfänger

• Ein einzelnes Feld (neu in v1.4)

Um ein neues Feld zu erstellen, fügen Sie das field-Objekt ohne eine id hinzu:

{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}

{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}

{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}

Um ein bestehendes Feld zu aktualisieren, geben Sie die field.id an:

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

Dieser granulare Ansatz vereinfacht die Feldverwaltung, wenn Sie eine einzelne Feldposition anpassen, den Erforderlich-Status eines Feldes ändern oder ein neues Feld hinzufügen müssen, ohne den gesamten Payload der Vorlage neu zu erstellen.

Vorlagenbenutzer-Abgleich mit template_user_id

Beim Erstellen von Signaturanforderungen aus Vorlagen können Sie jetzt template_user_id verwenden, um Empfänger explizit den Vorlagenbenutzern zuzuordnen:

{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}

{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}

{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}

Vor v1.4 basierte der Empfängerabgleich auf der Eigenschaft order. Das funktioniert weiterhin als Fallback, aber template_user_id beseitigt Unklarheiten. Wenn Ihre Vorlage mehrere Unterzeichner hat und Sie garantieren möchten, dass Jane die Rolle „Käufer“ (und nicht „Verkäufer“) erhält, stellt der explizite Abgleich sicher, dass die richtige Person die richtigen Felder erhält.

v1.4 Schemaänderungen

Feldtyp-Enum aktualisiert von:

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]

Zu:

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]

Das Empfängerschema enthält jetzt template_user_id für den expliziten Abgleich von Vorlagenbenutzern beim Erstellen von Signaturanforderungen.

v1.3.0: Benutzerdefinierte E-Mail-Domains und Transparenz bei der Nutzung

Version 1.3 führte die Email Domains API für den White-Label-E-Mail-Versand, die Nachverfolgung von Guthabenkosten zur Nutzungstransparenz und die Handhabung des Status „Abgelehnt“ für Signaturanforderungen ein.

Email Domains API

Eine vollständige API-Kategorie zur Konfiguration benutzerdefinierter E-Mail-Domains. Anstatt dass E-Mails mit Signaturanforderungen von noreply@firma.dev gesendet werden, können sie nun von signing@yourbrand.com stammen.

Acht neue Endpunkte:

Neue Schemata:

• Domain: E-Mail-Domain-Konfiguration mit Verifizierungsstatus

• DomainDnsRecord: Details zum DNS-Eintrag für die Domain-Verifizierung

Der Verifizierungsablauf funktioniert wie bei den meisten E-Mail-Domain-Einrichtungen: Fügen Sie Ihre Domain hinzu, verifizieren Sie die Inhaberschaft mit einem TXT-Eintrag, konfigurieren Sie SPF/DKIM/DMARC, schließen Sie die Einrichtung beim E-Mail-Anbieter ab und legen Sie Ihre primäre Versand-Domain fest.

Anwendungsfall: White-Label-Signatur-E-Mails. Wenn Sie eine API-Integration für elektronische Signaturen in Ihr SaaS-Produkt einbauen, erwarten Ihre Kunden, dass E-Mails von Ihrer Marke stammen. Eine E-Mail mit einer Signaturanforderung von contracts@yourplatform.com schafft Vertrauen. Eine E-Mail von noreply@firma.dev wirft Fragen auf.

Benutzerdefinierte E-Mail-Domains lassen sich hervorragend mit Kunden-Workspaces für vollständige White-Label-Bereitstellungen kombinieren. Jeder Ihrer Kunden erhält einen isolierten Workspace mit Vorlagen und Signaturanforderungen, die im Erlebnis des Unterzeichners keinerlei Bezug auf Firma.dev nehmen.

Für einen tieferen Einblick in die White-Label-Optionen lesen Sie unsere Leitfäden zur White-Label-API für Dokumentensignaturen und zu White-Label-E-Mails für elektronische Signaturen.

Nachverfolgung von Guthabenkosten

Zwei neue Felder sorgen für Transparenz bei der Guthabennutzung:

• credit_cost im Schema Template: Anzahl der verbrauchten Guthabenpunkte beim Senden einer Signaturanforderung aus dieser Vorlage

• credit_cost im Schema SigningRequest: Verbrauchte Guthabenpunkte, als diese Signaturanforderung gesendet wurde

Mit der neuen Workspace-Einstellung show_credit_cost_in_editor können Sie festlegen, ob die Guthabenkosten im eingebetteten Vorlagen- und Signatur-Editor angezeigt werden sollen.

Dies ist wichtig für SaaS-Plattformen, die Kosten an Kunden weitergeben oder die Nutzung pro Workspace nachverfolgen müssen. Da die Guthabenkosten auf Vorlagen- und Signaturanforderungsebene sichtbar sind, können Sie Abrechnungs-Dashboards erstellen, Nutzungswarnungen einrichten oder Kunden ihren Verbrauch anzeigen, ohne separate Analyse-Endpunkte abfragen zu müssen.

Mit 0,049 € pro Umschlag bleiben die Kosten kalkulierbar. Die Transparenz darüber, wohin dieses Guthaben fließt, hilft Ihnen jedoch bei der Optimierung.

Signaturanforderung Status „Abgelehnt“

Signaturanforderungen unterstützen jetzt einen declined-Status:

• declined zu den Enum-Werten von SigningRequest.status hinzugefügt

• Feld date_declined zum XML-Schema SigningRequest hinzugefügt

Wenn ein Unterzeichner die Unterschrift ablehnt, spiegelt sich dies im Status und im Zeitstempel wider. Dies ergänzt die in v1.2 eingeführten Felder declined_on und decline_reason bei SigningRequestUser.

v1.3 Schema-Verbesserungen

Vorlagenfelder:

• Feld date_default zum Festlegen von Standarddatumswerten (ISO-8601-Format) hinzugefügt

• Beschreibung von multi_group_id erweitert, um die sich gegenseitig ausschließende Feldgruppierung für Kontrollkästchen und Optionsfelder zu erklären

• Klarstellung, dass page_number 1-basiert indexiert ist und die Seitenzahl des Dokuments nicht überschreiten darf

Signaturanforderungsfelder:

• Gleiche Verbesserungen für multi_group_id wie bei den Vorlagenfeldern

Migrationshinweise

Weder v1.3 noch v1.4 enthalten Breaking Changes.

Migration von v1.2 auf v1.3:

• Die Konfiguration der E-Mail-Domain ist verfügbar, aber optional

• Status declined zum Status-Enum der Signaturanforderung hinzugefügt

• Nachverfolgung von Guthabenkosten für Vorlagen und Signaturanforderungen verfügbar

Migration von v1.3 auf v1.4:

• Feldtyp radio in radio_buttons umbenannt (beide werden aus Gründen der Abwärtskompatibilität akzeptiert)

• Neue PATCH-Funktionen für granulare Feldaktualisierungen

• template_user_id verfügbar für expliziten Empfängerabgleich

Sie können diese Funktionen schrittweise einführen. Bestehende Integrationen funktionieren weiterhin ohne Änderungen.

Erstellen Sie Ihre API-Integration für elektronische Signaturen

Firma.dev wurde für Entwickler entwickelt, die ihren Produkten Dokumentensignaturen hinzufügen müssen, ohne den Aufwand von Enterprise-Verträgen oder komplexen Integrationen zu betreiben. Pay-as-you-go-Preise bei 0,049 € pro Umschlag. Keine Mindestmengen. Keine Verträge.

Diese Releases spiegeln das Feedback unserer Kunden wider: mehr Flexibilität bei den Feldern, besseres White-Labeling und granulare Kontrolle über Vorlagen und Signaturanforderungen.

Prüfen Sie das vollständige API-Changelog für die Versionshistorie und Migrationsleitfäden. Oder beginnen Sie jetzt mit der Entwicklung.

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