In diesem Artikel zeigen wir dir Schritt für Schritt, wie du Daten an die Billing-App liefern kannst, um zentral alle deine Mandanten abzurechnen.

Hol dir eine App-Session

Die Billing-App kann nicht im Benutzerkontext angesprochen werden. Daher benötigst du eine App-Session (AuthSession für Apps). Genaueres hierzu findest in der Dokumentation der Identityprovider-App.

Implementiere einen POST-Handler

Die Identityprovider-App wird dir deine App-Session via HTTP-POST schicken. Daher musst du eine Route innerhalb deiner App bereitstellen, die diesen Request annehmen kann. Die Route kannst du der Identityprovider-App vorgeben. Somit ist sie frei wählbar, z.B.:

/my-app/appsession

An diese Route wird die Identityprovider-App folgendes JSON via HTTP-POST schicken:

{
  authSessionId: 'abcd1234',
  expire: '2021-07-06T02:42:45Z',
  sign: '71b613157c20467b930b60143316900dff4a4f6ac2114932bd8bb12c78146204'
}

Der authSessionId-Wert kann wie eine "normale" AuthSessionId als Bearer-Token genutzt werden.
Der expire-Wert gibt an, wann die App-Session abläuft.
Der sign-Wert muss unbedingt entsprechend der Dokumentation der Identityprovider-App überprüft werden. Wird der Wert nicht überprüft, entstehen erhebliche Sicherheitsrisiken.

Beantrage deine App-Session

Nun kannst du bei der Identityprovider-App deine App-Session beantragen. Schicke hierfür folgenden HTTP-POST an die Identityprovider-App:

curl --request POST \
  --url <SYSTEM_BASE_URI>/identityprovider/appsession \
  --header 'Accept: application/hal+json' \
  --header 'Content-Type: application/json' \
  --header 'Origin: <SYSTEM_BASE_URI>' \
  --data '{
    "appname": "my-app",                // Name deiner App
    "callback": "/my-app/appsession",   // Uri auf der dein POST-Handler die AppSession annehmen kann
    "requestid": "<REQUEST_ID>"           // Eindeutige Request-Id. Beispielsweise kannst du eine GUID würfeln.
  }'

Melde deine Daten an die Billing-App

Mit der erhaltenen App-Session kannst du dich gegenüber der Billing-App authentifizieren und deine Daten anliefern.

Beispielsweise kannst du folgenden HTTP-POST an die Billing-App schicken:

curl --request POST \
  --url <SYSTEM_BASE_URI>/billing/metrics/usage \
  --header 'Accept: application/hal+json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <APP_SESSION>' \
  --header 'Origin: SYSTEM_BASE_URI' \
  --data '{
  "usage": [
    {
      "metric": "braveElephant",
      "quantity": 3,
      "timestamp": "2021-07-05T08:08:32Z"
    },
    ...
  ]
}'

Wie gewohnt findet die Zuordnung zu einem Mandanten über die Basisadresse (SystemBaseUri) statt
Dem Mandanten wird monatlich eine aggregierte Rechnung (über alle Apps) zugestellt.
Um sicherzustellen, dass die Billing-App den Request verarbeitet hat, warte unbedingt den Status 200 - OK des Requests ab. Prüfe, ob die gemeldeten Metriken im Response-Body als consumed gelistet werden:

Content-Type: application/json

{
  "consumed": [
   {
      "metric": "braveElephant",
      "quantity": 3,
      "timestamp": "2021-07-05T08:08:32Z"
    },
   ],
   "rejected": []
}

Best Practice

Liefere deine Metriken möglichst schnell an. Im Idealfall ist das Melden von Metriken Teil deiner Prozesslogik.
Liefere deine Metriken mindestens einmal pro Tag an. So sind die Abrechnungsposten für deine Kunden nachvollziehbar.
Liefere deine Metriken einzeln oder kumuliert an, jedoch auf jeden Fall einheitlich.