API für Integratoren: viele Signaturen mit den Zertifikaten Ihrer Personen

Voraussetzungen

• Ein API-Schlüssel mit den nötigen Berechtigungen, angelegt von Inhaber oder Admin unter Entwickler → API-Schlüssel, siehe API-Schlüssel und Berechtigungen. Für Live-Signaturen ein Live-Schlüssel.
• Ein aktives Automatik-Zertifikat der Person. Ihre Software nennt es in jeder Signaturanfrage mit certificateId.
• Die Zustimmung der Person mit dem Kanal „Programmierschnittstelle (API)“, auf Wunsch beschränkt auf bestimmte Schlüssel, siehe Automatik-Zustimmung.
• Antwortet die API im Live-Betrieb mit 409 und Code 9030, ist dieser Weg für Ihre Organisation noch nicht freigeschaltet. Wenden Sie sich an den Support.

Den ganzen Ablauf mit Beispielen zeigt der Guide QES mit Mitgliedern.

Ein Schlüssel für Massenversand

Wartet niemand am Bildschirm auf das Ergebnis, legen Sie einen eigenen Schlüssel an und stellen ihn unter Entwickler → API-Schlüssel → „Zustellung ändern“ auf „Massenversand“. Dann wird jede Signaturanfrage sofort mit 202 eingereiht und nach den interaktiven Anfragen gesendet. Massenversand hat ein eigenes, größeres Kontingent wartender Signaturen. Die Priorität lässt sich nur absenken; für interaktive Anfragen legen Sie einen neuen Schlüssel an.

Gleichmäßig senden

• Verteilen Sie große Mengen über den Tag, statt alles in derselben Minute zu senden. Als Richtwert: für die ganze Organisation höchstens etwa 3 Signaturanfragen pro Sekunde und nie mehr, als die Limits Ihrer Stufe erlauben.
• Ihre Limits nennt GET /v1/me, jede Antwort trägt sie in den Kopfzeilen RateLimit-Policy und RateLimit-Remaining. Mehrere Schlüssel erhöhen das Limit der Organisation nicht.
• Für viele Dokumente auf einmal nutzen Sie POST /v1/signature-batches: standardmäßig bis zu 50 Dokumente in einem Aufruf, der einmal gegen das Limit zählt.

429 und Retry-After

• Bei 429 (Code 9009) und 503 (Code 9010) warten Sie mindestens so viele Sekunden, wie Retry-After angibt, und wiederholen mit demselben Idempotency-Key. So entsteht keine zweite Signatur.
• Wiederholen Sie nur bei 408, 429, 5xx und Netzwerkfehlern, nie bei anderen 4xx. Ohne Retry-After verdoppeln Sie die Wartezeit mit Zufallsanteil.
• Eine Antwort 202 ist kein Fehler: Die Signatur wird im Hintergrund fertig. Das Ergebnis kommt mit den Webhooks signature.completed oder signature.failed oder über GET /v1/signatures/{id}.

Grenzen der Zustimmung

• 403 mit Code 9013: Die Zustimmung fehlt, deckt diesen Kanal, Schlüssel oder diese Vorlage nicht ab, oder die Person hat gesperrt. Die Person muss (neu) zustimmen.
• 409 mit Code 9016 und automatic_daily_limit: Das Tageslimit der Person ist erreicht. Weitere Signaturen gehen erst am nächsten Tag.
• Die Person bekommt an jedem Tag mit solchen Signaturen einen Bericht und kann die Nutzung jederzeit sperren. Planen Sie dafür einen Weg in Ihrer Software ein, etwa eine Meldung an die zuständige Person.