Teilweiser Dokumentdownload und Wasserzeicheneinstellungen (API v1.16.0)

API v1.16.0 führt zwei Funktionen ein, die einen häufigen Schmerzpunkt lösen: das Herunterladen von Dokumenten zu Signaturanfragen, bevor jeder Unterzeichner fertig ist, und die Steuerung, wie diese Teil-PDFs mit einem konfigurierbaren Wasserzeichen aussehen.

Dokumente in jeder Phase herunterladen

Vor diesem Update konnten Sie ein PDF einer Signaturanfrage erst herunterladen, nachdem alle Unterzeichner abgeschlossen hatten. Das funktioniert gut für einfache Vereinbarungen zwischen zwei Parteien, bricht aber zusammen, wenn Sie Verträge mit mehreren Unterzeichnern haben, bei denen Rechts- oder Compliance-Teams den Fortschritt sehen müssen, bevor die letzte Unterschrift gesetzt wird.

Der neue Endpunkt GET /signing-requests/{id}/download gibt eine vorab signierte Download-URL für das Dokument in seinem aktuellen Zustand zurück. Er funktioniert für jeden Status einer Signaturanfrage: in Bearbeitung, storniert, abgelehnt und abgelaufen.

Für abgeschlossene Signaturanfragen erhalten Sie wie bisher das endgültig signierte PDF. Für alles andere erhalten Sie einen Schnappschuss, der nur die Felder enthält, die von bereits abgeschlossenen Unterzeichnern ausgefüllt wurden. Felder ausstehender Unterzeichner werden vollständig ausgelassen, sodass das Dokument genau widerspiegelt, was bisher ausgeführt wurde.

Jedes Teil-PDF enthält außerdem eine Seite mit Prüfprotokoll, die eine Status-Tabelle pro Unterzeichner und eine Belegstruktur bietet und Ihnen so einen klaren Nachweis darüber gibt, wer unterschrieben hat, wer nicht und wann.

Um Teil-Downloads für eine Signaturanfrage zu aktivieren, setzen Sie allow_partial_download: true in den Einstellungen der Signaturanfrage. Das Dokument wird bei der ersten Anforderung bei Bedarf generiert und für weitere Aufrufe zwischengespeichert. Wenn das Dokument noch nicht generiert wurde, erhalten Sie einen 503 mit dem Header Retry-After.

Wasserzeichensteuerung pro Arbeitsbereich

Einige Teams möchten Teil-PDFs eindeutig als unvollständig gekennzeichnet sehen. Andere möchten saubere Dokumente, die sie ohne visuelle Ablenkung an Stakeholder weiterleiten können. Die neue Einstellung show_partial_watermark in den Arbeitsbereichseinstellungen gibt Ihnen diese Kontrolle.

Wenn sie aktiviert ist, enthalten Teil-PDFs über jede Seite hinweg ein diagonales Wasserzeichen mit dem Text "IN PROGRESS — NOT YET EXECUTED". Wenn sie deaktiviert ist (die Standardeinstellung), wird das Dokument ohne Wasserzeichen heruntergeladen.

Dies ist eine Einstellung auf Arbeitsbereichsebene. Wenn Sie also Customer Workspaces verwenden, um die Kunden Ihrer Plattform zu trennen, kann jeder Arbeitsbereich seine eigene Wasserzeichenpräferenz haben.

API-Details

Hier ist die kurze Zusammenfassung der Neuerungen in der API:

• Neuer Endpunkt: GET /signing-requests/{id}/download gibt eine vorab signierte download_url mit einem Zeitstempel expires_at zurück

• Neue Einstellung: allow_partial_download (boolean) in den Einstellungen der Signaturanfrage aktiviert Teil-Downloads

• Neue Arbeitsbereichseinstellung: show_partial_watermark (boolean | null) steuert das diagonale Wasserzeichen auf Teil-PDFs

• Unterstützte Status: finished, in_progress, cancelled, declined, expired

Die vollständige Endpunktspezifikation finden Sie in den Dokumenten zum Herunterladen von Signaturanfragen. Hinweise zur Migration finden Sie im API-Änderungsprotokoll.

Dies ist ein nicht brechendes Update. Es gibt keine Änderungen am bestehenden Verhalten, und bestehende Integrationen funktionieren weiterhin ohne Anpassung.

Los geht's

Wenn Sie die Firma.dev API bereits verwenden, können Sie den neuen Endpunkt sofort nutzen, indem Sie Ihren API-Versionsheader auf v01.16.00 aktualisieren. Wenn Sie neu bei Firma.dev sind, holen Sie sich jetzt Ihren API-Schlüssel und beginnen Sie kostenlos mit dem Bauen, keine Kreditkarte erforderlich.