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