Übersicht über die Instanzen

3.1.1. Übersicht über die Instanzen#

3.1.1.1. Über dieses Lernprogramm#

Dieses Tutorial behandelt die Verarbeitung von Zahlungen mit dem GNU Taler Händler-Backend. Die Zielgruppe für dieses Tutorial sind Entwickler von Händlern (wie z.B. Webshops), die daran arbeiten, GNU Taler mit dem kundenorientierten Frontend und dem mitarbeiterorientierten Backoffice zu integrieren.

In diesem Kapitel werden einige grundlegende Konzepte erläutert. Im zweiten Kapitel werden Sie lernen, wie man grundlegende Zahlungen durchführt.

Diese Version des Tutorials enthält Beispiele für Python3. Sie verwendet die requests-Bibliothek für HTTP-Anfragen. Versionen für andere Sprachen/Umgebungen sind ebenfalls verfügbar.

Wenn Sie sich einige einfache, laufende Beispiele ansehen möchten, schauen Sie sich diese an:

3.1.1.2. Überblick über die Architektur#

Der Taler-Software-Stack für einen Händler besteht aus den folgenden Hauptkomponenten:

  • Ein Frontend, das mit dem Browser des Kunden interagiert. Das Frontend ermöglicht es dem Kunden, einen Einkaufswagen zu erstellen und eine Bestellung aufzugeben. Nach der Bezahlung wird die entsprechende Geschäftslogik ausgelöst, um die Bestellung zu erfüllen. Diese Komponente ist nicht im Lieferumfang von Taler enthalten, sondern wird beim Händler vorausgesetzt. Dieses Tutorial beschreibt, wie man ein Taler-Frontend entwickelt.

  • Ein Taler-spezifisches Zahlungs-Backend, das es dem Frontend leicht macht, finanzielle Transaktionen mit Taler zu verarbeiten. Für dieses Tutorial werden Sie ein öffentliches Sandbox-Backend verwenden. Für den produktiven Einsatz müssen Sie entweder Ihr eigenes Backend einrichten oder eine andere Person bitten, dies für Sie zu tun.

Die folgende Abbildung veranschaulicht die verschiedenen Wechselwirkungen zwischen diesen Schlüsselkomponenten:

../../_images/arch-api.png

Das Backend unterstützt das kryptografische Protokoll, speichert Taler-spezifische Finanzinformationen und kommuniziert mit der GNU Taler-Börse über das Internet. Das Frontend greift auf das Backend über eine RESTful API zu. Dadurch muss das Frontend nie direkt mit der Börse kommunizieren und hat auch keinen Umgang mit sensiblen Daten. Insbesondere die Signierschlüssel und Bankkontoinformationen des Händlers sind im Taler-Backend gekapselt.

Einige Funktionen des Backend (die „öffentliche Schnittstelle“) sind dem Browser des Kunden direkt zugänglich. In der HTTP-API sind alle privaten Endpunkte (für das Backoffice) mit dem Präfix /private/ versehen. Dieses Tutorial konzentriert sich auf die /private/ Endpunkte. Die öffentliche Schnittstelle wird direkt von der Geldbörse verwendet und ist für den Händler nicht relevant (außer, dass die API offengelegt werden muss).

3.1.1.3. Öffentliches Sandbox-Backend und Authentifizierung#

Wie sich das Frontend gegenüber dem Taler-Backend authentifiziert, hängt von der Konfiguration ab. Siehe Merchant Backend Operator Manual.

Das öffentliche Sandbox-Backend https://backend.demo.taler.net/instances/sandbox/ verwendet einen API-Schlüssel im Authorization-Header. Der Wert dieses Headers muss Bearer secret-token:sandbox für das öffentliche Sandbox-Backend sein.

>>> import requests
>>> requests.get("https://backend.demo.taler.net/instances/sandbox/private/orders",
...              headers={"Authorization": "Bearer secret-token:sandbox"})
<Response [200]>

Wenn ein anderer HTTP-Statuscode als 200 zurückgegeben wird, ist etwas schief gelaufen. Sie sollten herausfinden, was das Problem ist, bevor Sie mit diesem Lernprogramm fortfahren.

Das Sandbox-Backend https://backend.demo.taler.net/instances/sandbox/ verwendet KUDOS als imaginäre Währung. Münzen, die auf KUDOS lauten, können von https://bank.demo.taler.net/ abgehoben werden.

3.1.1.4. Merchant Instances#

Ein einzelner Taler-Händler-Backend-Server kann von mehreren Händlern genutzt werden, die separate Geschäftseinheiten sind. Jeder dieser separaten Geschäftseinheiten wird eine Händlerinstanz zugewiesen, die durch eine alphanumerische Instanz-ID identifiziert wird. Wenn die Instanz weggelassen wird, wird die Instanz-ID admin angenommen.

Die folgenden Händlerinstanzen sind auf https://backend.demo.taler.net/ konfiguriert:

Bemerkung

Es handelt sich dabei um fiktive Händler, die für unsere Demonstratoren verwendet werden und nicht mit den jeweiligen Projekten verbunden oder von diesen offiziell anerkannt sind.

Alle Endpunkte für Instanzen bieten die gleiche API. Daher wird die zu verwendende Instanz einfach in die Basis-URL des Händler-Backends aufgenommen.

3.1.1.5. Video-Tutorials#

Diese Seite enthält die gesamte Dokumentation für das Video-Tutorial zur Einführung in die Taler-Händler-API.

3.1.1.5.1. Video#

3.1.1.5.2. Anforderungen#

Erforderlich für diese Lehrgangsreihe:

  • Ein Taler-Händler-Backend
    Der Einfachheit halber empfehlen wir Ihnen, https://backend.demo.taler.net/instances/sandbox/ zu verwenden.
  • Eine Taler-Walletn-Instanz
    Anleitungen zur Einrichtung finden Sie unter https://wallet.taler.net, sie sind jedoch für dieses Lernprogramm nicht erforderlich.
  • Eine REST-API-Verwaltungssoftware oder entsprechende Programmierkenntnisse
    In dieser Videoreihe werden wir die kostenlose Software Insomnia verwenden, die unter https://insomnia.rest heruntergeladen werden kann.
    Als Einführung wird in diesem Video gezeigt, wie man funktionierenden Code aus den vorbereiteten Abfragen in Insomnia in Python (oder einer anderen unterstützten Sprache) exportiert und ausführt, aber dies wird in den nächsten Tutorials nicht mehr gezeigt.

3.1.1.5.3. Demo-Backend Hinweis#

Es wird dringend empfohlen, für dieses Tutorial den Online-Demoservice für Taler-Händler https://backend.demo.taler.net/instances/sandbox/ zu verwenden.

Der Zugangsschlüssel lautet: sandbox.

3.1.1.5.4. Informationen über den geheimen Token#

Das geheime Token entspricht dem Dokument RFC 8959. Mehr darüber erfahren Sie hier: https://datatracker.ietf.org/doc/html/rfc8959. Denken Sie daran, dass es sich um ein Bearer-Token handelt, das in Ihrem Header für die Autorisierung angegeben werden muss.

Ihr Berechtigungskopf sollte wie folgt aussehen:
Autorisierung: Bearer secret-token:<Zugangsschlüssel>

3.1.1.5.5. Mehr Tutorials#

Weitere Anleitungen finden Sie auf dieser Website oder unter https://docs.taler.net, wo Sie die neueste Dokumentation über die Taler-Dienste finden.