ratum Integrations-API

Darstellung

Beta-Onboarding ​

Diese Anleitung führt dich als Beta-Kunde in acht Schritten von null zur ersten Signatur im Test-Modus und danach in den Live-Betrieb. Jeder Schritt verweist auf den Leitfaden mit den Details.

Beta

Die Integrations-API ist in der Beta. api.ratum.ch ist die API-Adresse, docs.ratum.ch die Doku. Die SDKs sind veröffentlicht (npm install @ratum/sdk, pip install ratum, Version 0.x während des Piloten; Installation siehe TypeScript und Python).

1. API-Key im GUI erzeugen ​

  1. In ratum anmelden und Profil → API-Zugang öffnen. API-Zugang setzt einen bezahlten Tarif mit hinterlegter Zahlungsmethode voraus.
  2. Namen vergeben, Modus Test wählen und die Scopes documents:read, documents:write, documents:send und signers:link anhaken. Der Scope webhooks:manage ist für Test-Keys nicht erlaubt: Die Webhook-Routen der API brauchen einen Live-Key mit diesem Scope (im GUI unter Profil → Webhooks nicht nötig).
  3. Erzeugen und den Key sofort in deinen Secret-Store kopieren. ratum zeigt ihn nur einmal an.

Details: API-Keys & Scopes.

2. Mit dem Test-Key entwickeln ​

Ein ratum_test_-Key spricht dieselbe API, verschickt aber nie Mails, belastet kein Kontingent und versiegelt mit Wasserzeichen «TEST» und einem nicht vertrauenswürdigen Test-Zertifikat. Test-Dokumente werden nach 7 Tagen gelöscht, erlaubt sind 50 pro Benutzer in 24 Stunden. Test- und Live-Daten sind strikt getrennt. Ohne eingerichtetes Test-Zertifikat antwortet die API beim Anlegen eines Test-Dokuments mit 503. Details: Test-Modus.

3. Erstes Dokument senden ​

Führe den Quickstart in TypeScript oder Python mit dem Test-Key aus (RATUM_API_KEY=ratum_test_…). Er lädt ein PDF hoch, legt Signer und Felder an und pollt dann den Status. Mit einem Test-Key geht keine Einladung raus: Das Skript wartet, bis du in Schritt 4 den Signier-Link abgerufen und signiert hast. Starte dafür einen zweiten Prozess (z. B. curl) parallel zum laufenden Skript. Ablauf und Status: Ablauf & Status.

4. Signier-Link abrufen (delivery: none) ​

Im Test-Modus geht keine Einladung per Mail raus. Den Signier-Link holst du über den Link-Endpoint, sobald ein Signer an der Reihe ist (Webhook signer.activated oder Polling):

http
POST /api/v1/documents/{document_id}/signers/{signer_id}/link HTTP/1.1
Authorization: Bearer ratum_test_…

Die Antwort enthält url und expires_at. Öffne die URL im Browser und signiere; die Seite zeigt ein TEST-Banner. Jeder Abruf erzeugt einen neuen Link und macht den vorherigen ungültig. Der Key braucht den Scope signers:link. Details: Eigene Zustellung.

AVV/DPA noch offen

Wenn du im Live-Betrieb delivery: none einsetzt, verarbeitest du Signer-Daten und Signier-Links selbst. Die Regelung per Auftragsverarbeitungsvertrag (AVV/DPA) für API-Kunden ist noch nicht abgeschlossen. Sie muss geklärt und der AVV unterzeichnet sein, bevor du delivery: none produktiv nutzt. Frage vorher bei ratum nach dem Stand, auch für den übrigen Live-Betrieb.

5. Webhooks einrichten und Signatur prüfen ​

  1. Unter Profil → Webhooks (oder per POST /webhooks) einen HTTPS-Endpoint registrieren und die Events wählen, z. B. signer.activated, document.completed und document.failed.
  2. Das Secret (ratum_whsec_…) sofort speichern; es wird nur einmal angezeigt.
  3. Mit POST /webhooks/{id}/test ein webhook.ping senden.
  4. In deinem Endpoint jede Anfrage prüfen: HMAC-SHA256 über "<t>.<roher Body>", zeitkonstanter Vergleich, Zeitstempel höchstens 5 Minuten von deiner Uhr abweichend; das Secret geht inklusive ratum_whsec_ in den HMAC ein. Fertige Beispiele für TypeScript und Python stehen im Webhooks-Leitfaden; beide SDKs bringen die Prüfung mit.
  5. Antworte mit 2xx und verarbeite jede Event-id nur einmal (Zustellung ist at-least-once).

Endpoints gelten für Test und Live gemeinsam; es gibt keine getrennten Secrets pro Modus. Test-Dokumente lösen Events mit livemode: false aus, ein webhook.ping trägt immer livemode: true.

6. Fehler behandeln ​

  • Fehler kommen als application/problem+json nach RFC 9457. Verzweige nur auf das Feld code, nie auf detail. Alle Codes: Fehlercodes.
  • Rate-Limits: 10 Requests/s pro Key, 20 pro Benutzer. Bei 429 rate_limited wartest du die Zeit aus Retry-After ab. Siehe Limits.
  • Retry: create-and-send und /send brauchen einen Idempotency-Key. Wiederhole bei Netzwerkfehlern, 429, 5xx und 409 idempotency_key_in_use mit demselben Key und Backoff (Idempotenz). Die SDKs wiederholen in begrenztem Umfang automatisch (standardmässig 2 Versuche).

7. Checkliste: Wechsel von Test auf Live ​

  • [ ] AVV/DPA ist abgeschlossen; Pflicht, wenn du delivery: none einsetzt.
  • [ ] Live-Key (ratum_live_) mit minimalen Scopes erzeugt und im Secret-Store des Produktionssystems hinterlegt. Der Test-Key bleibt in der Entwicklung.
  • [ ] Der Live-Key ist nirgends im Code, in Git, in Logs oder im Browser gelandet.
  • [ ] Entwicklungs-Endpoint gelöscht oder deaktiviert (PATCH /webhooks/{id} mit "enabled": false), sonst erreichen ihn auch Live-Events. Produktiver Endpoint registriert (höchstens 3 pro Konto), Signaturprüfung gegen ein webhook.ping getestet, Secret gespeichert.
  • [ ] Der Code unterscheidet livemode: true von false; wir empfehlen, Test-Events nicht in den Live-Datenbestand zu übernehmen.
  • [ ] Retry mit Idempotency-Key, 429-Handling und Fehlerbehandlung auf code sind umgesetzt.
  • [ ] Ein Probedokument mit Live-Key an dich selbst gesendet, signiert und das versiegelte PDF geprüft (kein TEST-Wasserzeichen, gültiges Siegel).
  • [ ] Bei ratum-Zustellung: Absender-Mails kommen an und landen nicht im Spam.
  • [ ] Der Tarif ist bezahlt; ohne Zahlungsmethode antwortet die API mit 403 plan_required.
  • [ ] Ablaufdatum und Verantwortlichkeit für die Key-Rotation sind festgelegt.

8. Support ​

Bei Fragen, Fehlern oder fehlendem Zugang melde dich bei ratum:

Gib bei einer Fehlermeldung die instance und den code aus der Antwort an sowie die Dokument-ID. Sende nie einen vollständigen API-Key, ein Webhook-Secret oder einen Signier-Link.

ratum · Talent Factory GmbH