Onboarding area riservata - Customer API
To execute the log in of registered customer, follow the flow:
1. Logging in.
To execute the sign in of a new customer, follow the flows:
1. Signing in,
2. New user,
3. Data entry.
To execute the sign in of a not registered customer that already has a card, follow the flows:
1. Signing in,
2. User with card,
3. if necessary, Data entry.
Logging in
If the user intends to access his private area, these are the steps to follow:
1. Make the authentication call for customer access through the endpoint POST /auth to obtain a valid session token.
The response, if successful, will return the token and a “customer” json object with the information of the referring customer.
2. Verify that in the “customer” object, all the mandatory data for your campaign are filled in.
If there is no data, it means that the customer aborted the registration before the end of the procedure and it is necessary to redirect him to an error page.
If successful, however, the customer has completed the login.
Signing in
If the user interacts with the “Register” button, these are the steps to follow:
1. Ask the user for a value to enter for 'mobile number' or 'email' and register it.
2. Make the authentication call for customersynchro access through the endpoint POST /auth to obtain a valid session token.
3. Check if the customer already exists, that is, if they already have a card, and if they have completed the personal data.
To get this information, make a call through the endpoint GET /customer/checkcard inserting in addition to the entered token the fields:
• card (to be entered if the value requested and entered during registration is the code of the owned card),
• email (to be entered if the value requested and entered during registration is an email address),
• mobile (to be entered if the value requested and entered during registration is a mobile number).
The possible response cases are:
> If the result returned with status 402 and 53 on 'AnswerCode', the customer is a new user and must register it following the 'New User' flow;
> If the result returned with status 200, the customer has a card but the “registered_customer” field is false, register the obtained “customerid” field and follow the “User with card” flow;
> The result returned with status 200 and the “registered_customer” field is true, the user is already registered, so you have to return to the login page following the “Sign In” flow;
> The result returned with a different status from the previous ones, so report an error and return to the home page.
To see more technical details and errors, explore the API Reference section.
New user
To register a new user, the steps to follow are:
1. Allow the user to enter the new password and register it.
2. If it hasn't already been validated, make the authentication call for customersynchro access through the endpoint POST /auth to obtain a valid session token.
3. Send a validation code for OTP verification when the customer clicks on the reference icon.
Then make a call through the endpoint POST /customer/verifyemail by entering the following parameters:
• campaignid (the campaign id of your brand related to the production environment),
• emails (to be inserted if the value requested and entered during the “Register” flow is an email address),
• mobile (to be entered if the value requested and entered during the “Register” flow is a telephone number),
• devicetype (type of device from which the customer tries to log in 1=Browser 2=Android device 3=iOS Device).
If the result is positive, then it has http 200 status, continue. Otherwise, report that the sending of the OTP code was not successful and stay on this page.
4. Sent the code, make a call through the endpoint put/customer/registrationVCWithVerificationCode to verify the OTP (verification code), and, if appropriate, register the user directly, entering the following parameters:
• verificationcode (OTP code obtained),
• passwords (the password entered earlier),
• devicetype (1=Browser, 2=Android Device, 3=iOS Device),
• campaignid (the campaign id of your brand related to the production environment),
• categoryID (the id of the virtual card category to be activated),
• username (the value entered on the 'Register' page whether it is a mobile number or email),
• mailcontactdata (to be inserted if the value entered on the “Register” page is an email address),
• mobilecontactdata (to be entered if the value entered on the 'Register' page is a mobile phone number).
If the outcome is positive (http status 200), the user has been created and we have obtained in response the account info including the associated card number. Continue on the 'Data Insertion' flow.
In case of an error, show the error and stay on the page, otherwise go to the next page.
User with card
To register a new user who already has a card, the steps to follow are:
1. Allow the user to enter the new password and register it.
2. If it hasn't already been validated, make the authentication call for customersynchro access through the endpoint POST /auth to obtain a valid session token.
3. Send a validation code for OTP verification when the customer clicks on the reference icon.
Then make a call through the endpoint POST /customer/generateverificationcode by entering the following parameters:
• customerid (the customer id obtained during the “Register” flow),
• emails (to be inserted if the value requested and entered during the “Register” flow is an email address),
• mobile (to be entered if the value requested and entered during the “Register” flow is a telephone number),
• devicetype (type of device from which the customer tries to log in 1=Browser 2=Android device 3=iOS Device).
If the result is positive, then it has http 200 status, continue. Otherwise, report that the sending of the OTP code was not successful and stay on this page.
4. Once the code has been sent, verify the OTP (verification code), and, if appropriate, change the user's credentials.
To do this, make a call through the endpoint put/customer/changeUAPByVerificationCode, entering the following parameters:
• customerid (the customer id obtained during the “Register” flow),
• username (the value entered on the 'Register' page whether it is a mobile number or email),
• passwords (the password entered earlier),
• verificationcode (OTP code obtained).
If the outcome is positive (http status 200), the user has been created and we have obtained in response the account info including the associated card number.
Then we can continue on the 'Data Insertion' flow.
In case of an error, show the error that occurred and stay on the page, otherwise go to the next page.
To see more technical details and errors, explore the API Reference section.
Data entry
The account has been created and we have obtained the username (the mobile number) and the user's password.
To request the entry of the new user's personal data, the steps to follow are:
1. Make the authentication call for customer access through the endpoint POST /auth to obtain a valid session token, with the username and password obtained.
If the result is negative, return to the error page and contact support.
2. Get the list of fields (personal data) to fill in by making a call through the endpoint GET /customer/customerdatafields/ {campaignid} inserting the parameter:
• campaignid (your brand's campaign id related to the production environment).
In response, we get the list of fixed fields on the platform. There are two objects: 'CustomDataFields', containing the list of customer personal data, and 'PrivacyCustomDataFields', containing the list of privacy permissions.
For each field within these objects, visibility (so if it is necessary to show it during compilation) and the mandatory nature of the field are specified, through two Booleans.
3. Make a call through the endpoint GET /customer, inserting no parameters.
In response, we obtain all the customer data that has already been registered, allowing us to pre-fill the data of the proposed form with the data collected from the call.
Through this call, we also obtain the 'card' field (card number) and the 'FidelyCode' field (relative barcode).
4. Show the fields received and wait for the entry, checking for mandatory fields and other possible errors.
5. At the end of entering the data by the customer, it is necessary to update the fields on the customer's personal data.
For this, make a call through the endpoint PUT /customer, entering the following parameters:
• name (name entered, if required),
• surname (last name entered, if required),
• gender (gender inserted, if required),
• birthdate (date of birth entered, if required),
• usedforpromotions (choice of interaction with consent required (true or false),
•... Possible other consents to be set if required by the campaign,
• mobilecontactdata (mobile number registered for the user),
• mailcontactdata (registered email address for the user),
•... Possible other types of contacts and geolocation to be set if required by the campaign.
To see more technical details and errors, explore the API Reference section.