Ablauf & Status

Zwei Wege zum Versand

createAndSend (empfohlen): Ein Request legt Dokument, Signer und Felder an und fordert den Versand an. Danach lädst du nur noch die Datei hoch. Das ist der Weg aus den Quickstarts.

POST /documents/create-and-send   (Idempotency-Key Pflicht)  → 202 + upload_url
PUT  <upload_url>                 (Datei, upload_headers)
POST /documents/{id}/complete

Einzelschritte, z. B. wenn ein Mensch vor dem Versand im GUI prüfen soll:

POST /documents                         → 201 + upload_url (Entwurf)
PUT  <upload_url>
POST /documents/{id}/complete
POST /documents/{id}/signers            (je Signer, Reihenfolge = Signier-Reihenfolge)
POST /documents/{id}/signature-fields   (je Feld, mit signer_id)
POST /documents/{id}/send               (Idempotency-Key Pflicht) → 202

Lässt du den letzten Schritt weg, bleibt das Dokument ein Entwurf mit Badge «via API». Jemand im GUI kann es dann prüfen und selbst senden. API-Entwürfe und gescheiterte (failed) API-Dokumente werden nach 7 Tagen ohne Änderung gelöscht; danach liefert GET 404. Jede Änderung setzt die Frist neu.

«Senden, sobald bereit»

Nach /complete prüft ratum die Datei asynchron auf Malware. DOCX wird anschliessend nach PDF konvertiert. Du musst darauf nicht warten: Ein Versand per API-Key (/send oder createAndSend) wird angefordert (Antwort 202, send_requested: true) und läuft automatisch, sobald das Dokument bereit ist. Ist das Dokument schon bereit, geht es sofort raus, und die Antwort zeigt status: pending. Ist die Vorbereitung bereits gescheitert, kommt der Fehler direkt als 409.

Fehlen Upload oder /complete, bleibt das Dokument ein Entwurf und wird nach 7 Tagen gelöscht, ohne auf failed zu wechseln.

Scheitert die Vorbereitung, wechselt das Dokument auf failed, der Grund steht in failure_code:

failure_code	Ursache
scan_infected	Malware gefunden, Datei entfernt
scan_failed	Scan technisch fehlgeschlagen
conversion_failed	DOCX liess sich nicht nach PDF konvertieren
anchor_not_found	Anker-Platzhalter und Signer passen nicht zusammen (Anker)
anchor_scan_failed	PDF für die Anker-Suche abgelehnt (Seitenlimit, Zeitlimit, gedrehte Seite …)

Status

Dokument (status):

Status	Bedeutung	Endzustand
draft	Entwurf; mit send_requested: true ist der Versand angefordert
pending	versendet, Signer sind dran
signed	alle haben signiert; das Versiegeln läuft im Hintergrund und ist meist nach Sekunden fertig	✓
archived	nach signed im Langzeitarchiv abgelegt, oder im GUI manuell archiviert (dann ohne Siegel)	✓
declined	ein Signer hat abgelehnt	✓
failed	Vorbereitung gescheitert (failure_code)	✓

Signer (signers[].status): pending, signed, declined, expired. Die Signer signieren nacheinander in der angegebenen Reihenfolge. Erst wenn einer signiert hat, wird der nächste eingeladen.

Die Signierfrist (expires_at) ist der Zeitpunkt der letzten Einladung oder Erinnerung plus expiry_days (beim Senden, 1–365, Default 30). Läuft sie ab, wird der Signer expired, und das Dokument bleibt pending.

Bei delivery: none erinnerst du Signer selbst; /resend antwortet dann mit 409. Sonst gilt: Solange ein Signer an der Reihe ist und seine Frist läuft, kannst du ihn mit POST /documents/{id}/signers/{sid}/resend erinnern; ratum erinnert zusätzlich automatisch. Jede Erinnerung, manuell oder automatisch,

• erzeugt einen neuen Signier-Link (der alte wird ungültig),
• verlängert die Signierfrist,
• sperrt weitere Erinnerungen für 15 Minuten: In dieser Zeit antwortet /resend mit 429 rate_limited. Die Erfolgsantwort trägt Retry-After mit dieser Wartezeit.

Abgelaufene Signer

Ist ein Signer expired, lässt sich das Dokument per API derzeit weder erneut senden noch löschen, und es zählt weiter zum Limit der aktiven Dokumente. Erinnere Signer deshalb rechtzeitig vor Fristende.

Status abfragen

GET /documents/{id} liefert Dokument, failure_code und alle Signer in Signier-Reihenfolge.

• Polling: Höchstens alle paar Sekunden abfragen und auf Endzustände sowie expired-Signer prüfen. Die Rate-Limits gelten auch hier.
• Webhooks: In Produktion meldet ratum Statuswechsel an deinen Endpoint (Webhooks).

Ergebnisse abholen

Route	Inhalt
GET /documents/{id}/download/sealed	versiegeltes PDF (application/pdf); kurz nach signed noch 404, bis das Siegel geschrieben ist
GET /documents/{id}/download	Download-URL (15 Minuten gültig) des Arbeitsdokuments, bei DOCX das konvertierte PDF; erst nach erfolgreichem Malware-Scan, sonst 409
GET /documents/{id}/audit	Audit-Trail als JSON
GET /documents/{id}/audit/report	Audit-Report als PDF