Die Kosten für eine Veranstaltung oder eine Kursfreigabe (Seminar, E-Learning) können durch den Verrechnungsexport erfasst und bei erfolgreicher Teilnahme exportiert werden. Die Verrechnungsdatensätze werden erstellt, wenn Sie alle Termine der Termingruppe auf den Status „Geschlossen“ setzen.
In der Übersicht (Kursmanagement → Verrechnungsexport) sehen Sie die erstellen Exporte, aufgelistet nach Titel, Besitzer, Start- und Enddatum, sowie Erstellungs- und Änderungsdatum. Durch einen Rechtsklick auf den Tabellenkopf steht Ihnen einerseits die Option Gewählte Spalten immer anzeigen zur Verfügung, andererseits können Sie die Anzeige der Spalten und Reihenfolge bearbeiten.
Inhalte
- 1 Verrechnungsexport
Verrechnungsexport
Verrechnungsexport erstellen
Mandant
Wählen Sie den Mandanten aus, aus dem die Buchungsdatensätze exportiert werden.
Startdatum
Geben Sie das Startdatum der Buchungsdatensätze an.
Enddatum
Geben Sie das Enddatum der Buchungsdatensätze an.
Auslesen
Jeder Buchungsdatensatz kann nur ausgelesen werden, wenn er nicht exportiert wurde. Durch Setzten des Häkchens markieren Sie die Datensätze als exportiert; sie werden bei einem erneuten Export nicht berücksichtigt.
Titel
Legen Sie einen Titel für die exportierten Daten fest.
Teaser
Der Teaser beschreibt die exportierten Daten.
Anbieter
Die Angabe eines Anbieters filtert diese Datensätze.
Um Ihre Dateneingabe und Datenauswahl rückgängig zu machen, klicken Sie auf den Button Reset.
Um den Export abzuschließen, klicken Sie auf den Button Auslesen. Anschließend können Sie den Verrechnungsexport bearbeiten oder das Fenster schließen.
Verrechnungsexport bearbeiten
- Um den jeweiligen Verrechnungsexport zu bearbeiten, klicken Sie auf den Titel des Verrechnungsexportes.
Das Fenster zum Bearbeiten des Verrechnungsexportes öffnet sich. - Um weitere Verrechnungsdaten hinzuzufügen, klicken Sie auf den Button Verrechnungsdaten hinzufügen.
Das Fenster Verrechnungsdaten hinzufügen öffnet sich.
Geben Sie folgende Daten ein (Pflichtfelder): OE, Nachname, Vorname, Anbieter, Veranstaltungstitel, Startdatum, Enddatum, Preis und Rabatt.
Abschließend klicken Sie auf den Button Speichern.
Das Fenster Verrechnungsdaten hinzufügen schließt sich und dieses Verrechnungsdatum ist in der Tabelle als geändert Neu eingetragen.
Sie können dieses Verrechnungsdatum bearbeiten oder löschen über den entsprechenden Button. Wenn Sie auf den Button Löschen in der Zeile des jeweiligen Verrechnungsdatums geklickt haben, wird das Verrechnungsdatum noch angezeigt, ist aber als gelöscht markiert. - Um die CSV-Datei zum Beispiel mit Excel zu öffnen oder zu speichern, klicken Sie auf den Button Exportieren.
- Um den Verrechnungsexport zu löschen, klicken Sie auf den Button Löschen. Der Button Wiederherstellen wird eingeblendet. An dieser Stelle können Sie auf den Button Wiederherstellen klicken, um das Löschen des Verrechnungsexportes rückgängig zu machen.
API für den Abruf von Verrechnungsdatensätzenn (Billing-Datensätzen)
Einsatzmöglichkeiten
Für jede erfolgreiche Teilnahme an einem Veranstaltungstermin, erreichte Zertifizierung und jeden Abschluss einer Kursfreigabe wird ein sogenannter Rechnungsdatensatz (Billing-Datensatz) erzeugt. Wenn an der Kursfreigabe oder am Veranstaltungstermin ein Preis hinterlegt ist, steht dieser Preis in diesem Datensatz. Eine Erstellung dieses Rechnungs-Datensatzes erfolgt aber auch ohne Angabe des Preises. So kann auch nach der Art des Kurses, des Termins oder nach der Dauer eines E-Learning-Kurses abgerechnet werden. Außerdem können Kundenrechnungsprozesse unterstützt werden, bei dem der eigentliche Preis im Rechnungssystem festgelegt wird (nicht im Learning-Management-System (LMS)).
Avendoo® selbst ist ein LMS, kein Rechnungs- oder Shopsystem. Mit Hilfe der Billing-Datensätze und der Billing-API können Sie die Daten für die Verrechnung im Rechnungssystem nutzen.
Voraussetzungen für Billing-Datensätze und API
Die Billing-Datensätze werden immer erzeugt. Über die folgenden Einstellungen im Autorenbereich wird entschieden, ob diese über die API abgerufen werden können:
- Option Verrechnungsdatensätze auf dem Unterreiter Verkaufspreis des Reiters Parameter im Kursfreigabe-Assistenten und
- Option Verrechnungsdatensätze auf dem Reiter Parameter im Veranstaltungstermin-Assistenten.
Billing-API konfigurieren
Verwendung
Avendoo® bietet Ihnen für das Abrufen von Billing-Datensätzen eine REST-API. Für die Konfiguration und einen Testaufruf der Schnittstelle wird das Programm Postman verwendet: https://www.postman.com/downloads/
Vorgehensweise
- GET einstellen:
Tragen Sie neben der URL die URL des Kundensystems ein (siehe erster Screenshot).
– Sie können die Zusammensetzung der Adresse in der API Doc nachschauen. In dem folgenden Link tragen Sie die Domain des Kundensystems ein: https://{avendooSystemURL}/apidoc/doc).
– Rufen Sie den API-Endpunkt auf: X/v1/billing/getBillings/usergroup/{userGroup}/datalimit/{dataLimit}Erläuterung:
X erster Teil=URL des Systems/
/{userGroup}/ =ID des Mandanten
Je nach Bedarf können Sie neben den Pflicht-Header Parametern noch weitere optionale Header-Parameter. - Header Parameter einstellen: – Wert “true > es werden Billing-Datensätze mit gesetzten Billingdates abgerufen”
Wert “false > es werden nur neue Billing-Datensätze ohne Billingdate abgerufen)
– StartTime (optional) = Millisekunden-Zeitstempel für den Beginn der optionalen Angabe eines Zeitraumfilters. Wird der Paramater verwendet, werden nur Billing-Datensätze übermittelt, deren Erstellungsdatum (billingID) > dem Wert aus startTime sind. (z. B. „1609455600000“).
– endTime (optional) = Millisekunden-Zeitstempel für das Ende der optionalen Angaben eines Zeitraumfilters. Wird der Paramater verwendet, werden nur Billing-Datensätze übermittelt, deren Erstellungsdatum (billingID)
– markAsRetrieved = Boolean, welches die Markierung an den abgerufenen Datensätzen setzt. Diese werden bei einem neuen Abruf nicht übermittelt (es sei denn, die nächste Option wird verwendet).
Boolean:Wert “true > das Billingdate wird gesetzt”
Wert “false > es wird kein Billingdate gesetzt” (nur Testabruf/nur als gelesen markiert)
– includeRetrievedBillingData = Boolean, welches nur erforderlich ist, wenn Daten, die schon als „abgeholt“ (siehe markAsRetrievd) markiert wurden, nochmals abgerufen werden sollen.– Authentifizierung mit Basic-Auth über Benutzername/Login und Passwort (PW). Beides (Login/PW*) finden Sie in der Collection.
! Passwort nie in der Collection verschicken. Entweder stellen Sie die Datei in das System online oder entfernen das PW und teilen dies telefonisch mit.– Der Request wird dann mit einer Response beantwortet, die XML-Daten enthält (finale XML-Struktur siehe Beispiel .xml). Darin ist jeweils ein „billings-Eintrag“, in dem pro „Verrechnungsdatensatz“ je ein „billing-Element“ aufgeführt wird, enthalten.
Die XSD-Beschreibung zum XML ist auch im Anhang.
Es werden maximal so viele geliefert, bis „dataLimit“ erreicht ist. Falls mehr vorhanden sind, müssen Sie eine weitere Anfrage durchführen, so lange bis die Response keine neuen Datensätze mehr liefert.
Schnittstelle verwenden
Den Abruf dieser Daten führt man i.d.R. einmal am Tag oder einmal die Woche durch.
Beispiele dafür sind:
Neue Rechnungsdatensätze abrufen und als abgerufen markieren
Ziel
Alle Billing-Datensätze abrufen, die seit dem letzten Abruf neu hinzugekommen sind und diese als „abgerufen“ (=von Schnittstell verarbeitet) markieren.
Einstellungen Header
Den Header „markAsRetrieved“ setzen Sie auf „true“.
Ergebnis
Die neuen Billing-Datensätze werden geliefert und das „billingDate“ Attribut an den Datensätzen auf den Zeitpunkt des Abrufs gesetzt.
Beim nächsten Schnittstellenaufruf werden die Datensätze mit einem „billingDate“ ignoriert. So erhält man immer nur die neuen Datensätze.
Neue Rechnungsdatensätze abrufen, aber nur „lesen“ und nicht als abgerufen markieren
Ziel
Alle neuen Billing-Datensätze abrufen, die seit dem letzten Abruf neu hinzugekommen sind, aber nur „lesen“ und diese nicht als „abgerufen“ (=von Schnittstell verarbeitet) markieren.
Das wird z. B. zum Testen oder als „Vorschau“ verwendet.
Einstellungen Header
Den Header „markAsRetrieved“ setzen Sie auf „false“.
Ergebnis
Die neuen Billing-Datensäte werden geliefert und das „billingDate“ Attribut an den Datensätzen wird nicht gesetzt.
Beim nächsten Schnittstellenaufruf werden die Datensätze (ohne „billingDate“) wieder übermittelt. So lange bis die Schnittstelle wieder mit „markAsRetrieved“ gleich „true“ aufgerufen wird.
Korrekturfall: Bereits abgerufene Datensätze nochmals abrufen
Ziel
Bei der Verarbeitung von Daten nach dem Abruf ist etwas schiefgelaufen. Bereits abgerufene Billing-Datensätze mit „billingDate“ sollen nochmals abgerufen werden.
Einstellungen Header
Den Header „markAsRetrieved“ setzen Sie auf „false“, damit nicht zusätzlich noch „neue nicht abgerufene“ Datensätze übermittelt werden.
includeRetrievedBillingData auf „true“, um Billing-Datensätze, die schon einmal abgerufen wurden (=billingDate gesetzt) nochmals abzurufen.
startime und endtime werden gesetzt:
> Starttime eine Nummer/Wert kleiner als die „billingID“ des ersten Billing-Datensatzes den man nochmal abholen möchte.
> Enddtime entsprechend einer Nummer/Wert größer als die „billingID“ des letzten Billing-Datensatzes, den man nochmal abholen möchte. Es werden dann alle Datensätze dazwischen geliefert.
Ergebnis
Die neuen Billing-Datensäte werden geliefert und das „billingDate“ Attribut an den Datensätzen wird nicht gesetzt.
Beim nächsten Schnittstellenaufruf werden die Datensätze (ohne „billingDate“) wieder übermittelt. So lange bis die Schnittstelle wieder mit „markAsRetrieved“ gleich „true“ aufgerufen wird.
API-Autor erstellen
Voraussetzungen
Zum Aufrufen der Schnittstelle benötigt man einen Avendoo®-Autorenaccount. Dieser Account ist nur für die Schnittstelle und nicht für andere Zwecke (Inhaltserstellung) vorgesehen.
Diesem Autorenaccount sollte eine Berechtigungsgruppe zugewiesen sein, die es ihm ermöglicht, die Schnittstelle zu benutzen und Zugriff auf den/die entsprechenden Mandanten zu haben. Folgendes Zugriffsrecht ist erforderlich: Benutzer anzeigen.
Verwendung
Dieser API-Autor wird im System, welches den Aufruf der Schnittstelle der Billing-API durchführt, benötigt. Die Authentifizierung erfolgt über Basic Auth. Zum Testen dieser Schnittsteller empfiehlt es sich den Schnittstellenaufruf (URL > Headerparameter > Authorization) in Postman zu konfigurieren.
Antwort der Anfrage
Die Antwort der Anfrage enthält im Body Billing-Datensätze und wird im Folgenden erläutert.
Der Aufbau eines Datensatzes sieht folgendermaßen aus:
So sieht ein Bespieldatensatz aus:
Bedeutung und Format der einzelnen Attribute aus dem Beispieldatensatz
- assignmentId = ID der Kursfreigaben, die im Zusammenhang mit diesem Verrechnungseintrag steht. Kann leer sein. Format: String mit max. 33 Zeichen
- billingDate = Zeitstempel in Millisekunden, wann ein bereits „abgerufener Verrechnungsdatensatz“ abgerufen wurde. Im Normalfall, ohne Option, dass bereits abgerufene Daten übermittelt werden sollen, ist dieser Wert 0. Format: Millisekunden seit 1970, den 1. Januar 1970, 00:00 Uhr (siehe auch https://currentmillis.com/)
- billingId = ID des Verrechnungsdatensatzes und gleichzeitig Erstellungszeitpunkt des Billing-Datensatzes. Format: BigInt, kann auch negativ sein (z. B. -9216092154614085860)
- classification = Klassifikationsangabe. Format: String mit max. 16777215 Zeichen (ca. 16 MB). Typischerweise kleiner 1000 Zeichen.
- company = Firmenname. Format: String, keine Zahl (!) wegen führender Nullen, mit max. 255 Zeichen
- costCenter = Kostenstelle. Format: String, keine Zahl (!) wegen führender Nullen, mit max. 255 Zeichen
- currency = Währung. Format: String mit 3 Zeichen.
- duration = Dauer der erwarteten Lernzeit in Millisekunden. Durch 1000 * 60 teilen, um die Minuten zu erhalten und von da weiter nach Stunden (mit Doppelpunkt oder Komma) formatieren. BigInt, kann auch 0 sein.
- endDate = Zeitstempel (Datum + Uhrzeit, Zeitzone Wien) in Millisekunden, wann die Kursbearbeitung begann oder der Veranstaltungstermin beendet wurde.
- firstname = Vorname des Teilnehmers. Format: String mit max. 255 Zeichen.
- language = Sprache des Mitarbeiters. Format: String, 2 Zeichen
- lastname = Nachname des Teilnehmers. Format: String mit max. 255 Zeichen.
- location = Ortsangabe. Format: String mit max. 255 Zeichen.
- objectId= ID der Kursfreigaben, die im Zusammenhang mit diesem Verrechnungseintrag steht. Kann leer sein. Format: String mit max. 33 Zeichen
- objectType = Typ, 40 = Kursfreigabe, 22 = Veranstaltungstermin
- objectTypeName = Typ-Name, „COURSE“ oder „EVENT“
- oe = Organisationseinheit/Abteilungskürzel des Teilnehmers. Format: String mit max. 255 Zeichen.
- personnelNumber= Personalnummer. Format: String, keine Zahl (!) wegen führender Nullen, mit max. 255 Zeichen.
- price = Gesamtpreis, der zu verrechnen ist. Entweder ein manuell gesetzter Wert oder die Summe aus den Kosten. Format: Double Fließkommazahl.
- provider = Anbieter. Format: String mit max. 255 Zeichen.
- seminarCostAccomodation = Anteil des Preises, der durch Übernachtungskosten bei einem Verrechnungsdatensatz für einen Veranstaltungstermin entstanden ist. Format: Double Fließkommazahl.
- seminarCostTraining = Anteil des Preises, der durch Veranstaltungs- oder Trainerkosten bei einem Verrechnungsdatensatz für einen Veranstaltungstermin entstanden ist. Format: Double Fließkommazahl.
- startDate = Zeitstempel (Datum + Uhrzeit, Zeitzone Wien) in Millisekunden, wann die Kursbearbeitung begann oder der Veranstaltungstermin begonnen hat.
- subObjectId= ID der Veranstaltungstermins, die im Zusammenhang mit diesem Verrechnungseintrag steht. Nur für Verrechnung Veranstaltungstermine. Kann bei einem Kurs 0,0 sein. Format: String mit max. 33 Zeichen.
- teaser= Titel oder Bezeichnung des Kurses oder der Veranstaltung. Format: String mit max. 16777215 Zeichen (ca. 16 MB). Typischerweise kleiner 1000 Zeichen.
- title = Titel oder Bezeichnung des Kurses oder der Veranstaltung. Format: String mit max. 255 Zeichen.
- userLogin = Benutzername oder Login des Teilnehmers. Format: String mit max. 255 Zeichen.
Bei weiteren Fragen steht Ihnen unser Support-Team zur Verfügung.
