Reserved area
Viewing the Home
Within the home of your private area you can show:
> the information relating to the card, the points and the loyalty path that the customer is carrying out,
> the news in the foreground,
> the promotions in the foreground,
> the additional services of your brand in the foreground.
> Card
To request all the useful information related to the card, the points and the user's journey, two steps are necessary:
1. Make a call to the endpoint GET /customer, without entering any parameters.
In response, we obtain the customer's personal information, their point balance in the field customer->balance_points And the category of the card held in the field customer->category.
2. Make a call to the endpoint GET /customer/category/ {categoryid}, entering the parameter:
• CategoryID (category id obtained in the previous call).
If the outcome is positive, in response we obtain the “CategoryDTO” object containing the characteristics of the customer's card, including the value of the cash points.
The fields of the 'CategotyDTo' object affected for viewing are:
• CategoryDTO->WeightPointValuePoints,
• CategoryDTO->WeightPointValueMoney,
and together they define the points-to-money ratio available.
Based on these values and the points balance, it is possible to calculate how many points are left until the next objectives and show the path that the user is taking.
> News
To get and show the list of news in the foreground, you need this step:
1. Make a call to the endpoint GET /customer/news passing the following parameters:
• Infocus (value that defines the type of news to receive || 0=all news 1=only news in the foreground 2=only news NOT in the foreground),
•... Possible other values to add to better filter the news to receive.
If the outcome is positive, in response we obtain an array of “news” objects, which will be those visible to the customer, already ordered.
The fields of the “news” object affected for viewing are:
• news->title (news title)
• News->Summary text (short description that will be shown on homescreen)
• News->expiredate (expiration date to check before showing the news)
• News->NewsCategory (array that highlights the news category for possible filtering on the homescreen)
• news->image (URL image of the news).
> Additional Services
To obtain the list of additional services, you need to:
1. Make the call to the endpoint Get/Customer/AvailableServices, entering the parameters:
• Campaignid (the campaign id of your brand related to the production environment | required),
• CategoryID (id of the service category to be inserted only if we want the services of that specific category),
• Initlim and RowCount (parameters for pagination).
If the result is positive, an array of “AdditionalServices” objects is obtained in response.
The fields of the “AdditionalServices” object affected for viewing are:
• AdditionalServices->title (title of service),
• AdditionalServices->Summary (the short description to show on the homescreen),
• AdditionalServices->VisibleFrom and AdditionalServices->visibleTo (range of effective dates of the service to check before showing the service),
• AdditionalServices->Enable (Boolean that describes whether the service is active or not).
> Promotions
To obtain the list of valid promotions for the customer, this step is necessary:
1. Make a call to the endpoint GET /customer/promotionsoftarget, entering the parameter:
• standings (the status of the promotions to receive || 0=Promo starting in thefuture 1=In execution 2=Stopped 3=Ended).
In this case, the status must be set to 1=In execution.
If the outcome is positive, in response we obtain a series of information, including the array of “promotions” objects containing the main data relating to promotions.
The fields of the “promotions” object affected for viewing are:
• Description (name of the promotion),
• Summary Text (short description of the promotion),
• DateTo (end of the promotion),
• URLImage (image of the promotion),
• standings (promotion status).
In addition, for each promo item, there is an array of “prizes” items, which represent the prizes obtained by winning the promotion.
The fields of the “prizes” object affected for viewing are:
• Kind (the type of prize),
• Value (the description of the prize).
For more details and errors explore the API Reference section.
Personal profile
On the profile page, the personal data, consents and contacts registered by the user are shown.
To obtain and then then show all the customer's information, it is necessary:
1. Make the call to the endpoint GET /customer, without entering any parameters, receiving in response a “customer” object from which to record and show the information of interest.
To update personal data, if the customer enters new data or modifies existing data, it is necessary to follow these steps:
1. Make the call to the endpoint PUT /customer, entering the following parameters:
• Name (name, unchanged if not changed or new name if entered),
• Surname (last name unchanged if not changed or new last name if entered),
• gender (gender unchanged if not modified or new gender if inserted),
• Birthdate (date of birth unchanged if not changed or new date of birth if inserted)
• used for promotions (choice of interaction unchanged or in accordance with the changes made),
•... Possible other campaign consents to be able to manage,
• mobilecontactdata (cell phone number unchanged if not changed or new number if entered),
• mailcontactdata (email address unchanged if not modified or new email address if entered)
•... Possible other types of contacts and geolocation related to the campaign that you can manage.
For more details and errors explore the API Reference section.
Detail pages
> Detail page for promotions
To prepare the detail page dedicated to the list of valid promotions, it is necessary to:
1. Make the call to the endpoint GET /customer/promotionsoftarget, entering the parameter:
• standings (0=Promo starting in thefuture 1=In execution 2=Stopped 3=Ended).
To obtain the list of active promotions, validate the status = 1 field and to view an archive instead, validate the status = 3 field.
If the outcome is positive, in response, we obtain, among other information, an array of “promotions” objects containing the main data of each promotion.
The object 'promotions' consists mainly of:
• Description (name of the promotion),
• Summary Text (short description of the promotion),
• FullText (detailed description of the promotion),
• DateTo (end date of the promotion),
• URLImage (URL of the promotion image),
• standings (promotion status),
• [Prizes] (array of “prizes” objects that describe the prizes related to the promotion).
The 'prizes' object consists mainly of:
• Kind (the type of prize),
• Value (the description of the prize).
Kind's list of awards is many, some of the most common awards are:
> kind=3 (prize: points with multiplier, and consequently in the field Value the value by which to multiply the customer's points will be indicated),
> kind 4 (prize: fixed points, and consequently in the field) Value the fixed value of points won will be indicated),
> kind=7 (event: message to appear on the terminal in case of winning),
> kind=9 (prize: a discount coupon in%, and consequently in the field Value the percentage discount value will be indicated),
> kind=10 (prize: a discount coupon in a fixed amount, and consequently in the field Value the amount of the voucher will be indicated),
> kind=11 (event: message to appear on the terminal if a voucher is won),
> kind=37 (event: image to be shown on the terminal in case of winning),
> kind=21 (prize: prize in the catalog, followed by an instant win promotion, and consequently the description of the prize will be indicated in the value field).
Except in the case of an InstantWin type promotion, which allows the option of winning a consolation prize, for each promotion it is possible to define only one type of winning benefit.
> Detail page for the Card
To process the detail page dedicated to the customer's Card information, it is necessary to:
1. Make a call to the endpoint GET /customer (if it hasn't been done before) without entering any parameters.
If the result is positive, we get the “customer” object.
The fields of the “customer” object affected for viewing are:
• customer->name,
• customer->surname,
• customer->balance_points (points balance),
• customer->card (card number),
• Customer->FidelyCode (barcode or fidelycode of the card),
• customer->status (card status, where 1=active, 2=blocked, 3=deleted).
> Detail page for additional services
To process the detail page dedicated to the list of additional services, it is necessary to:
1. Make the call to the endpoint GET /customer/availableservices, entering the parameters:
• Campaignid (required | the campaign id of your brand related to the production environment),
• CategoryID (id of the services category to be inserted only if we want the services of that specific category),
• Initlim and RowCount (parameters for pagination).
If the result is positive, an array of “AdditionalServices” objects is obtained in response.
The “AdditionalServices” object consists of:
• AdditionalServices->categoryID (category of services),
• AdditionalServices->PathImage (url of the service image),
• AdditionalServices->title (title of service),
• AdditionalServices->Summary (the short description to show on the homescreen),
• AdditionalServices->Description (detailed description of the service),
• AdditionalServices->VisibleFrom and AdditionalServices->visibleTo (range of effective dates of the service to check before showing the service),
• AdditionalServices->Enable (Boolean that describes whether the service is active or not).
> Detail page for coupons
To process the detail page dedicated to the list of coupons obtained and available to the customer, it is necessary to:
1. Make the call to the endpoint GET /customer/vouchers, entering the parameters for the pagination:
• initlimit (start of list),
• Rowscount (number of records to display).
If the outcome is positive, in response we obtain various information, including an array of “VoucherList” json objects, which contains all the information related to the voucher, the promotion to which it is associated and the usage details.
To complete the list of available coupons, the fields of the “VoucherList” object concerned are:
• Voucherlist->title,
• VoucherList -> Description,
• Voucherlist->used (which specifies whether the coupon has been used or not),
• VoucherList -> ExpirationDate,
• Voucherlist -> Kind,
• VoucherList->value,
• VoucherList - > netinuseList - > name (in case CanUseVoucherOnlyInnet is validated to true).
> Privacy consents
To show the current states of the consents and possibly modify them, it is necessary to:
1. Check the value of the consent fields in the 'customer' object obtained following the call to the endpoint GET /customer.
The fields related to consents are:
• customer->privacy->usedforpromotions,
• Customer->privacy->usedforStatistics,
• customer->privacy->used by others,
• Customer->privacy->CangetCurrentLocation,
• Customer->Privacy->CAN Communicate Verification.
The first three fields are consents related to the use of data.
2. To update the consents, make a call to the endpoint PUT /customer, entering the following parameters:
• Name (customer name),
• Surname (customer's last name),
• Gender (customer gender),
• Birthdate (customer's date of birth)
• Used for Promotions,
• Used for Statistics,
• Used by Others,
• mobilecontactdata (cell phone number unchanged if not changed or new number if entered),
• mailcontactdata (email address unchanged if not modified or new email address if entered)
•... Possible other types of contacts and geolocation related to the campaign that you can manage.
> To disable and re-enable push notifications, you must rely directly on the onesignal API. Verify their documentation.
Store locator
The Customer API section contains four different endpoints that allow you to request store details based on various needs.
> Store by distance
Obtain the list of stores near the current position of the active device using the endpoin GET /customer/shops/bydistance.
It’s important to note that if the customer does not allow geolocation, this service will not be enabled.
1. Call the endpoint GET /customer/shops/bydistance, providing the following parameters:
- lat (latitude of the device performing the operation),
- long (longitude of the device performing the operation).
If successful, the response will contain an array of "shops" objects, associated with the netAndShop model, already sorted by distance.
The useful fields of “shops” objects for listing are:
- shops->name (store name)
- shops->distance (distance in km)
- shop->addressPrefix
- shops->address
- shops->addressNumber (street address)
- shops->zip (postal code)
- shops->geoLevel3Name (city)
- shops->telephone (phone number)
- shops->mail (email address)
The fields required for map display are:
- shops->geoLat (latitude for geolocation),
- shops->geoLong (longitude for geolocation).
the fields for displaying detailed store info are:
- shops->openingHours,
- shops->description.
Both fields may contain HTML code to customize opening hours and services.
> Store by filters
Search for stores using filters in the query, through the endpoint GET /customer/shops.
Possible search filters include store or network code or name, category, and geolocation data of the device.
- Call the endpoint GET /customer/shops, with the following query parameters:
- shopcategory (store category code | number)
- netid (network code | number)
- shopgroupid (store group code | number)
- name (store name | string)
- companyname (company name | string)
- country (country code | number)
- geolevel1 to geolevel5 (geo-level codes | number)
- zip (postal code | string)
- taxnumber (tax ID | string)
- enabled (only show enabled stores | boolean)
- visible (only show visible stores | boolean)
- geolat and geolong (latitude and longitude | number)
- radiusinmeters (radius of interest in meters | number)
- initlimit (pagination index | number)
- rowcount (pagination index | number)
If successful, the response will contain an array of "shops" objects, associated with the shopDTO model, already sorted by distance.
The fields useful for listing are:
- shops->name
- shops->distance
- shop->addressPrefix
- shops->address
- shops->addressNumber
- shops->zip
- shops->telephone
- shops->mail
- shops->facebookFanPage
- shops->twitterProfile
- shops->instagramProfile
- shops->youtubeChannel
The fields for map display are:
- shops->geoLat
- shops->geoLong
The fields for store details are:
- shops->openingHours
- shops->description.
> Store by radius and address
Request the list of stores within a defined radius starting from an entered address, via the endpoint GET /customer/shops/byradiusandaddress.
- Call the endpoint with these query parameters:
- geolat and geolong (latitude and longitude | number)
- radius (area radius | number)
- visible (only show visible stores | boolean)
- initlimit (pagination index | number)
- rowcount (pagination index | number)
If successful, the response will contain an array of "shops" objects, associated with the shopDTO model, already sorted by distance.
Same listing, mapping, and detail fields apply as in the previous method.
> Store by radius and geoposition
Request the list of stores within a defined radius based on address coordinates, using the endpoint GET /customer/shops/byradiusandgeoposition.
- Call the endpoint with these query parameters:
- address (starting address | string)
- address_number (starting address number | number)
- city (starting city | string)
- country (country code | number)
- radius (area radius | number)
- visible (only show visible stores | boolean)
- initlimit (pagination index | number)
- rowcount (pagination index | number)
If successful, the response will contain an array of "shops" objects, associated with the shopDTO model, already sorted by distance.
Same listing, mapping, and detail fields apply as in the previous methods.
For more details and errors explore the API Reference section.