Instance-overzicht

3.1.1. Instance-overzicht#

3.1.1.1. Over deze handleiding#

Deze tutorial behandelt hoe je betalingen verwerkt met de GNU Taler Backend. Het publiek voor deze tutorial zijn ontwikkelaars van winkeliers (zoals webwinkels) die bezig zijn GNU Taler te integreren met de klantgerichte Frontend en de personeelsgerichte Backoffice.

In dit hoofdstuk worden enkele basisbegrippen uitgelegd. In het tweede hoofdstuk leer je hoe je basisbetalingen doet.

Deze versie van de tutorial heeft voorbeelden voor Python3. Het gebruikt de requests bibliotheek voor HTTP verzoeken. Versies voor andere talen/omgevingen zijn ook beschikbaar.

Als je enkele eenvoudige, lopende voorbeelden wilt bekijken, bekijk dan deze:

  • De essay merchant die losse hoofdstukken van een boek verkoopt.

  • De donatiepagina die donaties voor softwareprojecten accepteert en donatiebewijzen geeft.

  • De WooCommerce plugin die een uitgebreide integratie is in een webwinkel, inclusief het terugbetalingsproces.

3.1.1.2. Overzicht architectuur#

De Taler software stack voor een merchant bestaat uit de volgende hoofdcomponenten:

  • Een frontend die interageert met de browser van de klant. Met de frontend kan de klant een winkelwagentje samenstellen en een bestelling plaatsen. Na betaling wordt de betreffende bedrijfslogica geactiveerd om de bestelling uit te voeren. Deze component wordt niet meegeleverd met Taler, maar wordt verondersteld te bestaan bij de verkoper. Deze tutorial beschrijft hoe je een Taler frontend ontwikkelt.

  • Een Taler-specifiek betalingsbackend dat het makkelijk maakt voor de frontend om financiële transacties te verwerken met Taler. Voor deze tutorial gebruik je een publieke sandbox backend. Voor productiegebruik moet je je eigen backend opzetten of iemand anders vragen dit voor je te doen.

De volgende afbeelding illustreert de verschillende interacties van deze sleutelcomponenten:

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

Het backend biedt ondersteuning voor cryptografische protocollen, slaat Taler-specifieke financiële informatie op en communiceert met de GNU Taler uitwisseling over het internet. Het frontend heeft toegang tot het backend via een RESTful API. Hierdoor hoeft de frontend nooit direct te communiceren met de exchange en heeft ook geen te maken met gevoelige gegevens. In het bijzonder worden de handtekeningsleutels en bankgegevens van de merchant ingekapseld in de Taler backend.

Sommige functionaliteit van de backend (de “publieke interface”) is direct zichtbaar voor de browser van de klant. In de HTTP API worden alle privé eindpunten (voor de Backoffice) voorafgegaan door /private/. Deze tutorial richt zich op de /private/ eindpunten. De publieke interface wordt direct gebruikt door de portemonnee en is niet relevant voor de merchant (behalve dat de API moet worden blootgesteld).

3.1.1.3. Publieke Sandbox Backend en Authenticatie#

Hoe het frontend zich authentiseert bij het Taler backend hangt af van de configuratie. Zie Merchant Backend Bedieningshandleiding.

De publieke sandbox backend https://backend.demo.taler.net/instances/sandbox/ gebruikt een API sleutel in de Authorization header. De waarde van deze header moet Bearer secret-token:sandbox zijn voor de publieke sandbox backend.

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

Als er een andere HTTP-statuscode dan 200 wordt geretourneerd, is er iets misgegaan. Je moet uitzoeken wat het probleem is voordat je verder gaat met deze tutorial.

De sandbox backend https://backend.demo.taler.net/instances/sandbox/ gebruikt KUDOS als denkbeeldige valuta. Munten in KUDOS kunnen worden opgenomen van https://bank.demo.taler.net/.

3.1.1.4. Handelaarsinstanties#

Een enkele Taler merchant backend server kan worden gebruikt door meerdere merchants die afzonderlijke bedrijfsentiteiten zijn. Aan elk van deze afzonderlijke bedrijfsentiteiten wordt een merchant instance toegewezen die wordt geïdentificeerd door een alfanumerieke instance id. Als de instantie wordt weggelaten, wordt de instantie id admin aangenomen.

De volgende merchant instanties zijn geconfigureerd op https://backend.demo.taler.net/:

Notitie

Dit zijn fictieve verkopers die gebruikt worden voor onze demonstrators en die niet verbonden zijn aan of officieel goedgekeurd zijn door de respectieve projecten.

Alle eindpunten voor instanties bieden dezelfde API. Welke instantie moet worden gebruikt, wordt dus eenvoudigweg opgenomen in de basis URL van het merchant backend.

3.1.1.5. Video-handleidingen#

Deze pagina bevat alle documentatie voor de video tutorial die de Taler merchant API introduceert.

3.1.1.5.1. Video#

3.1.1.5.2. Vereisten#

Vereist voor deze tutorialserie:

  • Een Taler merchant backend
    Voor het gemak raden we je aan https://backend.demo.taler.net/instances/sandbox/ te gebruiken.
  • Een Taler portemonnee instantie
    Installatie-instructies zijn beschikbaar op https://wallet.taler.net, maar niet vereist voor deze tutorial.
  • Software voor REST API-beheer of relevante programmeervaardigheden
    In deze videoserie gebruiken we de gratis software Insomnia, te downloaden op https://insomnia.rest.
    Als introductie laat deze video zien hoe je werkende code van je voorbereide query’s in Insomnia in Python (of een andere ondersteunde taal) kunt exporteren en uitvoeren, maar dit wordt niet meer gedemonstreerd in de volgende tutorials.

3.1.1.5.3. Demonstratie backend kennisgeving#

Het gebruik van de online Taler merchant demo service https://backend.demo.taler.net/instances/sandbox/ wordt sterk aangeraden voor deze tutorial.

De toegangssleutel is: zandbak.

3.1.1.5.4. Informatie over het geheime token#

Het geheime token voldoet aan het RFC 8959 document. Je kunt er hier meer over leren: https://datatracker.ietf.org/doc/html/rfc8959. Onthoud dat dit een Bearer token is en dat je authoirization header dit moet specificeren.

Je autorisatieheader zou er als volgt uit moeten zien:
Authorisatie: Bearer secret-token:<toegangssleutel>

3.1.1.5.5. Meer tutorials#

Om aanvullende tutorials te bekijken, kun je op deze site kijken of naar https://docs.taler.net gaan voor de nieuwste documentatie over de Taler services.