Area riservata - Customer API
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.