Tutorial

L'accesso alle API di MARTA viene gestito con un sistema di autenticazione a doppio livello:

          1. l'autenticazione alla chiamata all'endpoint POST /auth avviene tramite api-key rilasciata da MARTA da inserire nell'header della query;

          2. nella risposta alla chiamata all'endpoint POST /auth viene consegnato un JWT (JSON Web Token) firmato e validato da includere nell'header delle query ai successivi endpoint interessati.

‍

Per ottenere un token di sessione valido è necessario quindi effettuare una chiamata all'endpoint POST /auth.

‍

Richiesta di Accesso da Backoffice

Per autenticazione con scope backoffice, oltre all'inserimento dell'api-key nell'header, inserire nella request i parametri:

          • username (username dell’operatore che richiede l’accesso),

          • password (password associata all’operatore che richiede l’accesso),

          • campaignid (l'id della campagna del tuo brand relativo all’ambiente di produzione | vuoto se l’operatore ha un accesso Rete),

          • devicetype (tipo di device da cui il cliente tenta di fare l’accesso 1=Browser 2=Android device 3=iOS Device)

          • scope (tipo di accesso richiesto, in questo caso ‘backoffice’).

‍

> Ecco un esempio di una request all’endpoint POST /auth per effettuare un’autenticazione backoffice <

curl -X POST https://martaapidemo.keyx.it/auth \

--header 'Content-Type: application/json' \

--header 'x-api-key: ••••••' \

{

             "username":"opApiDoc",

             "password":"Password123!",

             "campaignid ": "16273",

             "devicetype":"1"

             "scope": "backoffice"

}'

‍

Richiesta di Accesso da Terminale

Per autenticazione con scope terminal o terminal-backoffice, oltre all'inserimento dell'api-key nell'header, inserire nella request i 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 (tipo di accesso richiesto, in questo caso ‘terminal’).

‍
> Ecco un esempio di 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":"opApiDoc",

             "password":"Password123!",

             "campaignid ": "16273",

             "devicetype":"1"

             "scope": "terminal-backoffice"

}'

‍

Richiesta di Accesso Customer

     > Richiesta con scope customersynchro

Per autenticazione con scope customersynchro, oltre all'inserimento dell'api-key nell'header, inserire nella request i parametri:
(accesso da utilizzare se le azioni da eseguire sono prima o in fase di registrazione del cliente, quindi prima del login)

          • username (campo da non inserire),

          • password (campo da non inserire),

          • 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 (tipo di accesso richiesto, in questo caso ‘customersynchro’).

‍

> Ecco un esempio di una request all’endpoint POST /auth per effettuare un’autenticazione customersynchro <

curl -X POST https://martaapidemo.keyx.it/auth \

--header 'Content-Type: application/json' \

--header 'x-api-key: ••••••' \

{

             "campaignid ": "16273",

             "devicetype":"2",

             "scope": "customersynchro"

}'

‍

     > Richiesta con scope customer

Per autenticazione con scope customer, oltre all'inserimento dell'api-key nell'header, inserire nella request i parametri:

          • username (username dell’account del customer),

          • password (password dell’account del customer),

          • 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 (tipo di accesso richiesto, in questo caso ‘customer’).

‍

> Ecco un esempio di una request all’endpoint POST /auth per effettuare un’autenticazione customer <

curl -X POST https://martaapidemo.keyx.it/auth \

--header 'Content-Type: application/json' \

--header 'x-api-key: ••••••' \

{

             "username":"+393728273349",

             "password":"Password123!",

             "campaignid ": "16273",

             "devicetype":"2",

             "scope": "customer"

}'

‍

‍

Se l'esito della chiamata all'endpoint POST /auth è stato http 200, si ottiene in risposta un oggetto JSON dove saranno presenti i campi "token" e "refreshtoken".

‍

Per maggiori dettagli ed errori, vedere l'endpoint POST /Auth.

Per eseguire l'accesso di un customer già registrato seguire il flusso:

          1. Accesso.

‍

Per eseguire la registrazione di un nuovo customer seguire i flussi:

          1. Registrazione,

          2. Nuovo utente,

          3. Inserimento dati.

‍

Per eseguire la registrazione di un customer che possiede già una card, ma non è registrato, seguire i flussi:

          1. Registrazione,

          2. Utente con card,

          3. se necessario, Inserimento dati.

‍

Accesso

‍

Se l’utente intende accedere alla sua area riservata, questi sono i passaggi da seguire:

          1. Effettuare la chiamata di autenticazione con scope customer tramite l'endpoint POST /auth per ottenere un token di sessione valido.

La risposta, se andata a buon fine, restituirà il token e un oggetto json "customer" con le informazioni del cliente di riferimento.

‍

          2. Verificare che nell’oggetto “customer”, siano compilati tutti i dati obbligatori della tua campagna.

Se mancano dei dati, significa che il cliente ha abortito la registrazione prima del termine della procedura e occorre reindirizzarlo ad una pagina di errore.

In caso di esito positivo, invece, il cliente ha completato l'accesso.

‍

Registrazione

‍

Se l’utente intende registrarsi, questi sono i passaggi da seguire:

          1. Richiedere all’utente un valore da inserire per “numero di cellulare” o “email” e registrarlo.

          2. Effettuare la chiamata di autenticazione con scope customersynchro tramite l'endpoint POST /auth per ottenere un token di sessione valido.

In caso di esito positivo, nella risposta otterremo anche il bearer token (token autorizzativo) che dovrà essere inserito nell’header delle successive chiamate.

‍

          3. ‍Verificare se il customer esiste già, ovvero se ha già una card, e se ha completato l'anagrafica.

Per ottenere queste informazioni, effettuare una chiamata tramite l'endpoint GET /customer/checkcard inserendo oltre al token inserito i campi:

               • card (da inserire se il valore richiesto e inserito durante la registrazione è il numero della card posseduta dal customer),

               • email (da inserire se il valore richiesto e inserito durante la registrazione è un indirizzo email),

               • mobile (da inserire se il valore richiesto e inserito durante la registrazione è un numero di cellulare).
‍

Le possibili casistiche di risposta sono:

          > Se l’esito è tornato con status 402 e 53 su "answerCode", il customer è un nuovo utente e bisogna registrarlo seguendo il flusso Nuovo utente;

          > Se l’esito è tornato con status 200, il customer possiede già una card, ma se il campo "registered_customer" è false, è necessario registrare il campo “customerid” ottenuto e seguire il flusso Utente con card;

          > L’esito è tornato con status 200 ed il campo "registered_customer" è true, l’utente è già registrato, quindi bisogna ritornare alla pagina di login seguendo il flusso di Accedi;

          > L’esito è tornato con uno status diverso dai precedenti, significa che si sono presentati errori relativi per esempio al numero o status di card o per mancanza di permessi, quindi segnalare errore e tornare alla pagina d’inizio.

‍

Per vedere maggiori dettagli tecnici ed errori, esplorare la sezione API Reference.

‍

Nuovo utente

‍

Per registrare un nuovo utente, i passaggi da seguire sono:

          1. Permettere all’utente di inserire la nuova password.

          2. Se non si possiede già un token autorizzativo valido con scope customersynchro, effettuare la chiamata di autenticazione con scope customersynchro tramite l'endpoint POST /auth per ottenere un token di sessione valido.

          3. Inviare un codice di validazione per la verifica OTP al momento del click da parte del cliente sull’icona di riferimento.

Effettuare a quel punto una chiamata tramite l’endpoint POST /customer/verifyemail inserendo i seguenti parametri:

               • campaignid (l'id della campagna del tuo brand relativo all’ambiente di produzione),

               • email (da inserire se il valore richiesto e inserito durante il flusso Registrati è un indirizzo email),

               • mobile (da inserire se il valore richiesto e inserito durante il flusso Registrati è un numero telefonico),

               • devicetype (tipo di device da cui il cliente tenta di fare l’accesso 1=Browser 2=Android device 3=iOS Device).

Se l’esito è positivo, quindi ha status http 200, proseguire. Altrimenti segnalare che l’invio del codice OTP non è andato a buon fine e rimanere su questa pagina. 

          4. Inviato il codice, effettuare una chiamata tramite l’endpoint PUT/customer/registrationvcwithverificationcode per verificare il codice OTP (verification code), e, se corrisponde, registrare direttamente l’utente, inserendo i seguenti parametri:

               • verificationcode (codice OTP ottenuto),

               • password (la password inserita precedentemente),

               • devicetype (1=Browser, 2=Android device, 3=iOS device),

               • campaignid (l'id della campagna del tuo brand relativo all’ambiente di produzione),

               • categoryid (l’id della categoria di card virtuale da attivare),

               • username (il valore inserito durante il flusso Registrati che sia numero di cellulare o email),

               • mailcontactdata (da inserire se il valore inserito durante il flusso Registrati è un indirizzo email),

               • mobilecontactdata (da inserire se il valore inserito durante il flusso Registrati è un numero di cellulare).

Se l’esito è positivo (http status 200), l’utente è stato creato e abbiamo ottenuto in risposta le info dell’account compreso il numero di card associato. Continuare sul flusso “Inserimento dati”.

In caso di errore mostrare l'errore e rimanere sulla pagina, altrimenti andare alla pagina successiva.

‍

‍Per vedere maggiori dettagli tecnici ed errori, esplorare la sezione API Reference.

‍

Utente con card

‍

Per abilitare un nuovo utente all'area riservata che possiede già una card, i passaggi da seguire sono:

          1. Permettere all’utente di inserire la nuova password.

          2. Se non si possiede già un token autorizzativo valido con scope customersynchro, effettuare la chiamata di autenticazione con scope customersynchro tramite l'endpoint POST /auth per ottenere un token di sessione valido.

          3. Inviare un codice di validazione per la verifica OTP al momento del click da parte del cliente sull’icona di riferimento.

Effettuare a quel punto una chiamata tramite l’endpoint POST /customer/generateverificationcode inserendo i seguenti parametri:

               • customerid (l'id del customer ottenuto durante il flusso Registrati),

               • email (da inserire se il valore richiesto e inserito durante il flusso Registrati è un indirizzo email),

               • mobile (da inserire se il valore richiesto e inserito durante il flusso Registrati è un numero telefonico),

               • devicetype (tipo di device da cui il cliente tenta di fare l’accesso: 1=Browser, 2=Android device, 3=iOS Device).

Se l’esito è positivo, quindi ha status http 200, proseguire. Altrimenti segnalare che l’invio del codice OTP non è andato a buon fine e rimanere su questa pagina.

          4. Inviato il codice, verificare il codice OTP (verification code), e, se corrisponde, modificare le credenziali dell’utente.
Per questo effettuare una chiamata tramite l’endpoint PUT/customer/changeuapbyverificationcode, inserendo i seguenti parametri:

               • customerid (l'id del customer ottenuto durante il flusso Registrati),

               • username (il valore inserito durante il flusso Registrati che sia numero di cellulare o email),

               • password (la password inserita precedentemente),

               • verificationcode (codice OTP ottenuto).

Se l’esito è positivo (http status 200), l’utente è stato abilitato all'accesso all'area riservata e abbiamo ottenuto in risposta le info dell’account compreso il numero di card associato.

Quindi possiamo continuare sul flusso Inserimento dati.

In caso di errore mostrare l'errore accaduto e rimanere sulla pagina, altrimenti andare alla pagina successiva.

‍

‍Per vedere maggiori dettagli tecnici ed errori, esplorare la sezione API Reference.

‍

Inserimento dati

‍

Conclusi i flussi Registrati e Nuovo utente o Utente con card, l'account è stato creato e abbiamo ottenuto l'username (il numero di cellulare, l'indirizzo email o il numero di card) e la password dell’utente.

Per richiedere l’inserimento dei dati anagrafici del nuovo utente, i passaggi da seguire sono:

          1. Effettuare la chiamata di autenticazione con scope customer tramite l'endpoint POST /auth per ottenere un token di sessione valido, con username e password ottenute.

Se l’esito dovesse essere negativo, rinviare alla pagina di errore e rivolgersi all’assistenza.

‍

          2. Ottenere la lista dei campi (dati anagrafici) da compilare effettuando una chiamata tramite l'endpoint GET /customer/customerdatafields/{campaignid} inserendo il parametro:

               campaignid (l'id della campagna del tuo brand relativo all’ambiente di produzione).

In risposta otteniamo la lista dei campi fissi della piattaforma. Sono presenti due oggetti: "customDataFields", contenente la lista dei dati anagrafici del cliente, e "privacyCustomDataFields", contenente la lista dei permessi privacy.

Per ogni campo all’interno di questi oggetti, vengono specificati la visibilità (quindi se è necessario mostrarlo durante la compilazione) e l’obbligatorietà del campo, attraverso due booleani.

          3. Effettuare una chiamata tramite l'endpoint GET /customer, inserendo nessun parametro.

In risposta otteniamo tutti i dati del customer che sono stati già registrati, permettendo di precompilare i dati del form proposto con i dati rilevati dalla chiamata.
Attraverso questa chiamata otteniamo anche il campo “card” (numero della card) e il campo “fidelyCode” (barcode relativo).

          4. Mostrare i campi ricevuti e attendere l’inserimento, controllando i campi obbligatori e altri possibili errori.

          5. Al termine dell’inserimento dei dati da parte del cliente, è necessario aggiornare i campi sull'anagrafica del customer.

Per questo, effettuare una chiamata tramite l'endpoint PUT /customer, inserendo i seguenti parametri:

               • name (nome inserito, se richiesto),

               • surname (cognome inserito, se richiesto),

               • gender (genere inserito, se richiesto),

               • birthdate (data di nascita inserito , se richiesto),

               • usedforpromotions (scelta di interazione con consenso richiesto (true o false),

               • ... Possibili altri consensi da settare se richiesti dalla campagna,

               • mobilecontactdata (numero di cellulare registrato per l’utente),

               • mailcontactdata (indirizzo email registrato per l’utente),

               • ... Possibili altri tipi di contatti e geolocalizzazione da settare se richiesti dalla campagna.

‍

‍Per vedere maggiori dettagli tecnici ed errori, esplorare la sezione API Reference.

Per costruire un'area riservata al cliente, dopo aver eseguito l'Onboarding, i flussi da seguire sono:

          1. Visualizzazione della Home.     

          2. Pagine di Dettaglio.

          3. Profilo personale.

          4. se necessario, Store locator.

Saranno analizzati anche i flussi:

          5. Eliminazione del profilo,

          6. Recupero Password.

‍

‍

Visualizzazione della Home

‍

All'interno della home della tua area riservata puoi mostrare:
          > le informazioni relative alla card, ai punti e al percorso loyalty che il cliente sta svolgendo,
          > le news in primo piano,
          > le promozioni in primo piano,
          > i servizi aggiuntivi del tuo brand in primo piano.

‍

Per la creazione e la gestione della home all'interno dell'area riservata, è necessario ottenere un token di sessione valido, effettuando una chiamata di autenticazione con scope customer tramite l'endpoint POST /auth.

‍

> Dati Card

‍Per richiedere tutte le informazioni utili legate alla card, ai punti e al percorso dell’utente, sono necessari due passaggi:

          1. Effettuare una chiamata all’endpoint GET /customer, senza inserire nessun parametro.
In risposta, otteniamo le informazioni anagrafiche del customer, il proprio saldo punti nel campo customer->balance_points e la categoria della card posseduta nel campo customer->category.

          2. Effettuare una chiamata all’endpoint GET /customer/category/{categoryid}, inserendo il parametro:

               • categoryid (id della categoria ottenuto nella chiamata precedente).

Se l’esito è positivo, in risposta otteniamo l'oggetto "categoryDTO" contenente le caratteristiche della card del customer, tra cui il valore dei punti in denaro.

‍

I campi dell'oggetto "categotyDTO" interessati per la visualizzazione sono:

               • categoryDTO->weightPointValuePoints,

               • categoryDTO->weightPointValueMoney,

e insieme definiscono il rapporto punti - denaro a disposizione.

In base a questi valori e al saldo punti si possono calcolare quanti punti mancano agli obiettivi successivi e mostrare il percorso che l’utente sta facendo.

‍

> News

‍Per ottenere e mostrare la lista delle news in primo piano, è necessario questo passaggio:

          1. Effettuare una chiamata all'endpoint GET /customer/news passando i seguenti parametri:

               • infocus (valore che definisce la tipologia di news da ricevere, in questo caso 1 || 0=tutte le news, 1=solo le news in primo piano, 2=solo le news NON in primo piano),

               • ... Possibili altri valori da aggiungere per filtrare maggiormente le news da ricevere.

Se l’esito è positivo, in risposta otteniamo un array di oggetti “news”, che saranno quelle visibili al customer, già ordinate.

‍

I campi dell’oggetto “news”  interessati per la visualizzazione sono:

               • news->title (titolo della news)

               • news->summaryText (breve descrizione che sarà mostrata su homescreen)

               • news->expireDate (data di scadenza da controllare prima di mostrare la news)

               • news->newsCategory (array che evidenzia la categoria di news per un possibile filtraggio sul homescreen)

               • news->image (immagine URL della news).

‍

> Promozioni

‍Per ottenere la lista delle promozioni valide per il customer è necessario questo passaggio:

          1. Effettuare una chiamata all'endpoint GET /customer/promotionsoftarget, inserendo il parametro:

               • status (lo stato delle promozioni sa ricevere || 0=Promo starting in thefuture 1=In execution 2=Stopped 3=Ended).

In questo caso, lo stato deve essere valorizzato a 1=In execution.

Se l’esito è positivo, in risposta otteniamo una serie di informazioni tra le quali l’array di oggetti "promotions" contenente i principali dati relativi alle promozioni.

‍

I campi dell'oggetto “promotions” interessati per la visualizzazione sono:

               • description (nome della promozione),

               • summaryText (descrizione breve della promozione),

               • dateTo (termine della promozione),

               • urlImage (immagine della promozione),

               • status (status della promozione).
‍

Inoltre per ogni oggetto promo, è presente un array di oggetti “prizes”, che rappresentano i premi che si ottengono vincendo la promozione.

I campi dell'oggetto “prizes” interessati per la visualizzazione sono:

               • kind (la tipologia di premio),

               • value (la descrizione del premio).

‍

> Servizi aggiuntivi

‍Per ottenere l'elenco dei servizi aggiuntivi occorre:

          1. Effettuare la chiamata all'endpoint GET/customer/availableservices, inserendo i parametri:

               • campaignid (l'id della campagna del tuo brand relativo all’ambiente di produzione | obbligatorio),

               • categoryid (id della categoria servizi da inserire solo se vogliamo i servizi di quella specifica categoria),

               • initlim e rowcount (parametri per la paginazione).

Se l’esito è positivo, in risposta si ottiene un array di oggetti "additionalServices".

‍

I campi dell'oggetto “additionalServices” interessati per la visualizzazione sono:

               • additionalServices->title (titolo del servizio),

               • additionalServices->summary (la descrizione breve da mostrare su homescreen),

               • additionalServices->visibleFrom e additionalServices->visibleTo (intervallo di date di validità del servizio da controllare prima di mostrare il servizio),

               • additionalServices->enable (booleano che descrive se il servizio è attivo o meno).

‍

‍Per maggiori dettagli ed errori esplorare la sezione API Reference.

‍

‍

Pagine di dettaglio

‍

Per la creazione e la gestione delle pagine di dettaglio all'interno dell'area riservata, è necessario ottenere un token di sessione valido, effettuando una chiamata di autenticazione con scope customer tramite l'endpoint POST /auth.

‍

> Pagina di dettaglio per la Card

‍Per elaborare la pagina di dettaglio dedicata alle informazioni della Card del cliente, è necessario:

          1. Effettuare una chiamata all’endpoint GET /customer (se non è stata effettuata in precedenza) senza inserire nessun parametro.
Se l’esito è positivo, otteniamo l’oggetto “customer”.

‍

I campi dell’oggetto “customer” interessati per la visualizzazione sono:

              • customer->name,

              • customer->surname,

              • customer->balance_points (saldo punti),

              • customer->card (numero card),

              • customer->fidelyCode (barcode o fidelycode della card),

              • customer->status (status della card, dove 1=attiva, 2=bloccata, 3=eliminata).

‍

> Pagina di dettaglio per le promozioni

‍Per elaborare la pagina di dettaglio dedicata alla lista delle promozioni valide, è necessario:

          1. Effettuare la chiamata all’endpoint GET /customer/promotionsoftarget, inserendo il parametro:

               • status (0=Promozione non ancora attiva 1=Promozione attiva 2=Promozione fermata 3=Promozione finita).

Per ottenere la lista delle promozioni attive validare il campo status = 1 e per visualizzare un archivio invece, validare il campo status = 3.

Se l’esito è positivo, in risposta otteniamo tra le altre informazioni un array di oggetti “promotions” contenenti i principali dati di ogni promozione.

‍

L’oggetto “promotions” è composto principalmente da:

               • description (nome della promozione),

               • summaryText (descrizione breve della promozione),

               • fullText (descrizione dettagliata della promozione),

               • dateTo (data termine della promozione),

               • urlImage (url dell’immagine della promozione),

               • status (status della promozione),

               • [prizes] (array di oggetti “prizes” che descrivono i premi relativi alla promozione).

L’oggetto “prizes” è composto principalmente da:

               • kind (la tipologia di premio),

               • value (la descrizione del premio).

La lista di kind per i premi sono molteplici, alcuni dei premi più comuni sono:

          > kind=3 (premio: punti con moltiplicatore, e conseguentemente nel campo value sarà indicato il valore per il quale moltiplicare i punti del cliente),

          > kind 4 (premio: punti fissi, e conseguentemente nel campo value sarà indicato il valore fisso di punti vinti),

          > kind=7 (evento: messaggio da fare apparire sul terminale in caso di vincita),

          > kind=9 (premio: un buono sconto in %, e conseguentemente nel campo value sarà indicato il valore percentuale di sconto),

          > kind=10 (premio: un buono sconto in importo fisso, e conseguentemente nel campo value sarà indicato il valore di importo del buono),

          > kind=11 (evento: messaggio da fare apparire sul terminale in caso di vincita di un buono),

          > kind=37 (evento: immagine da mostrare sul terminale in caso di vincita),

          > kind=21 (premio: premio a catalogo, inseguito ad una promozione di tipo instant win, e conseguentemente nel campo value sarà indicata la descrizione del premio).
‍

Tranne nella casistica di una promozione di tipo instantWin, che permette l’opzione di vincita di un premio di consolazione, per ogni promozione è possibile definire un solo tipo di benefit di vincita.
‍

> Pagina di dettaglio per i servizi aggiuntivi

Per elaborare la pagina di dettaglio dedicata alla lista dei servizi aggiuntivi, è necessario:

          1. Effettuare la chiamata all'endpoint GET /customer/availableservices, inserendo i parametri:

              • campaignid (obbligatorio | l'id della campagna del tuo brand relativo all’ambiente di produzione),

              • categoryid (id della categoria servizi da inserire solo se vogliamo iservizi di quella specifica categoria),

              • initlim e rowcount (parametri per la paginazione).

Se l’esito è positivo, in risposta si ottiene un array di oggetti "additionalServices".

‍

L’oggetto “additionalServices” è composta da:

              • additionalServices->categoryId (categoria dei servizi),

              • additionalServices->pathImage (url dell’immagine del servizio),

              • additionalServices->title (titolo del servizio),

              • additionalServices->summary (la descrizione breve da mostrare su homescreen),

              • additionalServices->description (descrizione dettagliata del servizio),

              • additionalServices->visibleFrom e additionalServices->visibleTo (intervallo di date di validità del servizio da controllare prima di mostrare il servizio),

              • additionalServices->enable (booleano che descrive se il servizio è attivo o meno).

‍

> Pagina di dettaglio per i coupon

‍Per elaborare la pagina di dettaglio dedicata alla lista dei coupon ottenuti e disponibili al cliente, è necessario:

          1. Effettuare la chiamata all'endpoint GET /customer/vouchers, inserendo i parametri per l’impaginazione:

              • initlimit (inizio elenco),

              • rowscount (numero di record da visualizzare).

Se l’esito è positivo, in risposta otteniamo diverse informazioni tra le quali un array di oggetti json "voucherList", che contiene tutte le informazioni relative al voucher, alla promozione al quale è associato e ai dettagli di utilizzo.

‍

Per completare la lista di coupon disponibili, i campi dell'oggetto "voucherList" interessati sono:

              • voucherList->title,

              • voucherList->description,

              • voucherList->used (che specifica se il coupon è stato utilizzato o meno),

              • voucherList->expirationDate,

              • voucherList->kind,

              • voucherList->value,

              • voucherList->netInUseList->name (nel caso in cui canUseVoucherOnlyInNet è validato a true).

‍

> Pagina di dettaglio per le news

Per mostrare la lista delle news legate alla campagna,

          1. Effettuare una chiamata all'endpoint GET /customer/news passando il parametro:

              • infocus (0=tutte le news, 1=solo le news infocus, 2=solo le news NON infocus | in questo caso infocus=0).

In caso di esito positivo, otterremo nella risposta un array di oggetti "news", ovvero la lista delle news che il customer può vedere, già ordinate secondo data di creazione. Durante la creazione di una news, MARTA permette di specificare lo stato in primo piano delle news che ci interessa mettere in evidenza. Le news in primo piano quindi si troveranno ai primi posti della lista di oggetti ottenuti in risposta.

‍

L'oggetto "news" è composto dai campi:

              • id (codice id della news),

              • title (titolo della news),

              • summaryText (breve descrizione della news),

              • fullText (descrizione della news),

              • image (immagine della news),

              • imageHiperLink (link da associare l'immagine della news),

              • issuedDate (data della creazione della news),

              • viewDate (data di inizio della visualizzazione della news),

              • expireDate (data di scadenza della visualizzazione della news),

              • campaignId (codice id della campagna su cui viene attivata la news),

              • seen (booleano che definisce lo stato della news || true se la news è stata letta dal customer),

              • seenCount (numero di volte in cui la news è stata letta),

              • newsCategory": {
                         ID                 (codice id della categoria relativa alla news),
                         name           (nome della categoria relativa alla news),
                         description  (descrizione della categoria relativa alla news),
                         campaignId (codice id della campagna su cui la categoria di news è attivata).

                  }

‍

△ È importante ricordare che nella lista di oggetti "news" vengono inserite anche le news la cui visualizzazione è scaduta. Di conseguenza, prima di mostrare una news, è necessario controllare, se presente, la data di scadenza della visualizzazione della news definita nel campo news->expireDate.

‍

          2. Per registrare la lettura di una news, occorre effettuare una chiamata all'endpoint POST /customer/news/read passando nel campo "idnews" il codice id della news di cui si sta mostrando il dettaglio, in modo da registrare che il customer ha letto la news.

‍

Per costruire la lista delle news, occorre usare i campi:

              • news->title per il titolo della news,

‍              • news->summaryText per mostrare la breve descrizione della news,

‍              • news->image per l'immagine della news,

              • news->seen se si intende evidenziare le news ancora da leggere.

‍

Per comporre la pagina di una news in dettaglio, bisogna tenere conto anche dei campi:

              • news->imageHiperLink, se valorizzato, per associare il link indicato all'immagine rendendola interattiva,

              •  news->fullText per mostrare il testo completo della news.

‍

△ I campi news->summaryText e news->fullText potrebbero essere validati con un codice in html, al posto di un testo semplice.
‍

> Pagina di dettaglio per la movimentazione

Per elaborare la pagina di dettaglio dedicata alla lista dei movimenti eseguiti, con le informazioni relative, è necessario:

          1. Registrare l'anagrafica dei tipi di movimento disponibili per la Card di riferimento.
Effettuare quindi la chiamata all’endpoint GET /customer/movements/kind/{languageid}, inserendo nella query string il codice della lingua d’interesse.

In caso di esito positivo, otterremo come risposta un array di oggetti “movementKind”, ovvero la lista dei tipi di movimenti associati alla categoria della relativa card.

‍

L’oggetto “movementKind” contiene i campi:

              • kind (codice del tipo di movimento),

              • description (descrizione del movimento).

‍

          2. Se sono configurati movimenti liberi, registrare l’anagrafica dei tipi di movimento libero disponibili per la Card di riferimento.
Effettuare quindi la chiamata all’endpoint GET /customer/freemovements.

In caso di esito positivo, otterremo in risposta un array di oggetti “freeMovementData”.

‍

Il recupero di questi oggetti sarà essenziale nella casistica in cui, nel passaggio successivo, ottenessimo un movimento libero (kind=62).
Per ottenere la descrizione di un movimento libero è necessario:

               2.1. Confrontare il campo “freeMovementData->code” degli oggetti “freeMovementData” ottenuti e il campo “movement->freeCode” dell’oggetto “movement” ottenuto nella risposta della chiamata all’endpoint GET /customer/movements/list, descritto successivamente.

               2.2. Rilevare la descrizione del movimento dal campo “freeMovementData->codeDescription” del movimento libero corrispettivo.

‍

          3. Dopo aver registrato i dettagli di tutti i tipi di movimento, effettuare la chiamata all’endpoint GET /customer/movements/list, inserendo nella query string i seguenti parametri:

              • initialdate (inizio dell’intervallo di tempo entro il quale stiamo ricercando i movimenti),

              • finaldate (fine dell’intervallo di tempo entro il quale stiamo ricercando i movimenti),

              • kind (tipo di movimento; se interessa vedere solo i movimenti di un tipo specifico),

              • shopid (codice ID di un negozio; se ci interessa vedere solo i movimenti effettuati in un specifico negozio),

              • netid (codice ID di una rete; se ci interessa vedere solo i movimenti effettuati in una specifica rete),

              • initlimit (dettaglio di paginazione),

              • rowcount (dettaglio di paginazione).

I campi initlimit e rowcount non sono obbligatori e servono in caso di filtraggio dei movimenti.

In caso di esito positivo, otterremo in risposta un array di oggetti json “movement”.

‍
La lista di movimenti sarà ordinata secondo data di attuazione, ovvero dal più recente al più vecchio.

I campi dell’oggetto “movement” che possono interessarci sono:

              • movement->customerName (nome del cliente)

              • movement->id (l’ID del movimento),

              • movement->card (il codice della Card che ha eseguito il movimento),

              • movement->kind (il codice del tipo movimento, utile per rilevare la descrizione dalla lista ottenuta con l'endpoint GET /customer/movements/kind/{languageid}),

              • movement->shop->name (nome del negozio in cui è stato effettuato),

              • movement->chargedPoints (la quantità di punti caricati),

              • movement->dischargedPoints (la quantità di punti scaricati),

              • movement->localTime (la data e ora del movimento).

Queste sono le informazioni principali, ma in base al movimento eseguito, ci possono essere altri campi od oggetti che possono tornare utili.

‍

‍

‍Per maggiori dettagli ed errori esplorare la sezione API Reference.

‍

‍

Profilo personale

‍

Nella pagina del profilo, vengono mostrati i dati anagrafici, i consensi e i contatti registrati dall’utente.

Per ottenere e successivamente poi mostrare tutte le informazioni del cliente è necessario:

          1. Effettuare la chiamata di autenticazione con scope customersynchro tramite l'endpoint POST /auth per ottenere un token di sessione valido.

          2. Effettuare la chiamata all’endpoint GET /customer, senza inserire nessun parametro, ricevendo in risposta un oggetto “customer” da cui registrare e mostrare le informazioni di interesse.

‍

Per effettuare l’update dei dati personali, se il cliente inserisce nuovi dati o modifica i preesistenti, è necessario seguire questi passaggi:

          1. Effettuare la chiamata all’endpoint PUT /customer, inserendo i seguenti parametri:

               • name (nome, inalterato se non modificato o nuovo nome se inserito),

               • surname (cognome inalterato se non modificato o nuovo cognome se inserito),

               • gender (genere inalterato se non modificato o nuovo genere se inserito),

               • birthdate (data di nascita inalterata se non modificata o nuova data di nascita se inserita)

               • usedforpromotions (scelta di interazione inalterata o conforme alle modifiche apportate),

               • ... Possibili altri consensi della campagna da poter gestire,

               • mobilecontactdata (numero di cellulare inalterato se non modificato o nuovo numero se inserito),

               • mailcontactdata (indirizzo email inalterato se non modificato o nuovo indirizzo mail se inserito)

               • ... Possibili altri tipi di contatti e geolocalizzazione legati alla campagna da poter gestire.

‍

> Consensi privacy

‍Per mostrare gli stati attuali dei consensi ed eventualmente modificarli, è necessario:

          1. Effettuare la chiamata di autenticazione con scope customersynchro tramite l'endpoint POST /auth per ottenere un token di sessione valido.

‍

          2. Verificare il valore dei campi relativi ai consensi nell’oggetto “customer” ottenuto in seguito alla chiamata all’endpoint GET /customer.


‍

I campi relativi ai consensi sono:

              • customer->privacy->usedForPromotions,

              • customer->privacy->usedForStatistics,

              • customer->privacy->usedByOthers,

              • customer->privacy->canGetCurrentLocation,

              • customer->privacy->canComunicaVerification.

I primi tre campi sono i consensi relativi all’utilizzo dei dati.

          3. Per aggiornare i consensi, effettuare una chiamata all’endpoint PUT /customer, inserendo i seguenti parametri:

              • name (nome del cliente),

              • surname (cognome del cliente),

              • gender (genere del cliente),

              • birthdate (data di nascita del cliente)

              • usedForPromotions,

              • usedForStatistics,

              • usedByOthers,

              • mobilecontactdata (numero di cellulare inalterato se non modificato o nuovo numero se inserito),

              • mailcontactdata (indirizzo email inalterato se non modificato o nuovo indirizzo mail se inserito)

              • ... Possibili altri tipi di contatti e geolocalizzazione legati alla campagna da poter gestire.

     > Per disabilitare e riabilitare le notifiche push va fatto affidamento direttamente alle API di onesignal. Verificare la loro documentazione.

‍

‍Per maggiori dettagli ed errori esplorare la sezione API Reference.

‍

‍

Store locator

‍

La sezione di API di tipo Customer contiene quattro endpoint differenti che permettono di richiedere i dettagli di negozi secondo diverse esigenze.

Per poter usufruire di questi endpoint, è necessario effettuare la chiamata di autenticazione con scope customersynchro tramite l'endpoint POST /auth per ottenere un token di sessione valido.

‍

> Store by filters

Esegui una ricerca di negozi sfruttando filtri da inserire nella query, tramite l’endpoint GET /customer/shops.

I filtri possibili per la ricerca includono il codice o il nome del negozio oppure della rete interessati, la categoria o le informazioni relative alla geolocalizzazione del dispositivo.

          1. Effettuare la chiamata all’endpoint GET /customer/shops, passando nella query:

              • shopcategory (codice della categoria del negozio | numero),

              • netid (codice della rete | numero),

              • shopgroupid (codice del gruppo del negozio | numero),

              • name (nome del negozio | stringa),

              • companyname (nome della compagnia del negozio | stringa),

              • country (codice del paese | numero),

              • geolevel1 fino a geolevel5 (codici di geolivelli |numero),

              • zip (codice postale del negozio | stringa),

              • taxnumber (codice fiscale del negozio | stringa),

              • enabled (mostrare solo i negozi abilitati | booleano),

              • visible (mostrare solo i negozi visibili | booleano),

              • geolat e geolong(latitudine e longitudine attuale del dispositivo | numero),

              • radiusinmeters (raggio di interesse in metri | numero),

              • initlimit (indice di paginazione | numero),

              • rowcount (indice di paginazione | numero).

‍

In caso di esito positivo, la risposta conterrà un array di oggetti "shops", associato al modello shopDTO, già ordinati per distanza.

I campi degli oggetti “shops” che possono interessarci per mostrare la lista sono:

              • shops->name, per il nome del negozio,

              • shops->distance per la distanza in km,

              • shop->addressPrefix

              • shops->address

              • shops->addressNumber, per l'indirizzo,

              • shops->zip, per il codice postale,

              • shops->telephone, per il numero di telefono,

              • shops->mail, per l'indirizzo email,

              • shops->facebookFanPage, shops->twitterProfile,shops->instagramProfile e shops->youtubeChannel per i vari contatti susocial networks.

Per quanto riguarda invece la composizione della mappa, servono anche i campi:

              • shops->geoLat (latitudine per la geolocalizzazione),

‍              • shops->geoLong(longitudine per la geolocalizzazione).

Per mostrare invece i dettagli, i campi da considerare sono:

              • shops->openingHours,

              • shops->description.

Entrambi i campi possono contenere codice HTML per personalizzare i propri orari e servizi.

‍

> Store by distance

Richiedi la lista di negozi vicini alla posizione attuale del dispositivo attivo tramite l’endpoint GET/customer/shops/bydistance.
E’ importante notare che se non viene consentita la geolocalizzazione da parte del cliente, questo servizio non viene abilitato.

          1. Effettuare la chiamata all’endpoint GET /customer/shops/bydistance, inserendo i parametri:

              • Lat (latitudine del dispositivo che sta eseguendo l’operazione)

              • Long (longitudine del dispositivo che sta eseguendo l’operazione).

‍

In caso di esito positivo, la risposta conterrà un array di oggetti "shops", associato al modello netAndShop, già ordinati per distanza.

I campi degli oggetti “shops” che possono interessarci per mostrare la lista sono:

              • shops->name, per il nome del negozio,

              • shops->distance, per la distanza in km,

              • shop->addressPrefix,

              • shops->address,

              • shops->addressNumber, per l'indirizzo,

              • shops->zip per il cap,

              • shops->geoLevel3Name, per il comune,

              • shops->telephone, per il numero di telefono,

              • shops->mail, per l'indirizzo email.

Per quanto riguarda invece la composizione della mappa, servono anche i campi:

              • shops->geoLat (latitudine per la geolocalizzazione),

              • shops->geoLong (longitudine per la geolocalizzazione).

Per mostrare invece i dettagli, i campi da considerare sono:

              • shops->openingHours,

              • shops->description.

Entrambi i campi possono contenere codice HTML per personalizzare i propri orari e servizi. 

> Store by radius and address

Richiedi la lista di negozi presenti nell’area circoscritta nel raggio da te definito partendo dall’indirizzo che viene inserito, tramite l’endpoint GET/customer/shops/byradiusandaddress.

          1. Effettuare la chiamata all’endpoint GET /customer/shops/byradiusandaddress, passando nella query:

              • geolat e geolong(latitudine e longitudine attuale del dispositivo | numero),

              • radius (raggio dell’area da valutare | numero),

              • visible (mostrare solo i negozi visibili | booleano),

              • initlimit (indice di paginazione | numero),

              • rowcount (indice di paginazione | numero).

‍

In caso di esito positivo, la risposta conterrà un array di oggetti "shops", associato al modello shopDTO, già ordinati per distanza.

I campi degli oggetti “shops” che possono interessarci per mostrare la lista sono:

              • shops->name, per il nome del negozio,

              • shops->distance per la distanza in km,

              • shop->addressPrefix

              • shops->address

              • shops->addressNumber, per l'indirizzo,

              • shops->zip, per il codice postale,

              • shops->telephone, per il numero di telefono,

              • shops->mail, per l'indirizzo email,

              • shops->facebookFanPage, shops->twitterProfile,shops->instagramProfile e shops->youtubeChannel per i vari contatti susocial networks.

Per quanto riguarda invece la composizione della mappa, servono anche i campi:

              • shops->geoLat (latitudine per la geolocalizzazione),

‍              • shops->geoLong (longitudine per la geolocalizzazione).

Per mostrare invece i dettagli, i campi da considerare sono:

              • shops->openingHours,

              • shops->description.

Entrambi i campi possono contenere codice HTML per personalizzare i propri orari e servizi.

‍

> Store by radius and geoposition

Richiedi la lista di negozi presenti nell’area circoscritta nel raggio da te definito partendo dalle coordinate della posizione che viene inserita, tramite l’endpoint GET/customer/shops/byradiusandgeoposition.

‍          1. Effettuare la chiamata all’endpoint GET /customer/shops/byradiusandgeoposition passando nella query:

              • address (nome dell’indirizzo di partenza | stringa),

              • address_number  (numero dell’indirizzo di partenza | numero),

              • city (città dell’indirizzo di partenza | stringa),

              • country (codice del paese dell’indirizzo di partenza |numero),

              • radius (raggio dell’area da valutare | numero),

              • visible (mostrare solo i negozi visibili | booleano),

              • initlimit (indice di paginazione | numero),

              • rowcount (indice di paginazione | numero).

‍

In caso di esito positivo, la risposta conterrà un array di oggetti "shops", associato al modello shopDTO, già ordinati per distanza.

I campi degli oggetti “shops” che possono interessarci per mostrare la lista sono:

              • shops->name, per il nome del negozio,

              • shops->distance per la distanza in km,

              • shop->addressPrefix

              • shops->address

              • shops->addressNumber, per l'indirizzo,

              • shops->zip, per il codice postale,

              • shops->telephone, per il numero di telefono,

              • shops->mail, per l'indirizzo email,

              • shops->facebookFanPage, shops->twitterProfile,shops->instagramProfile e shops->youtubeChannel per i vari contatti susocial networks.

Per quanto riguarda invece la composizione della mappa, servono anche i campi:

              • shops->geoLat (latitudine per la geolocalizzazione),

‍              • shops->geoLong (longitudine per la geolocalizzazione).

Per mostrare invece i dettagli, i campi da considerare sono:

              • shops->openingHours,

              • shops->description.

Entrambi i campi possono contenere codice HTML per personalizzare i propri orari e servizi.

‍‍

‍Per maggiori dettagli ed errori esplorare la sezione API Reference.

‍

‍

Eliminazione Profilo

‍

Per adeguarsi alle attuali normative europee e alle direttive di Apple e Google in fatto di privacy, è stato predisposto l'endpoint DELETE/customer/purge per l'eliminazione completa di tutti i dati del customer interessato.

‍

Per eliminare dunque l'account di un cliente, è necessario:

          1. Effettuare la chiamata di autenticazione con scope customer tramite l'endpoint POST /auth per ottenere un token di sessione valido.

‍

          2. Effettuare una chiamata all'endpoint DELETE/customer/purge inserendo i seguenti parametri

              • customerid (codice id del customer || obbligatorio),

              • card (codice id della card associata al customer || obbligatorio),

              • mobile (numero di cellulare associata al customer),

              • email (indirizzo email associato al customer).

Le informazioni inserire nel body della request sopra descritto sono richieste per un discorso di sicurezza, così da garantire che la richiesta di eliminazione dell'account sia avvenuta dall'applicazione su cui l'area riservata è stata implementata.‍

‍

‍Per maggiori dettagli ed errori esplorare la sezione API Reference.

‍

‍

Recupero Password

‍

Per permettere il recupero della password di un account, ovvero il controllo e il salvataggio di una nuova password, è necessario seguire questi passaggi:

          1. Permettere all’utente interessato a recuperare la propria password di inserire numero di cellulare o email.

‍

          2. Effettuare la chiamata di autenticazione con scope customersynchro tramite l'endpoint POST /auth per ottenere un token di sessione valido.

‍

          3. Eseguire una verifica OTP attraverso il contatto inserito dall’utente. Effettuare quindi una chiamata all’endpoint POST/customer/generaterecoverycode, inserendo i seguenti parametri:

              • email (indirizzo email inserito, se durante la fase 1 è stato richiesto l'indirizzo email),

              • mobile (numero di cellulare inserito, se durante la fase 1 è stato richiesto il numero di cellulare),

              • devicetype (1=Browser, 2=Android device, 3=iOS Device).

‍

          4. Permettere all'utente interessato a recuperare le proprie credenziali di inserire il codice OTP ricevuto e la nuova password.

‍

          5. Effettuare la chiamata all'endpoint PATCH /customer/changepasswordbyrecovery, inserendo i parametri:

              • email (l'indirizzo email inserito, se durante la fase 1 è stato richiesto l'indirizzo email)

              • mobile (il numero di cellulare inserito, se durante la fase 1 è stato richiesto il numero di cellulare),

              • verificationcode (il codice OTP inserito durante la fase 4),

              • newpassword (la nuova password scelta, inserita durante la fase 4).

‍

L'esito della chiamata viene definito dal campo "answerCode" dell'oggetto JSON ottenuto in risposta. In caso di esito positivo, "answerCode" sarà valorizzato a zero.‍

‍

‍‍Per maggiori dettagli ed errori esplorare la sezione API Reference.‍

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.