Creazione di ordini

3.1.3. Creazione di ordini#

Questa pagina contiene tutta la documentazione per il video tutorial che spiega la semplice creazione di un ordine tramite l’API e la verifica del suo stato.

3.1.3.1. Video#

3.1.3.2. Requisiti#

Necessario per questa serie di esercitazioni:

  • Un backend commerciale Taler
    Se avete bisogno di aiuto per usare il backend del commerciante per la prima volta, potete guardare il tutorial Taler merchant introduction.
  • Un’istanza di portafoglio Taler
    Le istruzioni per l’installazione sono disponibili su https://wallet.taler.net.
  • 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.

3.1.3.3. Avviso di backend demo#

Per questa esercitazione si può utilizzare il proprio servizio di backend commerciale o il servizio dimostrativo online di https://backend.demo.taler.net/instances/sandbox/.

3.1.3.4. Elaborazione dei pagamenti dei commercianti#

  1. Creare un ordine per un pagamento

I pagamenti in Taler ruotano attorno a un ordine, che è una descrizione leggibile a macchina della transazione commerciale per la quale deve essere effettuato il pagamento. Prima di accettare un pagamento Taler come commerciante, è necessario creare un ordine di questo tipo.

Ciò avviene inviando un oggetto JSON all’endpoint API /private/orders del backend. All’interno del campo ordine devono essere indicati almeno i seguenti campi:

  • importo: L’importo da pagare, come stringa nel formato CURRENCY:DECIMAL_VALUE, ad esempio EUR:10 per 10 euro o KUDOS:1.5 per 1.5 KUDOS.

  • sommario: Un riassunto leggibile per il contenuto del pagamento. Il riassunto deve essere abbastanza breve da poter essere inserito nei titoli, anche se non viene imposto un limite rigido.

  • fulfillment_url: Un URL che verrà visualizzato una volta completato il pagamento. Per i beni digitali, dovrebbe essere una pagina che mostra il prodotto acquistato. Quando il pagamento va a buon fine, il portafoglio aggiunge automaticamente il ordine_id come parametro della query, così come il session_sig per i pagamenti legati alla sessione (discusso di seguito).

Gli ordini possono avere molti altri campi, vedere Il formato dell’ordine di Taler. Quando si invia un ordine, è possibile specificare ulteriori dettagli, come ad esempio un override per la durata del rimborso e le istruzioni per la gestione dell’inventario. Questi dettagli sono raramente necessari e non sono trattati in questa esercitazione; per i dettagli si rimanda al manuale di riferimento.

Uno snippet Python minimale per la creazione di un ordine sarebbe simile a questo:

>>> import requests
>>> body = dict(order=dict(amount="KUDOS:10",
...                        summary="Donation",
...                        fulfillment_url="https://example.com/thanks.html"),
...             create_token=False)
>>> response = requests.post("https://backend.demo.taler.net/instances/sandbox/private/orders",
...               json=body,
...               headers={"Authorization": "Bearer secret-token:sandbox"})
<Response [200]>

Il backend inserirà alcuni dettagli mancanti nell’ordine, come l’indirizzo dell’istanza del commerciante. I dettagli completi sono chiamati condizioni contrattuali.

Nota

La richiesta precedente disabilita l’uso dei claim token impostando l’opzione create_token a false. Se si ha bisogno di token di richiesta, è necessario modificare il codice per costruire l’URI taler://pay/ dato di seguito per includere il token di richiesta.

Dopo aver effettuato con successo una POST a /private/orders, verrà restituito un JSON contenente solo un campo order_id con una stringa che rappresenta l’ID dell’ordine. Se si ottiene anche un token di richiesta, verificare che la richiesta sia stata utilizzata come descritto sopra.

Insieme all”instance del commerciante, l’id dell’ordine identifica in modo univoco l’ordine all’interno del backend del commerciante. Utilizzando l’ID dell’ordine, è possibile costruire banalmente il rispettivo URI taler://pay/ che deve essere fornito al portafoglio. Sia example.com il nome del dominio in cui sono raggiungibili gli endpoint pubblici dell’istanza. L’URI di Taler pay è quindi semplicemente taler://pay/example.com/$ORDER_ID/ dove $ORDER_ID deve essere sostituito con l’ID dell’ordine restituito.

È possibile inserire l’URI taler:// come destinazione di un link per aprire il portafoglio Taler tramite lo schema taler://, oppure inserirlo in un codice QR. Tuttavia, per un negozio Web, il modo più semplice è semplicemente reindirizzare il browser a https://example.com/orders/$ORDER_ID. Questa pagina attiverà il portafoglio Taler. Il backend genera la logica giusta per attivare il portafoglio, supportando i vari tipi di portafoglio Taler esistenti. Invece di costruire a mano l’URL di cui sopra, è possibile ottenerlo anche controllando lo stato del pagamento, come descritto nella prossima sezione.

Quando si costruisce manualmente questo URL, assicurarsi di fornire il token di richiesta (a meno che non sia stato disabilitato) e se il backend è in esecuzione senza TLS utilizzare taler+http:// (si noti che quest’ultimo è supportato solo dai portafogli in esecuzione in modalità debug).

Nota

Un modo banale per ottenere il payment_redirect_url corretto è controllare lo stato del pagamento (vedere sotto). Quindi, se non si è ancora sicuri di come costruirlo, si può semplicemente chiedere al backend di farlo per noi. Tuttavia, in produzione si dovrebbe probabilmente costruirlo manualmente, evitando una richiesta extra al backend.

  1. Verifica dello stato dei pagamenti e richiesta di pagamento

Dato l’ID dell’ordine, lo stato di un pagamento può essere controllato con l’endpoint /private/orders/$ORDER_ID. Se il pagamento deve ancora essere completato dal cliente, /private/orders/$ORDER_ID fornirà al frontend un URL (con il nome payment_redirect_url) che attiverà il portafoglio del cliente per eseguire il pagamento. Questo è fondamentalmente l’URL https://example.com/orders/$ORDER_ID di cui abbiamo parlato sopra.

>>> import requests
>>> r = requests.get("https://backend.demo.taler.net/instances/sandbox/private/orders/" + order_id,
...                  headers={"Authorization": "Bearer secret-token:sandbox"})
>>> print(r.json())

Se il campo stato_ordine nella risposta è pagato, non si otterrà un payment_redirect_url` e invece informazioni sullo stato del pagamento, tra cui:

  • termini_contrattuali: Le condizioni contrattuali complete dell’ordine.

  • refunded: true se è stato concesso un rimborso (eventualmente parziale) per questo acquisto.

  • importo_rimborsato: Importo rimborsato

Una volta che il frontend ha confermato che il pagamento è andato a buon fine, di solito deve attivare la logica di business per l’esercente per adempiere agli obblighi del contratto.

Nota

Non è necessario continuare a interrogare per notare le modifiche allo stato della transazione dell’ordine. Gli endpoint supportano il polling lungo, basta specificare un parametro di query timeout_ms con il tempo massimo che si desidera attendere affinché lo stato dell’ordine cambi in pagato.

3.1.3.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.