Panoramica dell’istanza

3.1.1. Panoramica dell’istanza#

3.1.1.1. Informazioni su questo tutorial#

Questo tutorial spiega come elaborare i pagamenti utilizzando il backend commerciale di GNU Taler. Il pubblico di questo tutorial è costituito da sviluppatori di commercianti (come i negozi Web) che stanno lavorando all’integrazione di GNU Taler con il Frontend rivolto ai clienti e il Backoffice rivolto al personale.

Questo capitolo spiega alcuni concetti di base. Nel secondo capitolo si apprenderà come effettuare i pagamenti di base.

Questa versione del tutorial contiene esempi per Python3. Utilizza la libreria requests per le richieste HTTP. Sono disponibili anche versioni per altri linguaggi/ambienti.

Se volete vedere alcuni esempi semplici e funzionanti, date un’occhiata a questi:

  • Il commerciante di saggi che vende singoli capitoli di un libro.

  • La pagina delle donazioni che accetta le donazioni per i progetti software e fornisce le ricevute delle donazioni.

  • Il plugin WooCommerce che rappresenta un’integrazione completa in un negozio Web, compreso il processo di rimborso.

3.1.1.2. Panoramica dell’architettura#

Lo stack software Taler per un commerciante è costituito dai seguenti componenti principali:

  • Un frontend che interagisce con il browser del cliente. Il frontend consente al cliente di creare un carrello della spesa e di effettuare un ordine. Al momento del pagamento, attiva la rispettiva logica aziendale per soddisfare l’ordine. Questo componente non è incluso in Taler, ma si presume che esista presso il commerciante. Questa esercitazione descrive come sviluppare un frontend Taler.

  • Un backend per i pagamenti specifico di Taler che facilita il frontend nell’elaborazione delle transazioni finanziarie con Taler. Per questa esercitazione, si utilizzerà un backend sandbox pubblico. Per l’uso in produzione, è necessario configurare il proprio backend o chiedere a un’altra persona di farlo per voi.

L’immagine seguente illustra le varie interazioni di questi componenti chiave:

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

Il backend fornisce il supporto del protocollo crittografico, memorizza le informazioni finanziarie specifiche di Taler e comunica con lo scambio GNU Taler su Internet. Il frontend accede al backend tramite un’API RESTful. Di conseguenza, il frontend non deve mai comunicare direttamente con l’exchange e non tratta dati sensibili. In particolare, le chiavi di firma e le informazioni sul conto bancario dell’esercente sono incapsulate nel backend di Taler.

Alcune funzionalità del backend (l“«interfaccia pubblica») sono esposte direttamente al browser del cliente. Nell’API HTTP, tutti gli endpoint privati (per il Backoffice) hanno il prefisso /private/. Questa esercitazione si concentra sugli endpoint /private/. L’interfaccia pubblica è utilizzata direttamente dal portafoglio e non è rilevante per il commerciante (a parte il fatto che l’API deve essere esposta).

3.1.1.3. Backend Sandbox pubblico e autenticazione#

Il modo in cui il frontend si autentica al backend Taler dipende dalla configurazione. Vedere il Merchant Backend Operator Manual.

Il backend sandbox pubblico https://backend.demo.taler.net/instances/sandbox/ utilizza una chiave API nell’intestazione Authorization. Il valore di questa intestazione deve essere Bearer secret-token:sandbox per il backend sandbox pubblico.

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

Se viene restituito un codice di stato HTTP diverso da 200, qualcosa è andato storto. È necessario capire qual è il problema prima di continuare con questa esercitazione.

Il backend sandbox https://backend.demo.taler.net/instances/sandbox/ utilizza KUDOS come moneta immaginaria. Le monete denominate in KUDOS possono essere prelevate da https://bank.demo.taler.net/.

3.1.1.4. Istanze del commerciante#

Un singolo server backend di Taler può essere utilizzato da più commercianti che sono entità commerciali separate. A ciascuna di queste entità commerciali separate viene assegnata un’istanza merchant, identificata da un identificatore di istanza alfanumerico. Se l’istanza viene omessa, viene assunto l’id di istanza admin.

Le seguenti istanze commerciali sono configurate su https://backend.demo.taler.net/:

Nota

Si tratta di commercianti fittizi utilizzati per i nostri dimostratori e non affiliati o approvati ufficialmente dai rispettivi progetti.

Tutti gli endpoint delle istanze offrono la stessa API. Pertanto, l’istanza da utilizzare è semplicemente inclusa nell’URL di base del backend del commerciante.

3.1.1.5. Video tutorial#

Questa pagina contiene tutta la documentazione del video tutorial di introduzione all’API Taler merchant.

3.1.1.5.1. Video#

3.1.1.5.2. Requisiti#

Necessario per questa serie di esercitazioni:

  • Un backend commerciale Taler
    Per comodità, si consiglia di utilizzare https://backend.demo.taler.net/instances/sandbox/.
  • Un’istanza di portafoglio Taler
    Le istruzioni per la configurazione sono disponibili su https://wallet.taler.net, ma non sono necessarie per questa esercitazione.
  • Un software di gestione API REST o competenze di programmazione pertinenti
    In questa serie di video utilizzeremo il software gratuito Insomnia, disponibile per il download all’indirizzo https://insomnia.rest.
    Come introduzione, questo video mostrerà come esportare il codice di lavoro dalle query preparate in Insomnia in Python (o in qualsiasi altro linguaggio supportato) ed eseguirle, ma questo non verrà mostrato di nuovo nei prossimi tutorial.

3.1.1.5.3. Avviso di backend demo#

Per questa esercitazione si consiglia vivamente di utilizzare il servizio demo online di Taler merchant https://backend.demo.taler.net/instances/sandbox/.

La chiave di accesso è: sandbox.

3.1.1.5.4. Informazioni sul token segreto#

Il token segreto è conforme al documento RFC 8959. Per saperne di più, consultare il sito: https://datatracker.ietf.org/doc/html/rfc8959. Tenere presente che si tratta di un token Bearer e che l’intestazione di autorizzazione deve specificarlo.

L’intestazione dell’autorizzazione dovrebbe assomigliare a questa:
Autorizzazione: Bearer secret-token:<chiave di accesso>

3.1.1.5.5. More tutorials#

Per visualizzare altre esercitazioni, potete consultare questo sito o visitare https://docs.taler.net per ottenere la documentazione più recente sui servizi Taler.