Billing-APP

Only available in german

Billing-App

Einleitung

In diesem Abschnitt findest du allgemeine Informationen zur Billing-App, dem Funktionsumfang sowie zu den Kenntnissen, die hilfreich beim Programmieren von Funktionen und Anpassungen sind.

Über die Billing-App

Die Billing-App richtet sich an zwei Benutzergruppen:

d.velop cloud-Kunden, die die Kosten für die Nutzung der d.velop cloud einsehen möchten.
App-Builder, die erbrachte Leistungen für Kunden zur Abrechnung an d.velop melden möchten.

App-Builder müssen erbrachte Leistungen in Form von sogenannten Metriken an die Billing-App übermitteln. Metriken sind zähl- oder messbare Werte, die den Leistungsumfang einer App für einen Kunden beschreiben. Die Metriken sind typischerweise am fachlichen Mehrwert des Kunden orientiert und damit für ihn verständlich und nachvollziehbar.

Beispiele:

Eine App zur Verwaltung von Urlaubsantragsprozessen misst, wie viele unterschiedliche Benutzer die App im jeweiligen Monat nutzen.
Eine App zur Speicherung von Dokumenten misst, wie viel Speicherkapazität in Gigabyte für Daten eines Kunden verwendet werden.

Es handelt sich dabei um einzelne Ereignisse (die Urlaubsantrags-App wurde genutzt) oder um kontinuierliche Tätigkeiten ("gespeicherte Gigabyte"). Einzelne Ereignisse können direkt gezählt werden. Kontinuierliche Tätigkeiten müssen immer im Bezug zum Zeitraum gemessen werden, in dem sie durchgeführt und gemessen werden. Die kontinuierliche Tätigkeit "gespeicherte Gigabyte" müsste beispielsweise als "durchschnittliches Volumen in der letzten Stunde" gemessen werden.

Die Billing-App nimmt die angelieferten Daten entgegen und archiviert sie. Am Ende jedes Monats werden die Daten automatisch aggregiert und zur Abrechnung gebracht.

Um eine hohe Transparenz für Kunden über die angefallenen bzw. noch zu erwartenden Kosten zu gewährleisten, empfehlen wir Daten entweder direkt nach Eintreten des Ereignisses oder im Stundenintervall zu melden.

Preise auf der d.velop cloud-Plattform werden immer in Euro angegeben. Die Billing-App verarbeitet Preise mit einer Genauigkeit von 8 Stellen nach dem Komma, der kleinste mögliche Betrag ist 0,00000001 Euro. Auf der Abrechnung für Kunden werden Euro-Beträge auf ganze Eurocent nach kaufmännisch üblichen Regeln gerundet.

Die Summe der Metriken, die eine App definiert, wird als Preisliste bezeichnet. Im Laufe der Zeit werden sich Preise und unter Umständen auch die abzurechnenden Metriken ändern. Der Kunde bestätigt bei der Buchung einer App auch die zugrundeliegende Preisermittlung. Du kannst ihn daher nicht einseitig auf eine neue Preisliste setzen. Du solltest für Übergangszeiträume alte und neue Metriken parallel liefern. Deine Preisliste kannst du jederzeit ändern. Sobald du eine neue Preisliste aktivierst, nutzen neue Kunden die neue Preisliste. Bei Abrechnungen für Bestandskunden gilt weiterhin die Preisliste, die zum Zeitpunkt der Buchung aktiv war.

Verwenden der API-Funktionen

Nachfolgend erfährst du, wie du die Programmierschnittstelle der Billing-App für eigene Entwicklungen nutzen kannst.

Alle hier genannten APIs setzen eine gültige App-Authentifizierungssitzung voraus. Details zum Erstellen einer solchen Sitzung findest du in der Dokumentation der IdentityProvider-App. Bitte beachte den Abschnitt der die Inter-App-Kommunikation behandelt, da deine App die Nutzdaten unabhängig vom angemdelten Benutzerkontext sendet.

Grundlegendes zu schreibenden Zugriffen

Beim Aufrufen der API mit der HTTP-POST-Methode musst du den Header Origin angeben. Der Wert des Headers muss der aufrufenden URL ohne Pfad entsprechen. Bei einem lesenden Aufruf (z.B. mit der HTTP-GET-Methode) musst du den Header nicht angeben.

Mit dem Festlegen eines Wertes für den Header Origin vermeidest du CSRF-Angriffe (Cross-site Request Forgery).

Request

POST /billing/metrics/usage
Origin: https://exampletenant.d-velop.cloud

Wenn der Header fehlt, wird die Anforderung mit dem Statuscode HTTP 403 Forbidden abgelehnt.

Melden von erbrachten Leistungen

Um der Billing-App erbrachte Leistungen zu melden, sende wie im Folgenden beschrieben eine HTTP-POST-Anfrage an die Billing-App. Du kannst in einem Post eine beliebige Anzahl unterschiedlicher Metriken anliefern. Dadurch lassen sich Anwendungsfälle abbilden, bei denen mehrere Metriken involviert sind. Bei Preislistenänderungen werden Kunden nicht automatisch auf eine neue Preisliste migriert. Du hast also die Möglichkeit, Metriken der alten und der neuen Preisliste zu übermitteln.

Die Billing-App liefert in der Antwort die verarbeiteten und gegebenenfalls die nicht verarbeiteten Metriken zurück.

Du erkennst vollständig verarbeitete Anfragen daran, dass sie in der Antwort eine leere rejected-Liste enthalten. Du musst in deiner App entscheiden, wie du mit zurückgewiesenen Metriken weiter verfahren möchtest. Falls beispielsweise neue Metriken in deiner App abgerechnet werden sollen, diese Metriken aber noch nicht bei allen Kunden aktiv sind, wird die Metrik abgelehnt. Du kannst die Ablehnung ignorieren oder für statistische Zwecke auswerten. Du kannst einmal erfolgreich übertragene Informationen nicht mehr explizit ändern. Eine implizierte Korrektur ist nur möglich, wenn du eine Negativbuchung durchführst.

Gemäß den Grundsätzen ordnungsgemäßer Buchführung müssen Geschäftsvorfälle zeitnah und chronologisch verbucht werden. Entsprechend ist es nicht möglich, in die Zukunft zu buchen. Die Buchung in der Vergangenheit ist auch nur eingeschränkt möglich. Monatsabschluss ist jeweils um 23:59 Uhr am letzten Tag des Monats. Buchungen nach diesem Zeitpunkt werden erst in der nachfolgenden Abrechnung berücksichtigt.

Melde deine erbrachten Leistungen folgendermaßen an die Billing-App:

Request

POST /billing/metrics/usage
Content-Type: application/json

{
  "usage": [
    {
      "metric": string,
      "quantity": number,
      "timestamp": string
    },
  ]
}

Eigenschaft	Typ	Beschreibung	Pflicht
usage	Liste	Die Eigenschaft Usage enthält die Nutzdaten der App. Die Eigenschaft enthält ein oder mehrere Usage-Objekte.	Ja
usage.metric	String	Eindeutiger Schlüssel der Metrik.	Ja
usage.quantity	Nummer	Enthält die Anzahl der zu buchenden Einheiten. Du kannst Gleitkommawerte angeben.	Ja
usage.timestamp	Datum	Datum der Buchung im ISO-8601 Format.	Ja

Response

Status	Beschreibung
202	Leistung erfolgreich aufgezeichnet.
400	Ungültige Anfrage.

Response-Body

Content-Type: application/json

{
  "consumed": [
    {
      "metric": string,
      "quantity": number,
      "timestamp": string
    },
   ],
   "rejected": [
    {
      "metric": string,
      "quantity": number,
      "timestamp": string
    },
   ]
}

Eigenschaft	Typ	Beschreibung	Pflicht
consumed	Liste	Die Eigenschaft Consumed enthält die erfolgreich verarbeiteten Buchungen. Die Eigenschaft enthält ein oder mehrere Consumed-Objekte.	nein
consumed.metric	String	Eindeutiger Schlüssel der Metrik.	Ja
consumed.quantity	Nummer	Enthält die Anzahl der zu buchenden Einheiten. Du kannst Gleitkommawerte angeben.	Ja
consumed.timestamp	Datum	Datum der Buchung im rfc3339 Format.	Ja
rejected	Liste	Die Eigenschaft Rejected enthält die nicht verarbeiteten Buchungen. Die Eigenschaft enthält ein oder mehrere Rejected-Objekte.	nein
rejected.metric	String	Eindeutiger Schlüssel der Metrik.	Ja
rejected.quantity	Nummer	Enthält die Anzahl der zu buchenden Einheiten. Du kannst Gleitkommawerte angeben.	Ja
rejected.timestamp	Datum	Datum der Buchung im rfc3339 Format.	Ja

Weitere API Endpunkte

Die Billing App hält Daten zur Buchung vor und überwacht die Testphasen der Mandanten. Diese Information ist über folgenden Request innerhalb des Mandanten und Usercontext abrufbar. Request

Get /billing/testphase
Origin: https://exampletenant.d-velop.cloud

Zurückgeliefert wird ein json mit der Information ob ein Mandant in der Testphase ist und das entsprechende Enddatum in UTC. Response

Status	Beschreibung
200	Information wird geliefert.

Response-Body

Content-Type: application/json

{
  "show_warning": bool,
  "test_phase_ending_on_utc": string
}

Eigenschaft	Typ	Beschreibung	Pflicht	Anmerkung
show_warning	Boolean	Die Eigenschaft show_warning gibt an das der Tenant sich im Teststatus befindet und nach Ablauf der Testphase ausläuft.	ja
test_phase_ending_on_utc	String	Wenn show_warning wahr ist, enthält dieses Feld das Datum zu welchem die Testphase endet im ISO-8601 Format	Nein