ratum Integrations-API

Mit der Integrations-API schickt dein eigenes System Dokumente zur elektronischen Signatur: Dokument hochladen, Signer und Signaturfelder festlegen, versenden, Status verfolgen und das versiegelte PDF abholen. Signieren, Archivieren und die Verwaltung der API-Keys bleiben im ratum-GUI. Die Dokumente gehören deinem ratum-Konto und erscheinen dort mit dem Badge «via API».

Basis-URL	https://api.ratum.ch/api/v1
Authentifizierung	Authorization: Bearer ratum_live_… (API-Keys)
Format	JSON; Fehler als application/problem+json (Fehlercodes)
Spezifikation	openapi.json (OpenAPI 3.1) · API-Referenz

In 5 Minuten zur ersten Signatur

1. In ratum unter Profil → API-Zugang einen API-Key erzeugen (Anleitung).
2. Den Quickstart in TypeScript oder Python ausführen.
3. Die Einladung im Postfach des Signers öffnen und signieren. Das Skript lädt danach das versiegelte PDF herunter.

Wie ein Dokument durchläuft

createAndSend ──► PUT upload_url ──► /complete ──► Malware-Scan ──► (DOCX → PDF) ──► Versand
                                                                                   │
                                     signed ◄── alle Signer haben signiert ◄── pending

Details, Status und Fehlerfälle: Ablauf & Status.

Leitfäden

• Beta-Onboarding: von der Key-Erzeugung über den Test-Modus bis zum Wechsel auf Live
• API-Keys & Scopes: Key-Präfixe, Scopes, Ablauf, Widerruf
• Ablauf & Status: Einzelschritte vs. createAndSend, Polling, Status
• Signaturfelder & Anker: Koordinaten und Platzhalter {{ratum:signature:1}}
• Eigene Zustellung (delivery: none): Signier-Links selbst ausliefern
• Webhooks: Ereignisse empfangen und Signatur prüfen
• Idempotenz: sichere Wiederholungen mit Idempotency-Key
• Fehlercodes: alle code-Werte und wie du reagierst
• Limits: Rate-Limits pro Key und pro Benutzer, Grössen und Kontingente
• Test-Modus: mit ratum_test_-Keys ohne Kosten entwickeln
• Versionierung & Deprecation: was sich in v1 ändern darf

SDKs

Offizielle Client-Libraries für TypeScript (@ratum/sdk, Node 18+) und Python (ratum, ab Python 3.11, sync und async) werden aus derselben Spezifikation generiert. Sie laden Dateien hoch, setzen den Idempotency-Key, wiederholen bei 429 und transienten 5xx (Letztere nur, wenn der Aufruf sicher wiederholbar ist), pollen bis zum Endstatus und prüfen Webhook-Signaturen. Beide sind auf npm bzw. PyPI veröffentlicht, in Version 0.x (SemVer während des Piloten; Installation siehe Quickstarts). Die Quickstarts zeigen zuerst die API mit fetch bzw. httpx, damit jeder Schritt sichtbar ist, und danach dasselbe mit dem SDK.