Il formato dell’ordine di Taler

3.1.6. Il formato dell’ordine di Taler#

Il formato dell’ordine Taler descrive il JSON che deve essere inviato al backend del venditore per creare un ordine. È il prototipo da cui il backend del venditore creerà gli effettivi termini del contratto.

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 al venditore.

max_fee

Questo è l’importo totale massimo delle commissioni di deposito che il venditore è 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 amount.

max_wire_fee

Commissione massima per il bonifico accettata dal venditore (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.

wire_fee_amortization

Su quante transazioni del cliente il venditore prevede di ammortizzare in media le commissioni bancarie? Se la commissione di bonifico dell’Exchange è superiore a 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 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.

pay_url

Quale URL accetta i pagamenti. Questo è l’URL a cui il portafoglio invierà le monete tramite POST.

fulfillment_url

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.

order_id

Identificatore alfanumerico, liberamente definibile dal venditore. Utilizzato dal venditore 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.

pay_deadline

Timestamp dell’ora entro la quale il venditore 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 refund_deadline ed eseguirà un unico grande pagamento tramite bonifico. Gli importi saranno arrotondati per difetto all’unità di bonifico; se l’importo totale è ancora inferiore all’unità di bonifico, non sarà erogato.

refund_deadline

Data limite fino alla quale il venditore è disposto (e in grado) di fornire rimborsi per il contratto utilizzando Taler. Si noti che l’Exchange Taler terrà il pagamento in garanzia almeno fino a questa scadenza. Fino a questo momento, il venditore potrà firmare un messaggio per attivare un rimborso al cliente. Dopo questo termine, non sarà più possibile rimborsare il cliente. Deve essere inferiore a 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à unità di questo prodotto spedite alla delivery_location indicata. Si noti che di solito la somma di tutti i prezzi dovrebbe corrispondere all’importo totale del contratto, ma potrebbe essere diversa a causa di sconti o perché i singoli prezzi non sono disponibili.

product_id

ID univoco del prodotto nel catalogo del venditore. Può essere scelto liberamente, poiché ha un significato solo per il venditore, ma dovrebbe essere un numero nell’intervallo

.

imposte

Mappa delle imposte applicabili che il venditore 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 imposte il venditore intende pagare e può essere utilizzata dal cliente come ricevuta. È probabile che le informazioni vengano utilizzate anche in caso di controlli fiscali sul venditore.

delivery_date

Tempo entro il quale il prodotto deve essere consegnato alla delivery_location.

delivery_location

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, product_id o price potrebbero non essere specificati nel contratto. Allo stesso modo, per i prodotti virtuali consegnati direttamente tramite l’URI di adempimento, non è presente alcun delivery_location.

venditore
indirizzo

Questo dovrebbe fornire un’etichetta nella mappa locations, specificando dove si trova il venditore.

nome

Questo dovrebbe indicare un nome leggibile per l’attività del venditore.

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 commerciale del cliente o del venditore), 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.

zip_code

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.

street_number

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.