Kosten per API

Sie können vor jeder Aktion sehen, was sie kostet, und danach nachvollziehen, was gebucht wurde. Alle Beträge sind Netto-Verkaufspreise Ihrer Organisation in EUR. Mit einem Test-Schlüssel sehen Sie dieselben Preise, es wird aber nie etwas berechnet (charged: false).

1. Vorab schätzen: POST /v1/cost-estimates

Beschreiben Sie, was Sie vorhaben – die Empfänger eines Vorgangs, Identitätsprüfungen oder Zertifikatskäufe. Es wird nichts angelegt, reserviert oder berechnet.

POST /v1/cost-estimates
Authorization: Bearer qgw_test_…
Content-Type: application/json

{
  "recipients": [
    { "role": "SIGNER", "signatureLevel": "SES" },
    { "role": "SIGNER", "signatureLevel": "QES", "certificateKind": "OTP" },
    { "role": "CC" }
  ],
  "certificatePurchases": [{ "kind": "OTP" }]
}

Die Antwort (object: cost_estimate) enthält je Posten eine Zeile mit Menge, Einzelpreis und Betrag, die Summe total und Hinweise in notes. Was Sie dabei wissen sollten:

• Externe Unterzeichner werden je Empfänger berechnet, sobald ihre Signierrunde startet – auch wenn sie nicht unterschreiben – und nach einem Neustart der Runde erneut.
• Freigebende, Betrachter und Kopie-Empfänger (APPROVER, VIEWER, CC) kosten nichts.
• Live-Schlüssel bekommen zusätzlich withinSpendLimit und spendLimit (siehe unten).

Scope: billing:read.

2. Beim Senden prüfen: dryRun

Die Routen, die Vorgänge anlegen oder senden, kennen ?dryRun=true: Die Antwort ist eine Vorschau mit Prüfung und Kosten, verändert aber nichts. Beispiele:

• POST /v1/envelopes/{id}/send?dryRun=true – Vorschau envelope_send_preview mit costPreview und withinSpendLimit,
• POST /v1/envelopes?dryRun=true (mit send: true im Body) – dasselbe für einen Vorgang, der noch gar nicht existiert,
• POST /v1/templates/{id}/envelopes?dryRun=true – Vorgang aus einer Vorlage,
• POST /v1/submissions/{id}/envelope?dryRun=true – Vorgang aus einem Formular-Eingang,
• POST /v1/envelopes/{id}/restart-external-round?dryRun=true – Kosten eines Neustarts der Signierrunde.

3. Monatliches Ausgabenlimit

Im Dashboard legen Sie für Ihre Organisation ein monatliches Ausgabenlimit fest. Mit einem harten Limit lehnt die API Live-Aktionen ab, die es überschreiten würden: 403 / 9017, bevor etwas passiert. Ob eine Aktion noch passt, zeigen withinSpendLimit in den Vorschauen und spendLimit in der Kostenschätzung. Für Test-Schlüssel gilt kein Limit.

4. Nachvollziehen, was gebucht wurde

Posten mit Preis 0 (etwa das Siegel des Nachweisprotokolls) stehen mit included: true in der Liste und werden nie berechnet. Jeder Posten trägt seine Kontingent-Klasse billingClass: INCLUDED (aus dem Kontingent), INCLUDED_COMPANION (Aufschlag eines Postens aus dem Kontingent), OVERAGE (Mehrverbrauch zum Überschreitungspreis) oder STANDARD (ohne Kontingent). Die Klasse wird bei der Buchung festgelegt und ändert sich nicht. Neue Rechnungen meldet das Ereignis invoice.created (Scope billing:read).

5. Kontingent abfragen: GET /v1/quota

Hat Ihre Organisation einen Vertrag mit Kontingent, zeigt GET /v1/quota (Scope billing:read) den Stand im laufenden Kalendermonat (Europe/Berlin), je Kontingent:

• granted (Menge des Monats samt Bonus), used, reserved (von offenen Aktionen gehalten) und remaining (nie negativ),
• overage: bisher gebuchter Mehrverbrauch mit Menge und Betrag (netto) zum Überschreitungspreis,
• forecast.exhaustedOn: der Tag, an dem das Kontingent beim Tempo dieses Monats aufgebraucht ist (null, wenn es bis Monatsende reicht).

contract.hardStop: true heißt: Ist das Kontingent samt Kulanz aufgebraucht, lehnt die API neue kostenpflichtige Live-Aktionen mit 403 / 9017 ab. Ohne Vertrag ist contract null und pools leer. Kontingente gelten nur für Live-Nutzung: Test-Schlüssel erhalten pools: []. creditLimit.status ist eine Ampel (ok, near, reached) ohne Beträge; billingHold.status (none, announced, active) zeigt, ob neue kostenpflichtige Live-Aktionen wegen überfälliger Rechnungen pausiert sind oder eine Pause angekündigt ist.