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

Wir haben in der letzten Woche zwei API-Releases direkt nacheinander veröffentlicht. Keine Breaking Changes, aber neue Features … alles im Februar 2026. 👊

Version 1.3 brachte benutzerdefinierte E-Mail-Domains und die Nachverfolgung von Kreditkosten. Version 1.4 folgte mit drei neuen Feldtypen und granularen PATCH-Operationen für einzelne Felder.

Beide Releases verfolgen dasselbe Thema: mehr Kontrolle ohne mehr Komplexität. Und keines führt Breaking Changes ein, sodass Sie diese Funktionen in Ihrem eigenen Tempo übernehmen können.

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

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

v1.4.0: Neue Feldtypen und granulare Aktualisierungen

Veröffentlichungsdatum: 31. Januar 2026

Version 1.4 erweitert, was Sie mit Dokumentfeldern tun können und wie Sie sie aktualisieren. Drei neue Feldtypen geben Ihnen mehr Optionen zum Erfassen von Daten. PATCH-Operationen unterstützen jetzt Aktualisierungen einzelner Felder. Und ein neuer template_user_id Parameter macht das Zuordnen von Empfängern explizit.

Drei neue Feldtypen

Die Feldtyp-Enum umfasst jetzt textarea, url und radio_buttons:

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

Der url-Feldtyp

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

Verwenden Sie read_only_value, um die Ziel-URL festzulegen, und format_rules.urlDisplayText, um anzupassen, was 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": "View Terms & Conditions" }
  }
}

{
  "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": "View Terms & Conditions" }
  }
}

{
  "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": "View Terms & Conditions" }
  }
}

Anwendungsfall: Eingebettete AGB und Richtlinien. Wenn Ihr Unterzeichnungs-Workflow erfordert, dass Unterzeichner Nutzungsbedingungen, Datenschutzrichtlinien oder externe Verträge bestätigen, hält der Feldtyp url alles in einem Dokument. 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 vor Abschluss des Workflows auf externe Seiten umzuleiten.

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

Der textarea-Feldtyp

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

PATCH-Operationen für einzelne Felder

Früher bedeutete das Aktualisieren eines einzelnen Felds in einer Vorlage, dass die vollständige Vorlagennutzlast gesendet oder der umfassende PUT-Endpunkt verwendet werden musste. Jetzt unterstützen sowohl die PATCH-Endpunkte für Vorlagen als auch für Signaturanfragen Operationen für einzelne Felder.

Template PATCH (PATCH /templates/{id}) kann aktualisieren:

• Vorlageneigenschaften

• Einen einzelnen Benutzer

• Ein einzelnes Feld (neu in v1.4)

Signing Request PATCH (PATCH /signing-requests/{id}) kann aktualisieren:

• Eigenschaften der Signaturanfrage

• 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 ein:

{
  "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 vorhandenes Feld zu aktualisieren, fügen Sie field.id ein:

{
  "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 die Position eines einzelnen Felds anpassen, den Pflichtstatus eines Felds ändern oder ein neues Feld hinzufügen müssen, ohne die gesamte Vorlagennutzlast neu aufzubauen.

Zuordnung von Vorlagenbenutzern mit template_user_id

Beim Erstellen von Signaturanfragen aus Vorlagen können Sie jetzt template_user_id verwenden, um Empfänger explizit 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 die Zuordnung von Empfängern auf der Eigenschaft order. Das funktioniert weiterhin als Fallback, abertemplate_user_id beseitigt Mehrdeutigkeit. Wenn Ihre Vorlage mehrere Unterzeichner hat und Sie sicherstellen möchten, dass Jane die Rolle „Käufer“ erhält (und nicht die Rolle „Verkäufer“), stellt die explizite Zuordnung sicher, dass die richtige Person die richtigen Felder erhält.

Schema-Änderungen in v1.4

Die Feldtyp-Enum wurde von Folgendem aktualisiert:

["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 die explizite Zuordnung von Vorlagenbenutzern beim Erstellen von Signaturanfragen.

v1.3.0: Benutzerdefinierte E-Mail-Domains und Nutzungstransparenz

Version 1.3 führte die Email-Domains-API für White-Label-E-Mail-Versand, die Nachverfolgung von Kreditkosten für Nutzungstransparenz und die Behandlung des Status declined für Signaturanfragen ein.

Email-Domains-API

Eine vollständige API-Kategorie zum Konfigurieren benutzerdefinierter E-Mail-Domains. Statt dass E-Mails für Signaturanfragen von noreply@firma.dev kommen, können sie von signing@yourbrand.com gesendet werden.

Acht neue Endpunkte:

Neue Schemas:

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

• DomainDnsRecord: Details von DNS-Einträgen zur Domain-Verifizierung

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

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

Benutzerdefinierte E-Mail-Domains passen gut zu Kundenarbeitsbereichen für vollständige White-Label-Bereitstellungen. Jeder Ihrer Kunden erhält einen isolierten Arbeitsbereich mit Vorlagen und Signaturanfragen, die im Unterzeichnererlebnis niemals auf Firma.dev verweisen.

Für einen tieferen Einblick in White-Labeling-Optionen lesen Sie unsere Leitfäden zur White-Label-Dokumentensignatur-API und zu White-Label-E-Signatur-E-Mails.

Nachverfolgung von Kreditkosten

Zwei neue Felder schaffen Transparenz beim Kreditverbrauch:

• credit_cost im Template-Schema: Anzahl der Credits, die beim Senden einer Signaturanfrage aus dieser Vorlage verbraucht werden

• credit_cost im SigningRequest-Schema: Credits, die verbraucht wurden, als diese Signaturanfrage gesendet wurde

Eine neue Workspace-Einstellung, show_credit_cost_in_editor, ermöglicht es Ihnen umzuschalten, ob Kreditkosten in den eingebetteten Vorlagen- und Signatur-Editoren angezeigt werden.

Das ist wichtig für SaaS-Plattformen, die Kosten an Kunden weitergeben oder die Nutzung pro Arbeitsbereich nachverfolgen müssen. Wenn die Kreditkosten auf Vorlagen- und Signaturanfrage-Ebene sichtbar sind, können Sie Abrechnungs-Dashboards erstellen, Nutzungswarnungen einrichten oder Kunden ihren Verbrauch anzeigen, ohne separate Analytics-Endpunkte abzufragen.

Mit 0,029 € pro Umschlag bleiben die Kosten vorhersehbar. Aber die Transparenz darüber, wohin diese Credits fließen, hilft Ihnen bei der Optimierung.

Abgelehnter Status der Signaturanfrage

Signaturanfragen unterstützen jetzt den Status declined:

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

• date_declined-Feld zum SigningRequest-Schema hinzugefügt

Wenn ein Unterzeichner die Unterzeichnung ablehnt, sehen Sie das im Status und im Zeitstempel widergespiegelt. Dies ergänzt die Felder declined_on und decline_reason auf SigningRequestUser, die in v1.2 ausgeliefert wurden.

Schema-Verbesserungen in v1.3

Vorlagenfelder:

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

• Beschreibung von multi_group_id erweitert, um die gegenseitig ausschließende Gruppierung von Feldern für Kontrollkästchen und Radiobuttons zu erläutern

• Klarstellen, dass page_number bei 1 beginnt und die Seitenanzahl des Dokuments nicht überschreiten darf

Felder der Signaturanfrage:

• Die gleichen Verbesserungen bei multi_group_id wie bei Vorlagenfeldern

Hinweise zur Migration

Weder v1.3 noch v1.4 führen Breaking Changes ein.

Migration von v1.2 zu v1.3:

• Die Konfiguration von E-Mail-Domains ist verfügbar, aber optional

• Der Status declined wurde der Status-Enum der Signaturanfrage hinzugefügt

• Die Nachverfolgung von Kreditkosten ist für Vorlagen und Signaturanfragen verfügbar

Migration von v1.3 zu v1.4:

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

• Neue PATCH-Funktionen für granulare Feldaktualisierungen

• template_user_id steht für die explizite Empfängerzuordnung zur Verfügung

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

Erstellen Sie Ihre API-Integration für elektronische Signaturen

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

Diese Releases spiegeln wider, was wir von Kunden hören: mehr Flexibilität bei Feldern, besseres White-Labeling und granulare Kontrolle über Vorlagen und Signaturanfragen.

Sehen Sie sich das vollständige API-Änderungsprotokoll für Versionshistorie und Migrationsleitfäden an. Oder beginnen Sie jetzt mit der Entwicklung.

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