Firma.dev API v1.6, v1.7 und v1.8: PDFs aufteilen, handgezeichnete Unterschriften und benutzerdefinierte E-Mail-Vorlagen

Seit v1.5 wurden drei API-Releases veröffentlicht, und alle drei sind nicht-inkompatible, direkt einsetzbare Upgrades. Hier ist, was neu ist und wie man es verwendet.

v1.6.0: Geteilte PDF-Downloads und Bereinigung der Feldtypen

Veröffentlicht am 12. Februar 2026

Die am häufigsten gewünschte Funktion in v1.6 sind geteilte PDF-Downloads. Früher erhielt man, wenn eine Signaturanfrage abgeschlossen wurde, ein einzelnes kombiniertes PDF, das sowohl das unterzeichnete Dokument als auch das Zertifikat des Audit-Trails enthielt. Jetzt können Sie sie separat herunterladen.

Für abgeschlossene Signaturanfragen sind zwei neue Felder verfügbar:

{
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf"
}

{
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf"
}

{
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf"
}

Beide URLs sind vorab signiert und laufen nach 1 Stunde ab. Wenn Sie einen frischen Link benötigen, rufen Sie einfach die Signaturanfrage erneut ab. Das ist besonders nützlich, wenn Sie das unterzeichnete Dokument in einem System und den Audit-Trail in einem anderen speichern müssen oder wenn Ihre Endnutzer nur das saubere unterzeichnete PDF ohne angehängte Zertifikatsseiten benötigen.

v1.6 hat außerdem die Benennung der Feldtypen bereinigt. Die API akzeptiert jetzt sowohl initials als auch initial sowie textarea und text_area und normalisiert sie automatisch. Wenn Ihre Integration bereits die ursprünglichen Namen verwendet hat, geht nichts kaputt. Wenn Sie die normalisierten Formen bevorzugen, funktionieren diese ebenfalls.

Vollständiges Änderungsprotokoll v1.6

v1.7.0: Handgezeichnete Unterschriften

Veröffentlicht am 27. Februar 2026

Einige Workflows erfordern, dass Unterzeichner ihre Unterschrift physisch zeichnen, anstatt eine getippte oder von einer Schriftart erzeugte Option auszuwählen. v1.7 führt die Einstellung hand_drawn_only ein, um genau das zu erzwingen.

Fügen Sie sie zu Ihren Signaturanfrage-Einstellungen hinzu:

{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}

{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}

{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}

Wenn aktiviert, entfernt die Signatur-Oberfläche getippte und schriftbasierte Signaturoptionen vollständig. Unterzeichner müssen ihre Unterschrift von Hand zeichnen. Das ist nützlich für stark regulierte Branchen wie das Gesundheitswesen und Finanzdienstleistungen, in denen Aufsichtsbehörden oder Prüfer ausdrücklich handschriftliche Unterschriften erwarten.

Die Einstellung ist standardmäßig auf false gesetzt, daher sind bestehende Signaturanfragen nicht betroffen.

Dieses Release hat außerdem abwärtskompatible Legacy-Felder für Einstellungen zum SigningRequest-Schema hinzugefügt. Diese sind ganzzahlbasierte (0/1) Versionen der booleschen Einstellungen und für ältere Integrationen gedacht, die dieses Format erwarten. Wenn Sie etwas Neues bauen, bleiben Sie beim settings-Objekt. Die Legacy-Felder sind für Teams gedacht, die von älteren Systemen migrieren.

Vollständiges Änderungsprotokoll v1.7

v1.8.0: E-Mail-Vorlagen-API und Sprachunterstützung

Veröffentlicht am 3. März 2026

v1.8 ist die größte der drei Versionen. Das Hauptmerkmal ist die E-Mail-Vorlagen-API, mit der Sie die volle Kontrolle über die Benachrichtigungs-E-Mails haben, die Firma.dev während des Signaturprozesses versendet.

Sie können Vorlagen für fünf E-Mail-Typen anpassen: signing_invite, next_signer, signing_expired, signing_cancelled und signing_declined. Vorlagen unterstützen HTML-Inhalte mit Platzhaltern wie {{signer_name}}, {{document_name}} und {{signing_link}}.

Hier ist ein kurzes Beispiel:

PUT /workspace/{workspace_id}/email-templates/signing_invite
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please review and sign using this link: {{signing_link}}</p>"
}

PUT /workspace/{workspace_id}/email-templates/signing_invite
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please review and sign using this link: {{signing_link}}</p>"
}

PUT /workspace/{workspace_id}/email-templates/signing_invite
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please review and sign using this link: {{signing_link}}</p>"
}

Vorlagen folgen einer Hierarchie: Vorlagen auf Arbeitsbereichsebene überschreiben Vorlagen auf Unternehmensebene, die wiederum die integrierten Standardwerte überschreiben. Das bedeutet, dass Sie eine unternehmensweite Vorlage festlegen und sie dann pro Kunden-Arbeitsbereich für White-Label-Szenarien anpassen können, in denen jeder Ihrer Kunden seine eigenen gebrandeten E-Mails benötigt.

Zusätzlich zu benutzerdefinierten Vorlagen fügt v1.8 sowohl Company als auch WorkspaceSettings ein language-Feld hinzu. Setzen Sie es auf eine der sieben unterstützten Sprachen (de, es, it, pt, fr, de, el) und die integrierten E-Mail-Vorlagen von Firma.dev verwenden diese Sprache automatisch. Zusammen mit Überschreibungen auf Arbeitsbereichsebene können Sie internationale Märkte bedienen, ohne eine separate E-Mail-Infrastruktur verwalten zu müssen.

Schema-Verbesserungen

v1.8 hat außerdem mehrere Schema-Verbesserungen ausgeliefert, die man kennen sollte:

Das Template-Schema enthält jetzt eingebettete recipients, fields, settings, page_count und expiration_hours, wenn Sie eine einzelne Vorlage abrufen. Das bedeutet weniger API-Aufrufe, um das vollständige Bild der Konfiguration einer Vorlage zu erhalten.

Signaturanfrage-Antworten wurden in endpunktspezifische Formen (SigningRequestListItem, SigningRequestCreateResponse, SigningRequestDetail) mit eingebetteten Daten und standardisierten Zeitstempelfeldern aufgeteilt. Das macht die Antworten vorhersehbarer und erleichtert das Tippen in Ihrer Codebasis.

Webhooks haben drei neue Felder erhalten: description, consecutive_failures und auto_disabled_at. Die Felder zur Fehlerverfolgung sind besonders praktisch für das Monitoring. Wenn ein Webhook beginnt, Fehler zu verursachen, können Sie jetzt sehen, wie viele aufeinanderfolgende Fehler aufgetreten sind und ob Firma.dev ihn automatisch deaktiviert hat.

Beachten Sie, dass v1.8 auch mehrere Feldnamen in der OpenAPI-Spezifikation korrigiert hat, damit sie zu den tatsächlichen API-Antworten passen. Wenn Ihre Integration bereits die echten Antwortfelder verarbeitet, was sie mit ziemlicher Sicherheit tut, sind keine Änderungen erforderlich.

Vollständiges Änderungsprotokoll v1.8

Aktualisierung

Alle drei Releases sind vollständig abwärtskompatibel. Keine Breaking Changes, keine Migrationsschritte erforderlich. Sie können Ihre API-Version direkt von v1.5 auf v1.8 aktualisieren und alles funktioniert weiterhin wie zuvor, wobei die neuen Funktionen sofort verfügbar sind.

Das vollständige Änderungsprotokoll mit jeder Schemaänderung und jedem Migrationshinweis finden Sie im API-Änderungsprotokoll in der Dokumentation. Wenn Sie gerade erst mit Firma.dev anfangen, können Sie sich Ihren API-Schlüssel kostenlos holen und noch heute mit der Entwicklung beginnen.

Vorherige Versionshinweise: v1.5 | v1.3 und v1.4