Billing-App

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.

 Verwalten von Preislisten

Um Metriken anzuliefern, musst du die Metriken an die Billing-App übertragen.

Zum Übertragen der Metriken öffnest du zunächst das d.velop cloud center und navigierst zur Einstellungsseite deiner App.

Mit der Schaltfläche Metriken im Dialog Preisgestaltung öffnest du die Preislistenverwaltung.

In der Preislistenverwaltung wird eine Liste deiner Preislisten inklusive Anlagedatum angezeigt. Anhand des Status kannst du sehen, welche Preislisten aktiv oder noch bearbeitbar sind. Verwende die Schaltfläche NEUE PREISLISTE, um eine neue Preisliste zu erstellen.

Im Dialog Metriken sind alle Metriken der aktuellen Preisliste aufgeführt. Die Abrechnung nach Benutzern und Monat ist weitläufig etabliert. Du kannst sie mit geringem Aufwand implementieren. Bei der Erstellung der ersten Preisliste erzeugt die Billing-App automatisch eine Metrik 'UserMonth'. Wenn du eine neue Preisliste erstellst, wird jeweils die letzte Preisliste kopiert. Durch Auswahl einer Metrik oder den Button 'METRIK HINZUFÜGEN' gelangst du in den Metrikdialog, in welchem Du Metriken natürlich auch löschen kannst, wenn du sie nicht mehr benötigst.

Im Metrikdialog trägst du den eindeutigen Schlüssel der Metrik sowie den Preis und die Einheit (z.B Benutzer) ein. Die Billing-App ermittelt bei der Übermittlung der Metrikdaten den jeweils gültigen Preis pro Mandanten. Die weiteren Felder dienen der Darstellung in der Kostenübersicht des Kunden und der Preisübersicht im Store. Du kannst Metriken solange ändern und löschen, bis du die Preisliste aktivierst.

Sobald du mit deinen Änderungen zufrieden bist, kannst du die Preisliste aktivieren. Beim Buchen einer App wird dem Mandanten die jeweils aktuellste aktive Preisliste zugeordnet.

 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
    },
  ]
}
EigenschaftTypBeschreibung PflichtAnmerkung
usage[]ListeDie Eigenschaft Usage enthält die Nutzdaten der App. Die Eigenschaft enthält ein oder mehrere Usage-Objekte.Ja
usage[].metricStringEindeutiger Schlüssel der Metrik. Ja
usage[].quantityNummerEnthält die Anzahl der zu buchenden Einheiten. Du kannst Gleitkommawerte angeben. Ja
usage[].timestampDatumDatum der Buchung im ISO-8601 Format. Ja

Response

StatusBeschreibung
202Leistung erfolgreich aufgezeichnet.
400Ungültige Anfrage.

Response-Body


Content-Type: application/json

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

EigenschaftTypBeschreibungPflichtAnmerkung
consumed[]ListeDie Eigenschaft Consumed enthält die erfolgreich verarbeiteten Buchungen. Die Eigenschaft enthält ein oder mehrere Consumed-Objekte.nein
consumed[].metricStringEindeutiger Schlüssel der Metrik.Ja
consumed[].quantityNummerEnthält die Anzahl der zu buchenden Einheiten. Du kannst Gleitkommawerte angeben. Ja
consumed[].timestampDatumDatum der Buchung im ISO-8601 Format.Ja
rejected[]ListeDie Eigenschaft Rejected enthält die nicht verarbeiteten Buchungen. Die Eigenschaft enthält ein oder mehrere Rejected-Objekte.nein
rejected[].metricStringEindeutiger Schlüssel der Metrik.Ja
rejected[].quantityNummerEnthält die Anzahl der zu buchenden Einheiten. Du kannst Gleitkommawerte angeben. Ja
rejected[].timestampDatumDatum der Buchung im ISO-8601 Format.Ja