Usage & Billing per API integrieren

Mit der Usage & Billing API melden externe Systeme abrechenbare Nutzung an Workspace. Nutzen Sie diesen Schnitt für SaaS-Verbrauch, Maschinenlaufzeiten, USV- und Sensor-Monitoring, Compute-Ressourcen, API-Aufrufe oder prozessbasierte Abrechnung.

Workspace verarbeitet Nutzung in Stufen:

Usage Source -> Metered Resource -> Usage Event -> Meter Aggregate -> Billing Request -> Usage Finance Draft -> Usage Billing Period

Rohereignisse erzeugen keine Rechnung. Finance übernimmt später bewertete Billing-Request-Lines über einen Usage Finance Draft und erstellt daraus Rechnungsentwürfe oder rechtlich relevante Rechnungen.

Quellen registrieren

Legen Sie für jedes externe sendende System eine Usage Source an:

• Pfad: POST /api/v1/usage/sources
• Wichtige Felder: key, name, sourceType, allowedSubjects, rateLimitPerMinute
• Beispieltypen: sensor_gateway, compute_platform, api_gateway, industrial_controller

allowedSubjects begrenzt, welche Messarten eine Quelle senden darf. Verwenden Sie fachliche Subjects wie ups.battery.monitored_hour, machine.operating_hour, energy.kwh_used oder api.call. Mit rateLimitPerMinute begrenzen Sie, wie viele Event-Einträge der source-authentifizierte Maschinenpfad pro Minute annimmt. 0 bedeutet kein konfiguriertes Source-Limit.

Setzen Sie den Status auf:

Maschinen-Credential rotieren

Rotieren Sie nach dem Anlegen einer Source das technische Ingest-Credential.

POST /api/v1/usage/sources/{id}/ingest-secret/rotate
Content-Type: application/json

Die Antwort enthält ingestKey und secret. Speichern Sie das Secret direkt in der Geheimnisverwaltung des sendenden Systems. Workspace zeigt dieses Secret nicht erneut an und speichert nur den Hash.

Die Rotationsantwort enthält:

Rotieren Sie das Secret, wenn ein Collector, Gateway oder Automatisierungsjob ersetzt wird. Der ingestKey bleibt dabei stabil, solange die Source bereits eine technische Kennung hat.

Ressourcen registrieren

Legen Sie jedes abrechenbare Objekt als Metered Resource an:

• Pfad: POST /api/v1/usage/metered-resources
• Wichtige Felder: sourceId, resourceRef, resourceType, name, meterKind, billingSubjectType, billingSubjectId, subscriptionId, billingArrangementKey, rateCardKey, serviceVariantId, unitPriceNet, includedQuantity, minimumAmountNet, maximumAmountNet, pricingUnit, currency

Das externe System sendet später nur sein Source-Credential und resourceRef. Workspace löst Tenant, Billing Subject, Subscription und Preis serverseitig auf.

Setzen Sie meterKind passend zur Metrik:

pricingUnit ist die abrechenbare Einheit. Ingest-Events müssen dieselbe Einheit senden; abweichende Einheiten werden nicht als Nutzung akzeptiert. Verweisen Sie mit serviceVariantId auf eine Produktvariante, die als Service und als nutzungsbasiert gemessen gekennzeichnet ist. Die Produktfamilie dieser Variante muss can_be_service und can_be_measured erlauben. Ohne gültige Service-Variante, Billing Subject oder Usage-Vertrag blockiert Workspace die spätere Finance-Draft-Erzeugung.

Definieren Sie den Messvertrag an der Produktfamilie oder Produktvariante über Attribute. Die Variante überschreibt Familienwerte. Nutzen Sie dafür diese usage-Attribute:

So können Sie externe Quellen und Workspace-eigene Nutzung gleich modellieren: Ein Temperatursensor nutzt zum Beispiel measurement_category: "sensor", meter_kind: "flow" und ein Subject wie sensor.temperature.monitored_hour. Ein vermieteter Rechner kann CPU-Zeit, Speicherplatz oder TCP-Traffic als eigene gemessene Service-Varianten mit Subjects wie compute.cpu_core_hour, compute.storage_gib_hour oder network.tcp_gb führen. Die interne Workspace-Nutzung nutzt dieselbe Struktur mit measurement_category: "nucleus".

Nutzen Sie includedQuantity für Freimengen, minimumAmountNet für einen Mindestbetrag und maximumAmountNet für einen Cap je bewerteter Billing-Request-Line. Ohne diese Felder gilt weiterhin: quantity * unitPriceNet.

Wenn die Nutzung zu einem Abonnement gehört, setzen Sie subscriptionId. Wenn die Nutzung rein verbrauchs- oder nutzerbasiert ohne Abonnement läuft, lassen Sie subscriptionId leer und verwenden Sie ein stabiles billingArrangementKey, zum Beispiel payg-api, active-users-monthly oder industrial-monitoring. Workspace erzeugt aus dem Ingest keine automatische Null-Euro-Rechnung für Monate ohne Nutzung.

Nutzung als Maschine melden

Senden Sie externe Ereignisse an den source-authentifizierten Maschinenpfad:

POST /api/v1/usage/ingest
Content-Type: application/json
X-Workspace-Usage-Key: usg_<public-source-key>
Authorization: Bearer <one-time-secret>

{
  "events": [
    {
      "externalEventId": "ups-berlin-01-2026-06-01T10",
      "resourceRef": "ups-berlin-01",
      "subject": "ups.battery.monitored_hour",
      "quantity": "1",
      "unit": "hour",
      "periodStart": "2026-06-01T10:00:00Z",
      "periodEnd": "2026-06-01T11:00:00Z",
      "occurredAt": "2026-06-01T11:00:00Z",
      "dimensions": {
        "site": "Berlin",
        "batteryHealth": "good"
      }
    }
  ]
}

Der Maschinenpfad benötigt keinen Benutzerkontext und keinen Tenant-Header. Workspace ermittelt Tenant und Source ausschließlich aus dem gültigen Source-Credential. Fehlen Key oder Secret, ist die Source pausiert oder passt das Secret nicht, antwortet Workspace mit 401 und verarbeitet keine Events.

Ressourcen als Maschine deklarieren

Ein externes Gateway kann Ressourcen über dasselbe Source-Credential als Resource Declaration melden:

POST /api/v1/usage/resource-declarations
Content-Type: application/json
X-Workspace-Usage-Key: usg_<public-source-key>
Authorization: Bearer <one-time-secret>

{
  "resources": [
    {
      "resourceRef": "vm-berlin-01",
      "resourceType": "compute_vm",
      "name": "VM Berlin 01",
      "metadata": {
        "cpuCores": 8,
        "memoryGiB": 32,
        "region": "eu-central-1"
      }
    }
  ]
}

Workspace speichert die Deklaration tenant- und source-gebunden. Existiert bereits eine Metered Resource mit derselben resourceRef in derselben Source, antwortet Workspace für diesen Eintrag mit linked. Sonst bleibt die Resource Declaration pending.

{
  "accepted": 1,
  "linked": 0,
  "pending": 1,
  "rejected": 0,
  "results": [
    {
      "resourceRef": "vm-berlin-01",
      "status": "pending",
      "declarationId": "019f6fd2-4d4a-7f72-a55c-0aa4d9ff67b1"
    }
  ]
}

Eine Resource Declaration macht Nutzung noch nicht abrechenbar. Admins prüfen pending Deklarationen über:

• GET /api/v1/usage/resource-declarations
• GET /api/v1/usage/resource-declarations/{id}

Danach aktivieren sie die Resource Declaration oder aktualisieren eine bereits passende Metered Resource. Nur Metered Resources enthalten Billing Subject, optionales Abonnement, Preisfelder, Currency und Aktivstatus.

Tenant-Nutzung an eine Rating Authority melden

Ein System kann seine eigene Tenant-Nutzung als technische Usage Source an eine kompatible Rating Authority melden. Nutzen Sie diesen Modus für Hosting-, SaaS-, Compute-, Monitoring- oder andere Nutzungsmodelle, wenn ein anderes System Rating, Finance Drafts und spätere Rechnungsprozesse verantwortet.

Das Modell unterscheidet dabei Rollen:

Konfigurieren Sie die meldende Installation ausschließlich operatorseitig über locked-global Config-Werte:

Tenant-Admins können diese Werte nicht setzen. Secrets werden als sensitive Konfiguration behandelt und erscheinen nicht im Dashboard oder in Reporting-Run-Antworten.

Starten Sie einen Reporting-Run explizit:

POST /api/v1/usage/reporting-runs
Content-Type: application/json

{
  "periodStart": "2026-06-01T00:00:00Z",
  "periodEnd": "2026-07-01T00:00:00Z",
  "send": true
}

Das lokale System berechnet in V1 fest registrierte Metriken:

Der Reporting-Run sendet idempotente Events an den Maschinen-Ingest des Authority-Systems. Ein Producer sendet keine Preise, keine Kundenbindung und keine Rechnungsaussage. Diese Zuordnung bleibt Aufgabe der Rating Authority über Usage Source, Metered Resource und Rating-Konfiguration.

Eine Rating Authority kann bewertete Ergebnisse als Snapshot importieren:

POST /api/v1/usage/rating-snapshots
Content-Type: application/json

{
  "authorityKey": "external-billing",
  "authorityName": "External Billing",
  "authorityHost": "billing.example.test",
  "externalRef": "tenant-usage-2026-06",
  "status": "rated",
  "periodStart": "2026-06-01T00:00:00Z",
  "periodEnd": "2026-07-01T00:00:00Z",
  "currency": "EUR",
  "preliminary": true,
  "lines": [
    {
      "subject": "identity.member_count",
      "label": "Tenant members",
      "quantity": "12",
      "unit": "member",
      "totalNet": "118.80",
      "currency": "EUR"
    }
  ]
}

Der Import ist tenant-gebunden und idempotent je authorityKey und externalRef. Der Snapshot ist die Quelle für Kosten im Tenant-Dashboard.

Tenant-Admin-Dashboard lesen

Tenant-Admins mit usage_dashboard:read lesen ihren Verbrauch über:

GET /api/v1/usage/dashboard/stats

Die Antwort enthält Nutzungsmetriken, den letzten Reporting-Status und einen Rating-Status. Euro-Beträge erscheinen nur, wenn ein autoritativer UsageRatingSnapshot für die Periode vorliegt oder die Installation explizit als local_authority oder both konfiguriert ist. Ohne Bewertung zeigt das Dashboard „noch nicht bewertet“ statt 0,00 €. Diese Beträge sind ausdrücklich keine Rechnung.

Resource Declaration aktivieren

Aktivieren Sie eine geprüfte Resource Declaration, wenn die gemeldete Ressource abrechenbar werden soll:

POST /api/v1/usage/resource-declarations/{id}/activate
Content-Type: application/json

{
  "billingSubjectType": "customer",
  "billingArrangementKey": "payg-compute",
  "rateCardKey": "compute-vm-v1",
  "unitPriceNet": "0.0400",
  "includedQuantity": "10",
  "pricingUnit": "hour",
  "currency": "EUR",
  "metadata": {
    "region": "eu-central-1",
    "activatedBy": "admin"
  }
}

Workspace erstellt dabei eine Metered Resource im selben Tenant und in derselben Usage Source oder verlinkt eine bereits passende Metered Resource mit derselben resourceRef. Die Resource Declaration erhält danach den Status linked.

Der Aktivierungspfad ist idempotent. Wenn die Declaration bereits mit einer passenden Metered Resource verbunden ist, bleibt die bestehende Metered Resource unverändert. Ändern Sie Preise, Status oder Billing-Zuordnung danach über die Metered-Resource-API.

Das Source-Limit schützt den Ingest vor Lastspitzen. Workspace zählt die Event-Einträge im eingereichten Batch, bevor die fachliche Validierung und Idempotenzprüfung der einzelnen Events läuft. Ein akzeptierter Batch verbraucht daher Quote auch dann, wenn einzelne Events später als duplicate oder rejected zurückkommen. Ungültige oder zu große Batches verbrauchen keine Quote.

Wenn rateLimitPerMinute überschritten ist, antwortet Workspace mit:

HTTP/1.1 429 Too Many Requests
Retry-After: 27
X-Usage-Ingest-Receipt-ID: 019f6fd2-4d4a-7f72-a55c-0aa4d9ff67b1
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-06-01T10:01:00Z

Sender müssen Retry-After beachten, Batches retry-sicher halten und dieselben externalEventId-Werte erneut verwenden. Der Admin-Pfad POST /api/v1/usage/events ist für interne Werkzeuge gedacht und wird von diesem Source-Limit nicht gedrosselt.

Ingest Receipts auswerten

Jeder authentifizierte Maschinen-Batch erzeugt eine Ingest Receipt. Bei erfolgreicher Annahme steht die ID in der Antwort:

{
  "receiptId": "019f6fd2-4d4a-7f72-a55c-0aa4d9ff67b1",
  "accepted": 1,
  "duplicate": 0,
  "rejected": 0,
  "results": []
}

Bei authentifizierten Fehlern wie ungültigem JSON, ungültiger Batchgröße oder Rate-Limit-Überschreitung steht dieselbe ID im Header X-Usage-Ingest-Receipt-ID. Nutzen Sie diese ID in Collector-Logs, Supportfällen und Retry-Diagnosen.

Admins lesen Receipts über:

• GET /api/v1/usage/ingest-receipts
• GET /api/v1/usage/ingest-receipts/{id}

Eine Ingest Receipt speichert:

Workspace speichert in Receipts keine Rohpayloads, keine Header, keine Secrets und keine Bearer-Tokens. Fehlgeschlagene Authentifizierungen erzeugen keine Receipt, weil Workspace dabei keinen geprüften Tenant- und Source-Kontext hat.

Nutzung als Admin melden

Für interne Werkzeuge oder Tests können berechtigte Benutzer weiterhin den tenantgebundenen Admin-Pfad verwenden:

POST /api/v1/usage/events
Content-Type: application/json

{
  "sourceKey": "iot-gateway",
  "events": [
    {
      "externalEventId": "ups-berlin-01-2026-06-01T10",
      "resourceRef": "ups-berlin-01",
      "subject": "ups.battery.monitored_hour",
      "quantity": "1",
      "unit": "hour",
      "periodStart": "2026-06-01T10:00:00Z",
      "periodEnd": "2026-06-01T11:00:00Z",
      "occurredAt": "2026-06-01T11:00:00Z",
      "dimensions": {
        "site": "Berlin",
        "batteryHealth": "good"
      }
    }
  ]
}

Die Kombination aus Source und externalEventId ist idempotent. Wiederholte Events erzeugen keine zweite Nutzung, sondern kommen mit Status duplicate zurück. Events ohne registrierte Resource, ohne erlaubtes Subject oder mit ungültigem Zeitraum werden abgelehnt und nicht abgerechnet.

Aggregatoren einsetzen

Senden Sie bei hoher Frequenz nicht jeden Sensorrohwert direkt. Setzen Sie nahe am Fremdsystem einen Collector oder Aggregator ein, der:

• Messwerte puffert,
• doppelte Messungen entfernt,
• Sekunden- oder Rohwerte in abrechenbare Intervalle verdichtet,
• Ausfälle und Lücken erkennt,
• retry-sichere Batches an Workspace sendet,
• 429-Antworten auswertet und nach Retry-After erneut sendet.

Für Monitoring und Industrieautomatisierung ist Gerät/Zeit oft der stabilste Meter: eine Stunde überwachte USV, eine Maschinenbetriebsstunde, eine produzierte Einheit oder eine verbrauchte Kilowattstunde.

Typische Nutzungsmuster

Verwenden Sie für hochfrequente Sensorik aggregierte Subjects wie sensor.measurement_bucket, wenn Rohwerte für Audit oder Monitoring in einem Fremdsystem bleiben. Workspace verarbeitet abrechenbare Nutzung, nicht jede technische Telemetrie als Zeitreihenarchiv.

Rating ausführen

Der MVP stellt einen manuellen Periodenlauf bereit:

POST /api/v1/usage/rating-runs
Content-Type: application/json

{
  "periodStart": "2026-06-01T00:00:00Z",
  "periodEnd": "2026-07-01T00:00:00Z",
  "markReady": true
}

Der Lauf aggregiert akzeptierte Events der Periode und erstellt Billing Requests mit Billing-Request-Lines. Jede Line enthält Subject, Ressource, Zeitraum, Messmenge, abrechenbare Menge, Einheit, Einzelpreis, Rating-Snapshot und Nettobetrag.

Billing Requests prüfen

Lesen Sie die Ergebnisse über:

• GET /api/v1/usage/meter-aggregates
• GET /api/v1/usage/billing-requests
• GET /api/v1/usage/billing-request-lines
• GET /api/v1/usage/statements
• GET /api/v1/usage/finance-drafts
• GET /api/v1/usage/billing-periods

Die Rechnung enthält später keine Rohereignisse. Rohereignisse bleiben Audit- und Nachweisgrundlage; Rechnungspositionen entstehen aus bewerteten Aggregaten.

Usage Statement erzeugen

Erzeugen Sie einen prüfbaren Verbrauchsnachweis für einen Billing Request:

POST /api/v1/usage/billing-requests/{id}/statement
Content-Type: application/json

{
  "note": "Nachweis für Juni-Abrechnung"
}

Das Statement ist idempotent. Ein erneuter Aufruf erzeugt keinen zweiten Nachweis, sondern liefert alreadyGenerated: true. Workspace erstellt das Statement nur für Billing Requests mit Status requested oder finance_requested und mindestens einer Line.

Ein Usage Statement ist kein rechtlich relevanter Beleg. Es speichert einen Snapshot des Billing Requests und der bewerteten Lines inklusive Messmenge, abrechenbarer Menge, Pricing-Regeln und Rating-Snapshot. Finance kann diesen Nachweis später an einen Rechnungsentwurf oder eine finale Rechnung anhängen.

Finance-Handoff anfragen

Wenn ein Billing Request geprüft ist, markieren Sie ihn für Finance:

POST /api/v1/usage/billing-requests/{id}/finance-handoff
Content-Type: application/json

{
  "note": "Geprüft für Juni-Abrechnung"
}

Der Handoff ist idempotent. Ein erneuter Aufruf erzeugt keine zweite Übergabe, sondern liefert alreadyRequested: true. Workspace akzeptiert den Handoff nur, wenn der Billing Request bereits requested ist, mindestens eine Line enthält und einen positiven Nettobetrag hat.

Nach erfolgreichem Handoff steht der Billing Request auf finance_requested. Erzeugen Sie danach einen Usage Finance Draft, damit Finance einen stabilen Übergabe-Snapshot erhält.

Prüfen Sie vor dem Entwurf die Finance-Readiness:

GET /api/v1/usage/billing-requests/{id}/finance-readiness

Die Antwort enthält status, checks und blockers. Die Schlüssel sind maschinenlesbar und nicht lokalisiert. Wenn eine abrechenbare Usage Line keine Service-Variante hat, die hinterlegte Variante nicht als Service-Variante gekennzeichnet ist oder die Variante kein gemessenes Messmodell beschreibt, liefert der Endpunkt Blocker wie usage_order_service_variant_missing, usage_order_service_variant_not_orderable_service oder usage_order_service_variant_not_measured.

Die Prüfung blockiert außerdem fehlende oder widersprüchliche Abrechnungsgrundlagen:

Die Oberfläche zeigt diese Blocker als Banner. Der Schreibpfad für den Finance Draft verwendet dieselbe Prüfung und erzeugt keinen Entwurf, solange die Readiness blockiert ist.

Usage Finance Draft erzeugen

Erzeugen Sie aus dem Finance-Handoff einen kontrollierten Übergabeentwurf:

POST /api/v1/usage/billing-requests/{id}/finance-draft
Content-Type: application/json

{
  "note": "Entwurf für Juni-Abrechnung vorbereiten"
}

Der Usage Finance Draft ist idempotent. Ein erneuter Aufruf erzeugt keinen zweiten Entwurf, sondern liefert alreadyDrafted: true. Workspace akzeptiert den Entwurf nur für Billing Requests mit Status finance_requested, angefragtem Finance-Handoff, mindestens einer Line und positivem Nettobetrag. Jede abrechenbare Line muss außerdem eine gültige Service-Variante, ein Billing Subject, einen Usage-Vertrag und eine konsistente Meter-Einheit referenzieren.

Ein Usage Finance Draft ist keine Rechnung und erzeugt keine Ledger-Buchung. Er speichert Header, Lines, optionales Statement und Zielhinweise als Snapshot. Finance kann daraus später einen Rechnungsentwurf oder eine finale Rechnung nach den Finance-Regeln erzeugen.

Usage Finance Draft prüfen

Finance kann einen Usage Finance Draft annehmen oder zurückweisen:

POST /api/v1/usage/finance-drafts/{id}/accept
Content-Type: application/json

{
  "note": "Für Rechnungsvorbereitung angenommen"
}

POST /api/v1/usage/finance-drafts/{id}/reject
Content-Type: application/json

{
  "note": "Verbrauchsdaten müssen fachlich geprüft werden"
}

Beide Aktionen sind idempotent, solange der Draft bereits im Zielstatus steht. Workspace erlaubt den Statuswechsel nur aus drafted. Ein angenommener Draft kann im MVP nicht nachträglich zurückgewiesen werden und ein zurückgewiesener Draft kann nicht nachträglich angenommen werden. Die Aktion erzeugt weiterhin keine Rechnung und keine Ledger-Buchung.

Usage Billing Period schließen

Schließen Sie nach Prüfung einen operativen Perioden-Scope:

POST /api/v1/usage/billing-requests/{id}/close-period
Content-Type: application/json

{
  "note": "Juni-Verbrauch geprüft und gesperrt"
}

Workspace legt beim Rating automatisch eine offene Usage Billing Period für den Billing-Scope an. Der Scope besteht aus Billing Subject, Subscription, Arrangement, Währung und Zeitraum. Das Schließen ist idempotent: Ein erneuter Aufruf erzeugt keine zweite Periode und liefert alreadyClosed: true.

Eine geschlossene Usage Billing Period blockiert weitere Rating-Läufe für denselben Scope und Zeitraum. Dadurch bleiben geprüfte Verbrauchsdaten stabil, auch wenn später weitere Rohereignisse eintreffen oder ein Fremdsystem Batches erneut sendet.

Für kontrollierte Korrekturen können Administratoren die Periode wieder öffnen:

POST /api/v1/usage/billing-periods/{id}/reopen
Content-Type: application/json

{
  "note": "Korrekturlauf nach geprüftem Geräteausfall"
}

Ein Reopen erzeugt keine Rechnung und ändert keine Rohereignisse. Es entfernt nur den operativen Rating-Guard für die Periode, damit ein expliziter Korrekturlauf möglich ist.

Grenzen des MVP

Der MVP erzeugt keine finalen Rechnungen, keine Ledger-Buchungen und keine automatische Queue-Verarbeitung. Der Usage Finance Draft ist ein kontrolliertes Übergabeobjekt mit einfacher Finance-Prüfung, aber noch keine Finance-Rechnung. Die API ersetzt keine Zeitreihen-Datenbank für Rohtelemetrie. Für Rate-Card-Versionen, automatische Periodenläufe, Queue-Verarbeitung und vollautomatische Finance-Verarbeitung folgen separate Ausbauschritte.