3.1.6. Il formato dell’ordine di Taler#

Il formato dell’ordine Taler descrive il JSON che deve essere inviato al backend del commerciante per creare un ordine. È il prototipo da cui il backend dell’esercente creerà i termini del contratto <https://docs.taler.net/core/api-merchant.html#the-contract-terms>`__.

Esistono diverse versioni per il formato dell’ordine; sono descritte in dettaglio nel Manuale di riferimento.

Nota

Gli importi finanziari sono sempre specificati come stringa nel formato CURRENCY:DECIMAL_VALUE.

Questa sezione fornisce una panoramica dei campi più comuni:

importo: Specifica l’importo totale che il cliente deve pagare all’esercente.

max_fee: Questo è l’importo totale massimo delle commissioni di deposito che il commerciante è disposto a pagare. Se le spese di deposito per le monete superano questo importo, il cliente deve includerlo nel totale del pagamento. La commissione viene specificata utilizzando lo stesso formato usato per importo.

tariffa max_wire: Commissione massima per il bonifico accettata dall’esercente (la quota del cliente deve essere divisa per il fattore wire_fee_amortization e ulteriormente ridotta se le commissioni di deposito sono inferiori a max_fee). Se manca, il valore predefinito è zero.

ammortamento_filo: Su quante transazioni del cliente l’esercente prevede di ammortizzare in media le commissioni bancarie? Se la commissione di bonifico dello scambio è superiore alla max_wire_fee, la differenza viene divisa per questo numero per calcolare il contributo previsto del cliente alla commissione di bonifico. Il contributo del cliente può essere ulteriormente ridotto dalla differenza tra la max_fee e la somma delle commissioni di deposito effettive. Opzionale, il valore predefinito se mancante è 1. I valori zero e negativi non sono validi e vengono interpretati come 1.

indirizzo_pagamento: Quale URL accetta i pagamenti. Questo è l’URL in cui il portafoglio POSTUMA le monete.

url_adempimento: A quale URL deve andare il portafoglio per ottenere l’adempimento, ad esempio l’HTML o il PDF di un articolo acquistato, o un sistema di tracciamento degli ordini per le spedizioni, o una semplice pagina Web leggibile dall’uomo che indichi lo stato del contratto.

ordine_id: Identificatore alfanumerico, liberamente definibile dall’esercente. Utilizzato dall’esercente per identificare in modo univoco la transazione.

sintesi: Breve riepilogo del contratto, leggibile dall’uomo. Da utilizzare quando si visualizza il contratto in una sola riga, ad esempio nella cronologia delle transazioni del cliente.
timestamp: Ora in cui è stata generata l’offerta.

scadenza_pagamento: Timestamp dell’ora entro la quale il commerciante desidera che l’exchange trasferisca definitivamente il denaro dovuto da questo contratto. Una volta scaduto questo termine, l’exchange aggregherà tutti i depositi in cui i contratti hanno superato la scadenza_di_rimborso ed eseguirà un unico grande pagamento via bonifico. Gli importi saranno arrotondati per difetto all’unità di bonifico; se l’importo totale è ancora inferiore all’unità di bonifico, non sarà erogato.

termine_di_rimborso: Data limite fino alla quale il commerciante è disposto (e in grado) di fornire rimborsi per il contratto utilizzando Taler. Si noti che lo scambio Taler terrà il pagamento in deposito almeno fino a questa scadenza. Fino a questo momento, il commerciante potrà firmare un messaggio per attivare un rimborso al cliente. Dopo questo termine, non sarà più possibile rimborsare il cliente. Deve essere inferiore al pay_deadline.

prodotti

Array di prodotti venduti al cliente. Ogni voce contiene una tupla con i seguenti valori:

descrizione: Descrizione del prodotto.
quantità: Quantità degli articoli da spedire. Può specificare un’unità (ad esempio, 1 kg) o solo il numero.
prezzo: Prezzo per quantità di unità di questo prodotto spedite alla data località_di_consegna. Si noti che di solito la somma di tutti i prezzi dovrebbe sommare l’importo totale del contratto, ma potrebbe essere diversa a causa di sconti o perché i singoli prezzi non sono disponibili.
prodotto_id: ID univoco del prodotto nel catalogo del commerciante. Può essere scelto liberamente, poiché ha un significato solo per il commerciante, ma dovrebbe essere un numero nell’intervallo $[0,2^{51})$ .
tasse: Mappa delle imposte applicabili che il commerciante deve pagare. L’etichetta è il nome dell’imposta, ad esempio IVA, imposta sulle vendite o imposta sul reddito, mentre il valore è l’importo dell’imposta applicabile. Si noti che sono consentite etichette arbitrarie, purché siano utilizzate per identificare il regime fiscale applicabile. I dettagli possono essere specificati dal regolatore. L’informazione viene utilizzata per dichiarare al cliente quali tasse l’esercente intende pagare e può essere utilizzata dal cliente come ricevuta. È probabile che le informazioni vengano utilizzate anche in caso di controlli fiscali sull’esercente.
data_di_consegna: Tempo entro il quale il prodotto deve essere consegnato alla località_di_consegna.
posizione_di_consegna: Questo dovrebbe fornire un’etichetta nella mappa locations, specificando dove l’oggetto deve essere consegnato.

I valori possono essere omessi se non sono applicabili. Ad esempio, se un acquisto riguarda un pacchetto di prodotti che non hanno prezzi individuali o ID prodotto, il product_id o il price possono non essere specificati nel contratto. Allo stesso modo, per i prodotti virtuali consegnati direttamente tramite l’URI di adempimento, non c’è alcun locale_di_consegna.

commerciante

indirizzo: Questo dovrebbe fornire un’etichetta nella mappa locations, specificando dove si trova il commerciante.
nome: Questo dovrebbe indicare un nome leggibile per l’attività del commerciante.
giurisdizione: Questo dovrebbe fornire un’etichetta nella mappa locations, specificando la giurisdizione sotto la quale questo contratto deve essere arbitrato.

luoghi

Mappa associativa dei luoghi utilizzati nel contratto. Le etichette dei luoghi in questa mappa possono essere scelte liberamente e utilizzate ogni volta che un luogo è richiesto in altre parti del contratto. In questo modo, se lo stesso luogo è richiesto più volte (come l’indirizzo di lavoro del cliente o dell’esercente), deve essere elencato (e trasmesso) solo una volta e può essere altrimenti richiamato tramite l’etichetta. Un elenco non esaustivo di attributi di ubicazione è il seguente:

nome: Nome del destinatario per la consegna, sia esso un’azienda o una persona.
Paese: Nome del Paese di consegna, come si trova su un pacco postale, ad esempio «Francia».
Stato: Nome dello Stato di consegna, come si trova su un pacco postale, ad esempio «NY».
regione: Nome della regione di consegna, come si trova su un pacco postale.
province: Nome della provincia di consegna, come si trova su un pacco postale.
città: Nome della città di consegna, come si trova su un pacco postale.
codice postale: Codice di avviamento postale per la consegna, come si trova su un pacco postale.
strada: Nome della via per la consegna, come si trova su un pacco postale.
numero_di_strada: Numero civico (numero dell’abitazione) per la consegna, come si trova su un pacco postale.

Nota

Le località non sono obbligate a specificare tutti questi campi e possono anche avere campi aggiuntivi. I renderizzatori di contratti devono rendere almeno i campi elencati sopra e dovrebbero rendere i campi che non comprendono come un elenco di valori-chiave.