Conceptueel overzicht

3.1.1. Conceptueel overzicht#

3.1.1.1. Over deze handleiding#

Deze tutorial behandelt hoe je betalingen verwerkt met de GNU Taler-verkopersbackend. Het publiek voor deze tutorial zijn ontwikkelaars van verkopers (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-verkoper 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 softwarestack voor een verkoper 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 exchange 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 verkoper 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 verkoper (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 Bedieningshandleiding voor de verkoper-backend.

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. Verkopersinstanties#

Eén enkele Taler-verkopersbackendserver kan worden gebruikt door meerdere verkopers die afzonderlijke bedrijfsentiteiten zijn. Aan elk van deze afzonderlijke bedrijfsentiteiten wordt een verkopersinstantie toegewezen die wordt geïdentificeerd door een alfanumerieke instantie-id. Als de instantie wordt weggelaten, wordt de instantie-id admin aangenomen.

De volgende verkopersinstanties 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 de verkopersbackend.

3.1.1.5. Video-handleidingen#

Deze pagina bevat alle documentatie voor de videotutorial die de Taler-verkopers-API introduceert.

3.1.1.5.1. Video#

3.1.1.5.2. Vereisten#

Vereist voor deze tutorialserie:

  • Een Taler-verkopersbackend
    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-verkoperdemoservice https://backend.demo.taler.net/instances/sandbox/ wordt sterk aangeraden voor deze tutorial.

De toegangssleutel is: sandbox.

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.