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

Wir haben zwei API-Versionen direkt hintereinander ausgeliefert, allein in der letzten Woche. Nichts Untypisches, aber neue Funktionen ... alles im Februar 2026. 👊

Version 1.3 landete mit benutzerdefinierten E-Mail-Domains und Verfolgung der Kreditkosten. Version 1.4 folgte mit drei neuen Feldtypen und granularen PATCH-Operationen für einzelne Felder.

Beide Versionen teilen dasselbe Thema: mehr Kontrolle ohne mehr Komplexität. Und weder führt zu signifikanten Änderungen, sodass Sie diese Funktionen in Ihrem eigenen Tempo übernehmen können.

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

Hier ist alles neu 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 bieten Ihnen mehr Optionen zum Sammeln von Daten. PATCH-Operationen unterstützen jetzt die Aktualisierung einzelner Felder. Und ein neuer template_user_id-Parameter macht das Empfängermatching explizit.

Drei Neue Feldtypen

Der Feldtyp-Enum umfasst nun textarea, url und radio_buttons:

Der radio-Typ funktioniert weiterhin für Abwärtskompatibilität, aber radio_buttons ist der kanonische Name in Zukunft.

Die url Feldtypen

Der neue url-Feldtyp ermöglicht es Ihnen, anklickbare Links direkt in Ihre Signierdokumente einzubetten. Das Feld wird 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 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 Bedingungen und Richtlinien. Wenn Ihr Signierablauf erfordert, dass Unterzeichner Bedingungen der Dienstleistungen, Datenschutzrichtlinien oder externe Verträge anerkennen, hält der url-Feldtyp alles in einem Dokument. Unterzeichner klicken auf den Link, überprüfen die referenzierten Inhalte und fahren mit dem Signieren 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, auf denen sich die Bedingungen häufig ändern. Aktualisieren Sie die verlinkte URL einmal und jede neue Signieranfrage verweist auf die aktuelle Version.

Der textarea Feldtyp

Der textarea-Feldtyp unterstützt die mehrzeilige Texteingabe. Verwenden Sie ihn, wenn Sie Unterzeichner dazu bringen müssen, längere Antworten zu geben: spezielle Anweisungen, Liefernotizen oder beliebige Freitextangaben, die nicht in einzeilige text-Felder passen.

PATCH-Operationen für Individuelle Felder

Früher bedeutete das Aktualisieren eines einzelnen Feldes auf einer Vorlage, die vollständige Vorlagen-Nutzlast zu senden oder den umfassenden PUT-Endpunkt zu verwenden. Jetzt unterstützen sowohl die Template- als auch die Signing Request-PATCH-Endpunkte Einzel-Feld-Operationen.

Vorlagen-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:

• Signing Request-Eigenschaften

• Einen einzelnen Empfänger

• Ein einzelnes Feld (neu in v1.4)

Um ein neues Feld zu erstellen, schließen 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 bestehendes Feld zu aktualisieren, schließen Sie die 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 das Verwaltung von Feldern, wenn Sie die Position eines einzelnen Feldes anpassen, den erforderlichen Status eines Feldes ändern oder ein neues Feld hinzufügen müssen, ohne die gesamte Vorlagen-Nutzlast neu zu erstellen.

Template-Benutzermatching mit template_user_id

Beim Erstellen von Signieranfragen aus Vorlagen können Sie nun template_user_id verwenden, um Empfänger explizit mit Vorlagenbenutzern abzugleichen:

{
  "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 das Empfängermatching auf der order-Eigenschaft. 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" (nicht die Rolle "Verkäufer") erhält, sorgt explizites Matching dafür, 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"]

Empfängerschema enthält jetzt template_user_id für explizites Vorlagenbenutzermatching bei der Erstellung von Signieranfragen.

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

Version 1.3 führte die E-Mail-Domains-API für White-Label-E-Mail-Sendungen ein, die Verfolgung von Kreditkosten für die Nutzungssichtbarkeit und die Behandlung von abgelehnten Status für Signieranfragen.

E-Mail-Domains-API

Eine vollständige API-Kategorie zur Konfiguration benutzerdefinierter E-Mail-Domains. Anstatt dass Signieranfragen-E-Mails von noreply@firma.dev kommen, können sie von signing@yourbrand.com kommen.

Acht neue Endpunkte:

Neue Schemas:

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

• DomainDnsRecord: DNS-Eintragsdetails für Domainverifizierung

Der Verifizierungsfluss funktioniert wie die meisten E-Mail-Domain-Setups: Fügen Sie Ihre Domain hinzu, verifizieren Sie den Besitz mit einem TXT-Eintrag, konfigurieren Sie SPF/DKIM/DMARC, schließen Sie mit dem E-Mail-Anbieter ab und setzen Sie Ihre primäre Sendedomain.

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

Benutzerdefinierte E-Mail-Domains passen gut zu Kundenarbeitsbereichen für vollständige White-Label-Einsätze. Jeder Ihrer Kunden erhält einen isolierten Arbeitsbereich mit Vorlagen und Signieranfragen, die Firma.dev in der Unterzeichnererfahrung niemals referenzieren.

Für einen tieferen Einblick in White-Label-Optionen sehen Sie sich unsere Anleitungen zu White-Label-Dokumentensignatur-APIs und White-Label-e-Signatur-E-Mails an.

Kreditkostenverfolgung

Zwei neue Felder bieten Sichtbarkeit in die Kreditnutzung:

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

• credit_cost im SigningRequest-Schema: Credits, die beim Senden dieser Signaturanfrage verbraucht werden

Eine neue Arbeitsbereichseinstellung, show_credit_cost_in_editor, ermöglicht es Ihnen, umzuschalten, ob Kreditkosten im eingebetteten Vorlagen- und Signatureditor angezeigt werden.

Dies ist wichtig für SaaS-Plattformen, die Kosten an Kunden weitergeben oder die Nutzung pro Arbeitsbereich verfolgen müssen. Mit sichtbaren Kreditkosten auf der Vorlagen- und Signaturanfrage-Ebene können Sie Abrechnungs-Dashboards erstellen, Nutzungswarnungen festlegen oder Kunden ihren Verbrauch anzeigen, ohne separate Analytikendpunkte abzufragen.

Bei €0,029 pro Umschlag bleiben die Kosten vorhersehbar. Aber die Sichtbarkeit, wohin diese Credits gehen, hilft Ihnen, zu optimieren.

Status "Abgelehnt" für Signaturanfragen

Signaturanfragen unterstützen jetzt einen declined-Status:

• Hinzugefügt declined zu SigningRequest.status-Enum-Werten

• Hinzugefügt date_declined-Feld zum SigningRequest-Schema

Wenn ein Unterzeichner sich weigert zu unterschreiben, wird dies im Status und Zeitstempel angezeigt. Dies ergänzt die declined_on und decline_reason-Felder auf SigningRequestUser, die in v1.2 verschifft wurden.

v1.3 Schema-Verbesserungen

Vorlagenfelder:

• Hinzugefügt date_default-Feld zum Einstellen von Standard-Datumswerten (ISO 8601-Format)

• Verbesserte multi_group_id-Beschreibung zur erklärenden gegenseitig ausschließenden Feldgruppierung für Kontrollkästchen und Radiobuttons

• Klärte, dass page_number 1-indiziert ist und nicht die Dokumentseitenzahl überschreiten darf

Felder der Signaturanfrage:

• Gleiche multi_group_id-Verbesserungen wie Vorlagenfelder

Migrationshinweise

Weder v1.3 noch v1.4 führen signifikante Änderungen ein.

Migration von v1.2 zu v1.3:

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

• declined-Status zum Enum für Signaturanfrage-Status hinzugefügt

• Kreditkostenverfolgung verfügbar für Vorlagen und Signaturanfragen

Migration von v1.3 zu v1.4:

• radio-Feldtyp umbenannt zu radio_buttons (beide für Abwärtskompatibilität akzeptiert)

• Neue PATCH-Fähigkeiten für granulare Feldaktualisierungen

• template_user_id verfügbar für explizites Empfängermatching

Sie können diese Funktionen schrittweise übernehmen. Bestehende Integrationen arbeiten weiterhin ohne Modifikation.

Bauen Sie Ihre Elektronische Signatur-API-Integration

irma.dev ist für Entwickler gebaut, die Dokumentensignierung in ihre Produkte integrieren müssen, ohne den Overhead von Unternehmenskontakten oder komplexen Integrationen. Pay-as-you-go-Preise zu €0,029 pro Umschlag. Keine Mindestanforderungen. 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 Signieranfragen.

Schauen Sie sich das vollständige API-Änderungsprotokoll für Versionsgeschichte und Migrationsleitfäden an. Oder fangen Sie jetzt zu bauen.

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