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-Versionen veröffentlicht, und alle drei sind nicht-breaking, drop-in-Upgrades. Hier ist, was neu ist und wie man es verwendet.

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

Veröffentlicht am 12. Februar 2026

Das am meisten nachgefragte Feature in v1.6 sind die aufgeteilten PDF-Downloads. Zuvor, wenn ein Unterzeichnungsantrag abgeschlossen wurde, bekam man ein einziges kombiniertes PDF, das sowohl das unterzeichnete Dokument als auch das Zertifikat des Audit-Trails enthielt. Jetzt können Sie sie separat herunterladen.

Zwei neue Felder sind bei abgeschlossenen Unterzeichnungsanträgen 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 neuen Link benötigen, holen Sie einfach den Unterzeichnungsantrag erneut ab. Dies 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 die angehangenen Zertifikatsseiten benötigen.

v1.6 hat auch die Benennung der Feldtypen bereinigt. Die API akzeptiert jetzt sowohl initials als auch initial sowie textarea und text_area und normalisiert sie automatisch. Wenn Ihr Integration bereits die ursprünglichen Namen verwendet hat, ändert sich nichts. Wenn Sie die normalisierten Formen 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 hand_drawn_only-Einstellung ein, um genau das zu erzwingen.

Fügen Sie es zu Ihren Unterzeichnungsantragseinstellungen 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 Unterzeichnungsoberfläche vollständig die getippten und schriftartbasierten Signaturoptionen. Unterzeichner müssen ihre Signatur von Hand zeichnen. Dies ist nützlich für stark regulierte Branchen wie das Gesundheitswesen und Finanzdienstleistungen, wo Regulierer oder Auditoren handgeschriebene Signaturen erwarten.

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

Dieses Release fügte auch rückwärtskompatible Legacy-Einstellungsfelder zum SigningRequest Schema hinzu. Diese sind ganzzahlbasierte (0/1) Versionen der boolean-Einstellungen, die für ältere Integrationen konzipiert sind, die dieses Format erwarten. Wenn Sie neu bauen, bleiben Sie beim settings Objekt. Die Legacy-Felder sind für Teams gedacht, 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 die 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 Unterzeichnungsprozesses 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-Körper 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: Arbeitsbereichsbezogene Vorlagen überschreiben firmenbezogene Vorlagen, die die eingebauten Standards überschreiben. Das bedeutet, dass Sie eine firmenweite Vorlage festlegen und sie dann pro Kundenarbeitsbereich für White-Label-Szenarien anpassen können, bei denen jeder Ihrer Kunden seine eigenen markenspezifischen E-Mails benötigt.

Neben 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, de, el) und die integrierten E-Mail-Vorlagen von Firma.dev werden diese Sprache automatisch nutzen. In Kombination mit überschreibenden Arbeitsbereichsvorlagen können Sie internationale Märkte bedienen, ohne eine separate E-Mail-Infrastruktur zu verwalten.

Schema-Verbesserungen

v1.8 brachte auch mehrere Schema-Verbesserungen, die es zu wissen lohnt:

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-Anfragen, um das vollständige Bild der Konfiguration einer Vorlage zu erhalten.

Unterzeichnungsanforderungsantworten wurden in endpunktspezifische Strukturen aufgeteilt (SigningRequestListItem, SigningRequestCreateResponse, SigningRequestDetail) mit Inline-Daten und standardisierten Zeitstempelfeldern. Dadurch werden die Antworten vorhersehbarer und einfacher in Ihrem Code zu typisieren.

Webhooks erhielten drei neue Felder: description, consecutive_failures und auto_disabled_at. Die Felder zur Fehlerverfolgung sind besonders nützlich für das Monitoring. Wenn ein Webhook fehlerhaft wird, können Sie nun 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 korrigierte, um den tatsächlichen API-Antworten zu entsprechen. Wenn Ihre Integration bereits die tatsächlichen Antwortfelder verarbeitet (was sie fast sicherlich tut), sind keine Änderungen erforderlich.

Vollständiges v1.8 Änderungsprotokoll

Upgrades

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

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

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