Integrazione front-end cassa base - Terminal API
Per avviare l'integrazione base con il front-end di cassa, seguire il flusso:
1. Autenticazione,
2. Avvio cassa, recupero regole e permessi campagna.
Per registrazione una card, seguire il flusso:
1. Autenticazione,
2. Registrazione Card.
Per effettuare un movimento di vendita, seguire il flusso:
1. Autenticazione,
2. Lettura Card,
3. Chiusura scontrino,
4. Acquisto.
Per integrare e gestire la feature Gift Card, seguire il flusso:
1. Autenticazione,
2. Gift Card lettura e uso.
Eliminazione ultimo movimento
1. Autenticazione,
2. Eliminazione ultimo movimento.
Autenticazione
Per eseguire un accesso con scope terminal, effettuare la chiamata all’endpoint POST /auth, inserendo i seguenti parametri:
• username (username dell’operatore che richiede l’accesso),
• password (password associata all’operatore che richiede l’accesso),
• serialnumber (numero seriale legato al terminale associato all’operatore che richiede l’accesso),
• campaignid (l'id della campagna del tuo brand relativo all’ambiente di produzione),
• devicetype (tipo di device da cui il cliente tenta di fare l’accesso 1=Browser 2=Android device 3=iOS Device)
• scope (‘terminal’ o ‘terminal-backoffice’).
In caso di esito positivo, nella risposta otterremo anche il bearer token (token autorizzativo) che dovrà essere inserito nell’header delle successive chiamate alle API di tipo Terminal.
> Ecco un esempio del body in una request all’endpoint POST /auth per effettuare un’autenticazione terminal: <
curl -X POST https://martaapidemo.keyx.it/auth \
--header 'Content-Type: application/json' \
--header 'x-api-key: ••••••' \
{
"username":"opwsDemo",
"password":"123456",
"serialnumber": 444001,
"campaignid": "25427",
"scope": "terminal"
}'
Per maggiori dettagli ed errori esplorare la sezione API Reference.
Avvio cassa, recupero regole e permessi campagna
Per eseguire l’integrazione di front-end di cassa, è necessario acquisire le regole e i permessi della campagna associata al terminale interessato.
1. Effettuare una chiamata all’endpoint GET /terminal/campaign/{campaignid}, specificando nella query il valore “campaignid”, ovvero l’id della campagna.
In caso di esito positivo, in risposta otterremo un oggetto JSON “campaign” che mostra tutte le informazioni relative e un oggetto “terminal” contenente i dettagli del terminale.
Le informazioni contenute nell’oggetto “campaign” ci interesseranno per le successive azioni.
Vedi un esempio di risposta alla chiamata all'endpoint GET /terminal/campaign/{campaignid}.
Per permettere al front-end di cassa di gestire la movimentazione, è importante ottenere le ponderazioni di tutte le categorie di card che possono essere utilizzate dall’account terminal loggato.
2. Effettuare una chiamata all’endpoint GET /terminal/cardcategories.
In caso di esito positivo, in risposta otterremo un oggetto JSON “category” contenente un array con tutte le categorie di card utilizzabili e le corrispettive informazioni.
I dettagli più rilevanti sono quelli relativi alle ponderazioni, ovvero la corrispondenza punti/denaro.
I campi dell'oggetto "category" che ci interessano sono:
• weightChargePointMoney e weightChargePointPoints (definiscono i punti da ottenere in base ai soldi spesi),
• weightPointValueMoney e weightPointValuePoint (definiscono lo sconto ottenibile in base ai punti caricati sulla card).
Vedi un esempio di risposta all’endpoint GET /terminal/cardcategories.
Se la campagna interessata include la presenza di campi dinamici nell’anagrafe del customer, è necessario:
3. Effettuare una chiamata all’endpoint GET /terminal/campaign/dynamicfields/{campaignid}, specificando nella query il valore “campaignid”, ovvero l’id della campagna.
In caso di esito positivo, in risposta otterremo un array di oggetti JSON “dynamicFields”, rappresentante la lista di campi dinamici definiti all’interno della campagna.
Se la campagna interessata include la gestione di prodotti, è necessario:
4. Effettuare una chiamata all’endpoint GET /terminal/product, specificando nella query solo i dettagli per l’impaginazione, ovvero:
• initlimit (limite iniziale),
• rowcount (numero di record da mostrare).
Per maggiori dettagli ed errori esplorare la sezione API Reference.
Registrazione Card
Card con inserimento dati congestione consensi privacy
Per registrare e attivare una nuova card, è necessario:
1. Effettuare una chiamata all’endpoint POST /terminal/customers, inserendo i dati anagrafici di interesse.
Tramite front-end di cassa è possibile creare e attivare una card fisica oppure una card virtuale. I campi che ci interessano in questa fase sono “card”, “fidelycode” e “categoryid”, da inserire nel body della request.
Nel caso in cui intendiamo attivare una card fisica, è necessario valorizzare i campi “card” e “fidelycode” con i codici indicati sulla card interessata, lasciando vuoto il campo “categoryid”.
Se invece intendiamo attivare una card virtuale, i campi “card” e “fidelycode” devono essere lasciati vuoti mentre il campo “categoryid” deve essere valorizzato con l’id della categoria che la nuova card dovrà assumere e da cui deriva la numerazione automatica. E' possibile lasciar vuoto anche il campo "categoryid", in questo modo verrà presa la categoria settata come default della campagna, se la campagna ne dispone.
A questo punto per visualizzare i campi visibili e obbligatori da richiedere al customer e inserire nel body della request, è necessario valutare l’oggetto JSON campaign->completeCustomerFields ottenuto dalla chiamata all’endpoint GET /terminal/campaign/{campaignid} effettuata nel flusso Avvio cassa, recupero regole e permessi campagna.
L'oggetto "completeCustomerFields" elenca le caratteristiche definite di tutti campi anagrafici della campagna. Con caratteristiche intendiamo che un campo può essere visibile (show), può essere visibile in modalità solo lettura (non consentendo modifiche o l'eliminazione del dato | readOnly) o essere obbligatorio (mandatory).
Per ogni campo saranno quindi mostrate tutte le caratteristiche valorizzate secondo le regole della campagna.
> Ecco un esempio di oggetto "completeCustomerFields". <
"completeCustomerFields": {
"showName": true,
"isMandatoryName": true,
"showSurname": true,
"isMandatorySurname": true,
"showBirthdate": true,
"isMandatoryBirthdate": true,
"showAddress": true,
"isMandatoryAddress": false,
"showAddressPrefix": false,
"isMandatoryAddressPrefix": false,
"showZipCode": true,
"isMandatoryZipCode": false,
"showCountry": true,
"isMandatoryCountry": false,
"showGeoLevels": true,
"isMandatoryGeoLevels": false,
"showDNI": true,
"isMandatoryDNI": false,
"showTelephone": false,
"isMandatoryTelephone": false,
"showFax": false,
"isMandatoryFax": false,
"showMobile": true,
"isMandatoryMobile": false,
"showEmail": true,
"isMandatoryEmail": true,
"showGender": true,
"isMandatoryGender": false,
"showNotes": false,
"isMandatoryNotes": false,
"showCustomerDataCanBeUsedForPromotions": true,
"isMandatoryCustomerDataCanBeUsedForPromotions": false,
"showCustomerDataCanBeUsedForStatistics": true,
"isMandatoryCustomerDataCanBeUsedForStatistics": false,
"showCustomerDataCanBeUsedByOthers": false,
"isMandatoryCustomerDataCanBeUsedByOthers": false,
"mandatoryCustomerDataCanGetCurrentLocation": false,
"mandatoryComunicaVerification": false,
"mandatoryInterestAreas": false,
"showCustomerDataCanGetCurrentLocation": false,
"showComunicaVerification": false,
"showInterestAreas": false,
"readOnlyCustomerDataCanBeUsedForPromotions": false,
"readOnlyCustomerDataCanBeUsedForStatistics": false,
"readOnlyCustomerDataCanBeUsedByOthers": false,
"readOnlyCustomerDataCanGetCurrentLocation": false,
"readOnlyComunicaVerification": false,
"readOnlyInterestAreas": false,
"readOnlyName": false,
"readOnlySurname": false,
"readOnlyBirthdate": false,
"readOnlyAddress": true,
"readOnlyAddressPrefix": false,
"readOnlyZipCode": true,
"readOnlyCountry": false,
"readOnlyGeoLevels": false,
"readOnlyDNI": false,
"readOnlyDNIType": false,
"readOnlyTelephone": false,
"readOnlyFax": false,
"readOnlyMobile": false,
"readOnlyEmail": false,
"readOnlyGender": false,
"readOnlyNotes": false,
"readOnlyZone": false,
"readOnlyCanNotModCustInTerminals": false,
"showDNIType": false,
"mandatoryDNIType": false,
"showZone": false,
"mandatoryZone": false,
"showCanNotModCustInTerminals": false,
"mandatoryCanNotModCustInTerminals": false,
"showAccountNumber": false,
"isMandatoryAccountNumber": false,
"readOnlyAccountNumber": false,
"showFrequentFlyerNumber": false,
"isMandatoryFrequentFlyerNumber": false,
"readOnlyFrequentFlyerNumber": false
},
> Ecco un esempio di una request all’endpoint POST /terminal/customers per la creazione di un nuovo customer, con assegnazione automatica del nr di card, con solo alcuni dati essenziali (nome, cognome, data di nascita, cellulare, consensi privacy e un campo dinamico) <
curl -X POST https://martaapidemo.keyx.it/terminal/customers\
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'authorization: ••••••' \
{
"campaignid": 362,
"categoryid": 463,
"card”:"",
"fidelycode": "",
"parentcustomerid": "",
"mlmcustomerid": "",
"mlmcustomercard": "",
"zoneid":"",
"zoneforeignid": "",
"identitycard": "",
"identitycardtypeid": "0",
"name":"Mario",
"surname":"Rossi",
"gender":"M",
"birthdate": "1970-10-01",
"username": "mario.rossi@myemail.it",
"usedforpromotions": true,
"usedforstatistics": true,
"usedbyothers": false,
"cangetcurrentlocation": false,
"cancomunicaverification": false,
"expdateusedprom": "2025-10-31",
"expdateusedstatis": "2025-10-31",
"expdateusedothers": "2025-10-31",
"expdateusedgen": "2025-10-31",
"mailcontactdata": "mario.rossi@myemail.it",
"mobilecontactdata": "33311122777",
"telephonecontactdata": "",
"faxcontactdata": "",
"addressprefix": "",
"address":"",
"addressnumber": "",
"zip":"",
"country":0,
"geolevel1": 0,
"geolevel2": 0,
"geolevel3": 0,
"geolevel4": 0,
"geolevel5": 0,
"facebookid": "",
"twitterid": "",
"instagramid": "",
"youtubeid": "",
"customerdynamicfields": [
{
"id": 648,
"value":"valore di test"
}
],
"accountnumber": "",
"frequentflyernumber": "",
"pathimage": "",
"foreignid": "",
"notsendwelcomemail": false,
"invitor_code": "",
"notes": ""
}
Per la gestione dei consensi privacy, prima di inserire le preferenze relative nel body della query alle chiamate POST /terminal/customers o PUT /terminal/customers (per la modifica delle informazioni della card), è necessario confermare le scelte del customer tramite una verifica double OTP-in.
1. Il primo passaggio corrisponde alla generazione e l'invio di in codice OTP al customer per ogni consenso da inserire o modificare. É necessario quindi effettuare chiamate all’endpoint POST/terminal/customers/genotpcodeconsents, inserendo i seguenti parametri:
• customerid (id del customer, ricevuto in risposta alla chiamata all’endpoint POST /terminal/customers),
• mobile (numero di cellulare del customer | se inserito non serve valorizzare il campo email),
• email (indirizzo email del customer | se inserito non serve valorizzare il campo mobile).
2. Inviati i codici OTP interessati, per verificare le scelte del customer bisogna effettuare una chiamata all’endpoint POST /terminal/customers/verifyOotpcodeconsents, inserendo per ogni consenso legato alla campagna il codice OTP consegnato e la scelta del cliente relativa al consenso specificato.
> Ecco un esempio del body di una request all’endpoint POST /terminal/customers/verifyOotpcodeconsents dove sono stati richiesti tutti i consensi, ma accettati solo il consenso per le promozioni e per la geolocalizzazione. <
curl -X POST https://martaapidemo.keyx.it/terminal/customers/verifyOotpcodeconsents\
--header 'Content-Type: application/json \
--header 'Accept: application/json' \
--header 'authorization: ••••••' \
{
"customerid": 123456,
"promotioncode": "055832",
"promotionconsent": true,
"statisticcode": "274829",
"statisticconsent": false,
"othercode": "235267",
"otherconsent": false,
"geolocationcode": "028474",
"geolocationconsent": true
}
Per maggiori dettagli ed errori esplorare la sezione API Reference.
Lettura Card
Al momento di interazione tra un customer registrato e il front-end di cassa, è necessario effettuare la lettura della card posseduta.
1. Effettuare una chiamata all’endpoint GET /terminal/customers{nrcard}, specificando nella query il valore “nrcard”, ovvero il numero di card.
Questa chiamata permette di recuperare le ponderazioni della card, utili per un’eventuale spesa o movimento successivo.
In caso di esito positivo, in risposta otterremo anche un oggetto JSON “customer” contenente tutte le informazioni della card, sia anagrafiche che contabili, come il saldo punti, i crediti o il badge.
Nel caso in cui il “answerCode” non fosse valorizzato a 0, significa che la chiamata non è andata a buon fine.
Le casistiche di risposta da tenere in considerazione sono:
> “answerCode”= 53
La card richiesta non esiste, ma il numero è comunque tra quelli validi per la campagna. Quindi potrebbe essere il caso di una nuova card che va attivata.
> “answerCode”= 59
La card non è presente in white list. Vuol dire che si è inserito un numero di card che NON può essere utilizzato per la campagna.
> “answerCode”= 60
La card è in blacklist. Vuol dire che il nr di card inserito è relativo ad una card non più esistente, molto probabilmente è stata sostituita con un'altra card.
Vedi un esempio di risposta alla chiamata all’endpoint GET /terminal/customers{nrcard}.
Per maggiori dettagli ed errori esplorare la sezione API Reference.
Chiusura scontrino
Al momento della chiusura dello scontrino, prima del pagamento, è necessario valutare se il customer che sta effettuando l’acquisto ha a disposizione possibili sconti o vouchers.
Relativamente agli sconti, i passi da seguire sono:
1. Recuperare gli oggetti JSON “categories” e “customer” ottenuti dalle chiamate agli endpoint GET /terminal/cardcategories e GET /terminal/customers, vedi i flussi Avvio cassa, recupero regole e permessi campagna e Lettura Card.
2. Dall’oggetto JSON “customer”, recuperare la categoria relativa al customer interessato (customer->balanceData->category) e i punti disponibili (customer->balanceData->balance_points).
3. Dall’oggetto JSON “categories”, recuperare le ponderazioni relative alla categoria interessata.
4. Eseguire i calcoli in base alle ponderazioni ottenute per valutare la presenza di sconti.
Per quanto riguarda i vouchers invece, le API di tipo Terminal offrono l’endpoint GET /terminal/vouchers, permettendo di ottenere l’elenco dei vouchers in possesso del customer.
MARTA indentifica come voucher i buoni sconto, dividendoli in buoni sconto in percentuale e buoni sconto per importo.
1. Effettuare una chiamata all’endpoint GET /terminal/vouchers, specificando nella query:
• campaignid (id della campagna, presente anche nell’oggetto JSON “customer” utilizzato nei passaggi precedenti),
• customer id (id del customer),
• card (numero della card relativa, presente nell’oggetto JSON “customer”).
• initlimit (limite iniziale),
• rowcount (numero di record da mostrare).
In caso di esito positivo, in risposta otterremo un oggetto JSON “voucherList” contenente un array di voucher.
I campi degli oggetti dell’array “vouchersList” che ci interessano sono:
• id (id del voucher),
• voucherCode (Barcode del voucher, da usare per il riconoscimento del voucher),
• title (Descrizione breve del voucher),
• description (Descrizione estesa del voucher),
• expirationDate (Data di scadenza del voucher),
• kind (Tipologia del voucher. 1=sconto in % 2=sconto per importo),
• value (Valore del voucher in percentuale o importo a seconda del kind).
> Ecco un esempio di request all’endpoint GET /terminal/vouchers. <
curl --location 'https://martaapidemo.keyx.it/terminal/vouchers?campaignid=362&customerid=195580&card=4&initlimit=0&rowcount=50'\
--header 'Authorization:••••••'
Per maggiori dettagli ed errori esplorare la sezione API Reference.
Acquisto
L’acquisto rappresenta il momento più complesso se parliamo di interazione tra card e terminale.
Durante l’acquisto infatti, si effettua la maggior parte della movimentazione eseguibile su un punto vendita, perché oltre a registrare l’atto da parte del cliente, vengono gestiti:
> l’utilizzo di benefit per ottenere degli sconti come lo scarico punti, sconti diretti, l’utilizzo di coupon sconto e molto altro,
> l’ottenimento dei punti in base all’importo netto dell’acquisto,
> la ricezione di eventuali benefit.
1. Effettuare una chiamata all’endpoint POST /terminal/movements/sale, inserendo principalmente i seguenti parametri:
• totalmoney (Importo totale della vendita),
• dischargedcredits (Importo dei crediti da scalare all’importo totale della vendita),
• dischargedpoints (Quantità di punti da scaricare, che vengono convertiti in sconto sull’importo totale della vendita),
• voucherid (id del voucher sconto eventualmente utilizzato, da scalare dall’importo totale della vendita).
Se la campagna prevede l’utilizzo dei prodotti, bisogna completare l’array:
• productlist (array contenente la lista dei prodotti utilizzati nella vendita)
prizecode //codicedel prodotto
price //prezzounitario del prodotto
amount //quantità del prodotto
La sommatoria di tutti gli importi di vendita dei singoli prodotti deve corrispondereall’importo totale della vendita contenuto nel campo “totalmoney”. Nel caso non si volesse far calcolare in automatico a MARTA i punti da caricare sulla card per l’acquisto di questo prodotto, è necessario valorizzare i seguenti campi:
useChargeDirectPoints // impostare a true
productChargeDirectPoints //punti da caricare sulla card
• pincode (pincode del cliente, se il movimento di vendita contiene punti da scaricare e la campagna prevede il pincode per lo scarico di punti),
• customerpincodedc (pincodecredit del cliente, se il movimento di vendita contiene crediti da scaricare e la campagna prevede il pincode per lo scarico di crediti),
• paymentmethod (metododel pagamento, se nella campagna viene registato),
L’array “paymentmethod” contiene l’elenco dei metodi di pagamento utilizzati e i campi obbligatori da inserire nell’oggetto sono:
id //id del tipo di pagamento
money //importo pagato
La sommatoria degli importi dei vari metodi di pagamento deve corrispondere all’importo netto della vendita ottenuto sottraendo al campo “totalmoney” il valore di “dischargedcredits”, il valore monetario di “dischargedpoints” e il valore del voucher indicato da “voucherid”.
Nel caso non si volesse far calcolare in automatico a MARTA i punti da caricare sulla card per l’acquisto, è necessario valorizzare i seguenti campi:
• usechargedirectpoints (da valorizzare a true nel caso non si volesse far calcolare automatico a MARTA i punti da caricare in base alle ponderazioni impostate),
• chargedirectpoints (quantità di punti da caricare scelta, da inserire nel caso usechargedirectpoints sia stato valorizzato a true).
△ É importante notare che la possibilità di definre il caricamento forzato di punti sulla card si presenta due volte: nella compilazione dell’array productlist e allafine del body della request. Questi campi sono autoesclusivi, di conseguenza è necessario valorizzare i valori corretti o nel dettaglio prodotti o nel totale del movimento, mai in entrambi per evitare incongruenze.
Come annunciato prima, per calcolare l’effettivo importo netto della vendita è necessario sottrarre al valore del campo “totalmoney” il valore di “dischargedcredits”, il valore monetario di “dischargedpoints” e il valore del voucher indicato da “voucherid”.
Il valore monetario di “dischargedpoints” e il valore dell’eventuale voucher indicato in “voucherid” sono recuperabili seguendo la sezione Chiusura Scontrino.
> Ecco un esempio di request con curl all’endpoint POST /terminal/movements/sale. In questo esempio viene registrata una una spesa di 10 euro con 2 prodotti, di cui su uno è stato forzato l’assegnazione di 8 punti escludendo la ponderazioine, l’utilizzo di crediti per 5 euro, e l’utilizzo di un metodo di pagamento. <
curl --location'https://martaapidemo.keyx.it/terminal/movements/sale' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'authorization: ••••••' \
--data '{
"campaignid": 362,
"customerid": 195580,
"card": 4,
"dischargedcredits":5,
"dischargedpoints":0,
"totalmoney": 10,
"totalBenefits": 0,
"ticketid": "",
"discountid": "",
"voucherid": "",
"operatorforeignid": "",
"paymentmethod": [
{
"id":46,
"money": 5
}
],
"foreignid": "",
"productlist": [
{
"code" : "pro2",
"price" : 7,
"amount" : 1
},
{
"code" : "pro1",
"price" : 3,
"amount" : 1,
"useChargeDirectPoints":true,
"productChargeDirectPoints": 8
}
],
"note":"Any string note you want",
"customerpincodedc": 1234
}
In caso di esito positivo, in risposta alla chiamata all'endpoint POST /terminal/sale otterremo gli oggetti JSON "customer", "movement" e "shop", che contengono le rispettive informazione legate all'acquisto effettuato.
Se a seguito dell'acquisto sono state vinte una o più promozioni, nella risposta sarà presente un array di oggetti JSON "promotions", che includono tutti i dettagli relativi ai premi ottenuti.
I campi dell'oggetto "promotions" che possono interessarci per la visualizzazione delle informazioni sono:
• promotions-> promotionID (codice id della promozione),
• promotions-> description (titolo della promozione),
• promotions-> shortDescription (descrizione breve della promozione) ,
• promotions-> longDescription (descrizione estesa della promozione),
• promotions->promotionPrizes (elementi che descrivono i premi vinti ed eventuali messaggi o immagini da visualizzare).
Gli oggetti “promotionPrizes” contengono quattro campi, di cui i più rilevanti sono:
• “kind”,
• “valuePrize”.
I valori di "kind" 11 e 7 sono associati ad un premio testuale, di conseguenza nel campo “valuePrize” saranno mostrati i testi da far vedere.
△ All’interno del testo può presentarsi una serie numerica preceduta dal carattere“#”, la quale rappresenta un barcode relativo ad un premio o voucher vinto. Se siamo interessati, è possibile stampare il barcode su ticket o scontrino, creando un barcode di tipo 128C.
Il valore di "kind" 37 è invece associato ad un premio che coinvolge la presenza di un'immagine, di conseguenza, nel campo “valuePrize” viene mostrato l’url dell’immagine da visualizzare.
> Quello sottostante è un esempio di oggetto “promotions” con dei testi e l’immagine legata alla promo. <
"promotions": [
{
"promotionID": 3864,
"description": "Doppi punti fino a fine gennaio",
"shortDescription": "Per tutto il mese di gennaio, per te doppi punti",
"longDescription": "Per ogni tuo acquisto del mese di gennaio, riceverai doppi punti.",
"budget": 0,
"budgetUsed": 0,
"budgetUsedPercent": 0,
"promotionPrizes": [
{
"kind": 7,
"valuePrize": {
"attributes": {
"xsi:type": "xs:string"
},
"$value": "Complimenti hai vinto doppi punti!!"
},
"urlImageWS": "nullnull",
"finalPointsPrize": 0,
"consolationPrize": false
},
{
"kind": 3,
"valuePrize": {
"attributes": {
"xsi:type": "xs:decimal"
},
"$value": "0.5"
},
"urlImageWS": "nullnull",
"finalPointsPrize": 0,
"consolationPrize": false
},
{
"kind": 37,
"valuePrize": {
"attributes": {
"xsi:type": "xs:string"
},
"$value": "https://v3demo.fidelynet.it/files/dev/promotions/campaigns/362/10_1.jpg"
},
"finalPointsPrize": 0,
"consolationPrize": false
}
]
}
]
Per maggiori dettagli ed errori esplorare la sezione API Reference.
Eliminazione ultimo movimento
Per eseguire l’eliminazione dell’ultimo movimento effettuato su una Card, è necessario:
1. Seguire il flusso Lettura Card.
2. Effettuare una chiamata all’endpoint DELETE /terminal/movements/last, inserendo nel body della request i seguenti parametri:
• customerid (l’id del customer, ottenuto dal passo precedente | campo obbligatorio),
• notes (note relative all’eliminazione se è necessario).
△ É importare notare che esiste una parametrizzazione a livello campagna che permette di impostare un limite di tempo entro il quale effettuare questa eliminazione.
> Ecco un esempio di una request all’endpoint DELETE /terminal/movements/last. <
curl --location'https://martaapidemo.keyx.it/terminal/movements/last' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'authorization: ••••••' \
{
"customerid":123456,
"notes”:"”
}
Per maggiori dettagli ed errori esplorare la sezione API Reference.
Gift card lettura e uso
All’interno della tua campagna, puoi intraprendere e gestire la feature delle Gift card.
Prima di integrare questa funzionalità, è essenziale aver recuperato gli oggetti JSON “categories” e “customer” ottenuti dalle chiamate agli endpoint GET /terminal/cardcategories e GET /terminal/customers, vedi i flussi Avvio cassa, recupero regole e permessi campagna e Lettura Card.
Per attivare una gift card da terminale è necessario:
1. Effettuare una chiamata all’endpoint POST /terminal/gift, passando nel body della request i seguenti parametri:
• campaignid (l'id della campagna del tuo brand relativo all’ambiente di produzione),
• card (numero della gift card di riferimento),
• initialamount (valore dell’importo da caricare sulla Gift card),
• notes.
Nel caso il parametro "initialamount" venga passato a zero, la gift card viene caricata con l’importo di default definito sulla categoria della card, altrimenti viene caricata con l’importo inserito.
> Ecco un esempio del body di una request all’endpoint POST /terminal/gift. <
curl --location'https://martaapidemo.keyx.it/terminal/gift' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'authorization: ••••••' \
{
"campaignid": 362,
"card":6029,
"initialamount": 50,
"notes":""
}
Per poter scaricare crediti da una gift card occorre:
1. Effettuare una chiamata all’endpoint POST /terminal/movements/dischargecreditsgift, inserendo nel body della requesti seguenti parametri:
• campaignid (l'id della campagna del tuo brand relativo all’ambiente di produzione),
• customerid (codice id del customer),
• card (numero della gift card di riferimento),
• dischargegiftcredits (quantità di crediti da scaricare).
• customerpincodepc.
Nel caso la campagna abbia attivato la gestione del pincode crediti, è obbigatorio passare anche il campo customerpincodepc che deve contenere il pincode.
> Ecco un esempio di request all’endpoint POST / terminal/movements/dischargecreditsgift. <
curl --location'https://martaapidemo.keyx.it/terminal/movements/dischargecreditsgift' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"campaignid": 362,
"customerid": 463874,
"card":6029,
"dischargegiftcredits": 15,
"notes":"",
"customerpincodepc": null
}’
Per maggiori dettagli ed errori esplorare la sezione API Reference.