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

Seit v1.5 wurden drei API-Releases ausgeliefert, und alle drei sind nicht-breaking, Drop-in-Upgrades. Hier ist, was neu ist und wie man es verwendet.

v1.6.0: Aufteilen von PDF-Downloads und Bereinigung der Feldtypen

Veröffentlicht am 12. Februar 2026

Das meist gewünschte Feature in v1.6 ist das Aufteilen von PDF-Downloads. Bisher erhielt man nach Abschluss eines Signaturauftrags ein einziges kombiniertes PDF, das sowohl das signierte Dokument als auch das Audit-Trail-Zertifikat enthält. Jetzt können Sie sie separat herunterladen.

Zwei neue Felder sind für abgeschlossene Signaturanfragen 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. Dies ist besonders nützlich, wenn Sie das signierte Dokument in einem System und das Audit-Trail in einem anderen speichern müssen oder wenn Ihre Endbenutzer nur das saubere signierte PDF ohne angehängte Zertifikatsseiten benötigen.

v1.6 hat auch die Benennung von 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, bleibt alles funktionsfähig. Wenn Sie die normalisierten Formulare bevorzugen, funktionieren diese ebenfalls.

Vollständiges v1.6 Änderungsprotokoll

v1.7.0: Handgezeichnete Signaturen

Veröffentlicht am 27. Februar 2026

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

Fügen Sie es 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
  }
}

Bei Aktivierung entfernt die Signaturoberfläche vollständig die Optionen für getippte und schriftartbasierte Signaturen. Die Unterzeichner müssen ihre Signatur von Hand zeichnen. Dies ist nützlich für Branchen mit hoher Compliance wie das Gesundheitswesen und Finanzdienstleistungen, bei denen Regulierungsbehörden oder Prüfer ausdrücklich handgezeichnete Signaturen erwarten.

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

Dieses Release hat auch abwärtskompatible Legacy-Einstellungsfelder zum SigningRequest-Schema hinzugefügt. Diese sind ganzzahlig basierte (0/1) Versionen der booleschen Einstellungen, die für ältere Integrationen entwickelt wurden, die dieses Format erwarten. Wenn Sie neu bauen, bleiben Sie beim settings-Objekt. Die Legacy-Felder sind für Teams, die von älteren Systemen migrieren.

Vollständiges v1.7 Änderungsprotokoll

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

Veröffentlicht am 3. März 2026

v1.8 ist das größte der drei. Das Hauptmerkmal ist die E-Mail-Vorlagen-API, die Ihnen die volle Kontrolle über die Benachrichtigungs-E-Mails gibt, die Firma.dev während des Signaturprozesses sendet.

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-Bodies mit Platzhaltern wie {{signer_name}}, {{document_name}} und {{signing_link}}.

Hier ist ein schnelles 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: Arbeitsbereichs-Vorlagen überschreiben Unternehmensvorlagen, die die eingebauten Standardvorlagen überschreiben. Das bedeutet, dass Sie eine unternehmensweite Vorlage festlegen können und diese dann pro Customer Workspace anpassen können, um Szenarien mit White-Labeling zu ermöglichen, bei denen jeder Ihrer Kunden seine eigenen Marken-E-Mails benötigt.

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

Schema-Verbesserungen

v1.8 hat auch mehrere Schema-Verbesserungen geliefert, die wissenswert sind:

Das Template-Schema enthält jetzt Inline-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. Dadurch werden die Antworten vorhersehbarer und leichter in Ihrem Code zu typisieren.

Webhooks erhielten drei neue Felder: description, consecutive_failures, und auto_disabled_at. Die Fehlerverfolgungsfelder sind besonders nützlich für die Überwachung. Wenn ein Webhook zu scheitern beginnt, 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-Spezifikationen korrigiert hat, um den tatsächlichen API-Antworten zu entsprechen. Wenn Ihre Integration bereits die echten Antwortfelder verarbeitet (was sie höchstwahrscheinlich tut), sind keine Änderungen erforderlich.

Vollständiges v1.8 Änderungsprotokoll

Aktualisierung

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

Für das vollständige Änderungsprotokoll mit jeder Schema-Änderung und Migration beachten Sie das API-Änderungsprotokoll in den Dokumenten. Wenn Sie gerade erst mit Firma.dev beginnen, können Sie Ihren API-Schlüssel kostenlos erhalten und noch heute mit dem Aufbau beginnen.

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