App feed API Unified v3 - Liquid Barcodeskb.liquidbarcodes.com/wp-content/uploads/2018/05/...May 16,...

App feed API Unified v3

LIQUID Barcodes Application Feed Interface JSON/REST

LIQUID Barcodes AS (tm)

Version 3.0.4May 2018

LIQUID Barcodes Application Feed Interface JSON/REST

General Disclaimer

Background

Nomenclature

API description

General principles

Security

Preferred API format and HTTP Headers

Registration and User Management

Deterministic PIN

Common models

The Consent model

The Consent situation model

The User model

POST /initialize

POST /pin

POST /user

PUT /user

GET /user

GET /languages

Content Management services

The Content model

Content types that require special handling

Content organization

Content images and device caching

How to build the content image

GET /content

POST /share

Ratings

GET /ratings/categories

POST /rating

GET /ratings/statistics

GET /ratings/statistics/store

Stores management

GET /stores

GET /storetagids (Store Tags)

Recruitment

GET /validreferral (Valid Referral)

POST /referral

Push notification support

Registering the device with Liquid Barcodes

POST /device

Receipts handling

GET /receipts

POST /forwardreceipts (Forward Receipts) (NOT IMPLEMENTED)

Coupon shop

Service definitions

Shop offer model

GET /shopoffers

GET /shopcategories

POST /ProcessShopBasket

GET /ShopTransactionStatus

Code management

POST /code/usage

Request

Response

List of errors

General Disclaimer

This document describes the interface to get the relevant content (coupons, games, survey etc) for a unique user and application. In order toutilize this interface there must be a commercial agreement with LIQUID Barcodes in place. In all circumstances the IPR of the interface resideswith LIQUID Barcodes. LIQUID Barcodes reserves the right to change this interface at any moment. Any implementation that utilizes this interfaceis the sole responsibility of the implementer, and under no circumstances should the issuing of this document be construed to signify that LIQUIDBarcodes will participate with the implementation, testing, verification of the implementation, unless otherwise agreed.

Background

This document describes the application interface to register a user, request the user's coupons, loyalty cards, promotions, rewards, surveys andgames. The document is organized in sections to describe functionality classes, and not every functionality class may be relevant for every mobileapplication. They are however included to detail the fully fledged functionality, but may not be present in the actual implementation for thisparticular purposes. The full functionality of the practical implementation has to be agreed with LIQUID Barcodes before using the servicesprovided.

Nomenclature

A is a ticket or document that can be exchanged for a financial discount or rebate when purchasing a product. A coupon can take manycouponforms, but for the purposes of this document a coupon is a graphical representation of a discount/rebate with the appropriate conditions. Anycondition of the coupon is embedded in the coupon itself. A coupon can be either unique or non-unique

A is a special type of coupon that promotes loyal behavior of the customer by rewarding coupons to the customer in exchange forloyalty cardrepeated purchases of the loyalty product. A loyalty card is always unique to each individual user.

A is special in that it is triggered by the repeated purchases using the appropriate loyalty card. An example would be a couponreward couponfor free coffee, at the point where the consumer has purchased 4 coffees using their loyalty card. A loyalty card is always unique to eachindividual user.

An is special in that it details a general offer, but without any barcode for validation. The image would as such describe a generalimage couponoffer, and is used as a general board to communicate information inside the application

A is a coupon offer that is either limited by time or by the total number of times the coupon can be redeemed across all recipientslimited couponof the coupon. This coupon is used to create a sense of urgency, and appeal to the competitive nature of some consumers. The coupon caneither be limited in the total amount of coupons that can be validated inside the campaign or limited in time (typically very short time periods)

HTML based content is some content that is displayed in the in-app web browser . Examples for this type are both surveys and games.

API description

General principles

Security

The Application ID and the security details are available on request. This API relies on the use of SHA-2 256 hash signatures with all mandatoryparameters + a secret salt known only by LIQUID and the customer (you).

Example (pseudo) service call:

1.

2.

3.

4.

{ "DateTimeHeader": "2014-03-07T11:07:21+01:00" "parameter_a": "abcd", "parameter_b": "1234", "signature": "1aaade12efceba0f9ddda4a94bce59a6"}

Lets say we have agreed upon the secret salt "wild-e-coupon". Then, the source for the checksum would be "abcd" + "1234" + "wild-e-coupon".The correct checksum would be:

SHA-2 256("2014-03-07T11:07:21+01:00abcd1234wild-e-coupon")= 800226d761b1bfe2248f68a353f73e720ab9322408dff29f50ed2dba223432e2

Each service specification below will detail how to build the source for the checksum, that is, which parameters and the order in which they shouldbe concatenated.

Preferred API format and HTTP Headers

The preferred content type for the requests that are being sent to LIQUID is JSON. For function call the following parameters are alwayseveryplaced in the HTTP header:

X-Liquid-Timestamp – datetime in ISO-8601 format. e.g. 2014-03-06T13:11:04+03:00. Time should be in UTCX-Liquid-Signature - signature calculated in the manner described above

Registration and User Management

Registration in some form is mandatory for all users of this API, as all coupons are personal and unique. The application identifies itself/the user ina two stage process, which is normally only carried out once. However the LIQUID services has the ability to force a re-registration either explicitly(hard) or implicitly (silent). The high-level registration process is as follows:

POST /initialize. The application identifies itself with a unique and persistent ID. As a response it is given a temporary UserId from the system that it is touse in all future function calls to this APIPOST /pinThe application calls this API again with a unique user identificator (normally phone number, but it may also be e-mail or in the responseto this function call) together with the temporary UserID. The user is then sent a PIN on SMS (or e-mail if that is preferred)POST /userThe application calls this API with the unique temporary UserID and the received PIN code. In addition additional information about theuser may be added. Upon verification from the system that the UserID and PIN matches, the application gets a final UserID. The finalUserID is either the same as the temporary UserID (user has never registered before) or a new UserID (in the case where the user haspreviously registered). The function returns the processed user model (see ).User modelPUT /UserIf some mandatory user information is required for the application, and this was not provided with the POST /user call this should beupdated to complete the registration process.

It is important to note that several application instance can share the same UserID, if a particular user installs and register the application onseveral phones (as long as he has access to the phone that gets the PIN)

Deterministic PIN

In the case where the client of our API already has a unique and persistence ID for each individual user, the API supports a mechanism where theregistration can be done silently to the end user. In this case the system will return a PIN with the POST /pin call that can be used directly withoutuser interaction. It is important that the and not by the mobile application itself. registration then is done through the caller's back end This modealso means that it is the caller's responsibility to handle all consents and management of the user's data, and for ensuring user identityuniqueness and persistence.

Common models

These primary models are used by multiple services and

The Consent model

The fields that make up a specific consent revision. It is used by the Consent situation mode below, which is in turn used by the appfeed services.

Field Description

Id The consent Id is an immutable ID for the version, any change in the consent text would mean a new ConsentId (even ifthe change is so minor that the ConsentVersion hasn't changed)

Title Localized / descriptive name.

Version This is a human readable consent version number of the latest valid consent

Description The exact consent text that the user is consenting too.

PrivacyPolicy Optional: The privacy policy text for the current consent version for the entire service

DefaultState Boolean flag. If true it means this consent can be checked as approved when presenting it to the user for the first time.

RevokeWarningText Optional: A text that must be shown to the user when trying to revoke this consent.

MinimumAge Optional: The minimum age of user to use this app. Given as a number of years

MinimumAgeText Optional: The text that is provided to indicate 'This app requires that you are X years or older'. This text must be shownto the user and she must either set a toggle to True or confirm by setting their birthdate. If the user did not confirm hisage then this consent cannot be confirmed

The Consent situation model

This model describes the current situation for all relevant consents, including what the user has approved and what he needs to approve.

Parameter Description

Name A value to indicate the consent type. The following values are defined for all applications: 'Master', 'Location', 'Pushnotification'

State The current state of this consent name for this user. It can take the following values

'NoConsent' - No consent has every been given for this consent name

'ConsentGiven' - The user has given his consent for the ConsentId/Version details in LastApproved

'ConsentRevoked' - The user has given but since revoked his consent

'ConsentRenewalRequired' - The user has given his consent for the ConsentId/Version details in LastApproved, but a renewalof the consent is required to use this part of the service

Mandatory If true the user must consent to or renew this consent for the app to work, if the user hasn't already given his consent. If theuser wants to revoke a mandatory consent, this will mean that the user opts out of the entire service. If false, this particularconsent is not required for the service to work

LastApproved Consent object (see ). The last revision the user has approved (may be revoked) of this consent name. If theConsent modeluser has never approved this will be null / not present.

CurrentVersion Consent object (see ). The current / latest revision of this consent.Consent model

ChangeLog Optional: Array of change log from the last approved consent version to the current version

Id The exact consent version as an Id

Version The consent version in a human readable form

Text A textual description of the changes that was introduced with this particular version from the previous ConsentId

The User model


UserId For new users the UserId will match the UserId from the request.

For returning users the UserId will be the UserId previously associated with the MSN.

Msn Users mobile number.

Name Optional: Name of user

Address Optional: Address of user.

PostCode Optional: User's zip code

City Optional: User's city of residence

Email Optional: User's preferred e-mail

DateOfBirth User's date of birth in ISO-8601 format (yyyy-mm-dd).Optional:

Gender User's gender specified as M or F.Optional:

PreferredStores Optional: List of user's preferred store(s) . lbased on their interaction with the system This is a JSON array of storesisted in most preferred store first. Must use the same as available in Stores section of this document. A storeStoreIdcan be present in both PreferredStores (set by the system) and SelectedPreferredStore (selected by the user)

SelectedPreferredStores List of user's preferred store(s). This is a JSON array of stores listed in most preferred store first.Optional: selectedMust use the same as available in Stores section of this document. A store can be present in bothStoreIdPreferredStores (set by the system) and SelectedPreferredStore (selected by the user)

UserGroups Optional: Array of userGroups for this user

GroupId A unique identifier for this group

GroupDescription A human readable description to be displayed to the user

IsUserMember Only accepted values are 'True' or 'False', meaning that the user is part of the group or not partof the group, respectively

UserConfigurable Takes one of the following values:'NotConfigurable' - The user cannot toggle membership him/herself

'Configurable' - The user is allowed to change the group membership status him/herself

'CodeConfigurable' - The user is allowed to change the group membership status him/herselfbut it requires an additional code to be entered by the user in the app

Additional values may be added in the future, and unrecognized values should default to'NotConfigurable'

Culture Optional: Indicates the users culture / language. Must be one of the values from the service. Values/languages follow RFC 4646.

Consents Array of consents (see ) that is appllicable for this user to use this application. AnyConsent situation modelMandatory consents must be displayed and approved by the user before POST /user call. If using 'DeterministicPIN' the consent handling is the responsibility of the calling party and this section will be empty.

UserMyPage Link to HTML page with advanced settings (including historic data for the user)

POST /initialize

This is the first service to be called for a uninitialized app instance. This function call is normally only done initially, or when the user has loggedout. The service expects the following parameters in the body of the request:


DeviceId A unique identifier for the device that as far as possible is persistent when the user logs in after having a) logged out, b)deleted and re-installed the app, and c) done a factory reset (if possible). This identifier is used to prevent fraud by settinglimitations on the number of times a user can use the same device with different MSNs.

Customers using the " " feature should instead their external user-reference in this field (unique andDeterministic PIN provide persistent for a given user).

Culture Optional: Indicates the users culture / language. Only values present in the service are accepted. Values follow/languages RFC 4646. This feature is only used if your app supports more than 1 language

The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + DeviceId+ Your secret salt

The service replies with HTTP-200 status when the operation was successful, the body of the response will contain:


UserId A randomly created user ID. The app should store this UserId for use with the following service calls.

Consents Array of consents (see ) that is appllicable for this user to use this application. Any Mandatory consentsConsent situation modelmust be displayed and approved by the user before POST /user call. If using 'Deterministic PIN' the consent handling is theresponsibility of the calling party and this section will be empty.

POST /pin

Before a user can be registered he must order a PIN to his mobile number to confirm he is the owner of that mobile number. The users PIN mustthen be used as with the POST /user service to register a new user.

The service expects the following parameters in the body of the request:


UserId UserId, a unique ID for the given User that is assigned by LIQUID.

Msn Mobile number where the PIN will be sent. (Optional parameter if using Deterministic PIN mode)

The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + + Your secret saltUserID + MSN



Status

Value Description Message suggestion

SmsSent A new SMS has been sent Engangspassord er sendt til deg på SMS

PinOnItsWay SMS has not been sent; 3 SMS messages has alreadybeen sent to the user before

Kunne ikke sende engangspassord til oppgittnummer, prøv igjen litt senere

PinToUse The PIN code to use is included in this response. This isonly relevant for a deterministic pin

Pin Optional: The PIN code to use for the POST /user call. This is only relevant for a deterministic pin

POST /user

Registers a new user profile and returns the users UserId. In case of returning users that needed to re-register, their previously UserId will bereturned. The mobile app must then replace it's UserId.




Pin Users PIN code (see POST /pin).

Msn Optional: The MSN of the user (only allowed to set MSN when using deterministic PIN)


Address Optional: Address of user



Emails Optional: List of user's preferred e-mails

DateOfBirth Users date of birth in ISO-8601 format (yyyy-mm-dd).Optional:

Gender Optional: User's gender specified as M or F.

SelectedPreferredStores List of the user's selected preferred store(s). This is a JSON array of stores listed in most preferred storeOptional: first. Must use the same StoreId as available in Stores section of this document

Culture Optional: Indicates the users culture / language. Must be one of the values from the service. Values/languages follow RFC 4646.

ApprovedConsents A list of approved consent IDs.

RevokedConsents A list of revoked consent IDs. (Note: first we will revoke any sent consents and then only add any approved)

The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + UserID + PIN + Your secret salt

The service replies with HTTP-200 status when the operation was successful, the body of the response will be the current user model (see User).model

PUT /user

Updates a users profile data.




Msn Optional: The MSN of the user (only allowed to change MSN when using deterministic PIN)


Address Optional: Address of user



Emails List of user's preferred e-mailOptional:

DateOfBirth Users date of birth in ISO-8601 format (yyyy-mm-dd).Optional:

Gender User's gender specified as M or F.Optional:

SelectedPreferredStores List of user's preferred store(s). This is a JSON array of stores listed in most preferred storeOptional: selectedfirst. Must use the same StoreId as available in Stores section of this document. A store can be present in bothPreferredStores (set by the system) and SelectedPreferredStore (selected by the user)

UserGroups Optional: Array of userGroups that is applicable to this user

GroupId A single word tag for this group. Only tags that have been fetched through Get/User is accepted

IsUserMember Only accepted values are 'True' or 'False', meaning that the user is to join/is joinedor is to quit/has quit the group in question

UserCode Provides a needed code to verify the change of status if UserConfigurable ='CodeConfigurable'. Blank otherwise

Culture Optional: Indicates the users culture / language. Must be one of the values from the service./languages Values follow RFC 4646.

ApprovedConsents A list of approved consent IDs.

RevokedConsents A list of revoked consent IDs. (Note: first we will revoke any send consents and then only add an approved)

The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + UserID + Your secret salt

The service replies with HTTP-200 status when the operation was successful, the body of the response will be the current user model (see User). A change of status on the UserGroup must be fetched through Get /User model

GET /user

Gets a user profile. Expects the following parameters in the URL query-string.


UserID UserId, a unique ID for the given User that is assigned by LIQUID.


The service replies with HTTP-200 status when the operation was successful, the body of the response will be the current user model (see User).model

GET /languages

Lists the possible languages / cultures the user can select in this app. The service has no arguments but the standard headers.

The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + your secret salt.

The response will be a dictionary with culture key and language name, for example:

Key Value

nb_NO Norwegian bokmål

nn_NO Norwegian nynorsk

This means nb_NO and nn_NO are the valid alternatives to send in the service's field./user Culture

Content Management services

This section describes the different ways of getting access to the coupons, loyalty cards, rewards, games, surveys etc... Essential for all functionsin this section is that they return a collection of content objects as described below:

The Content model

The content object is used in a several places and has two different states:

Activated, this means that the content has already been issued either by a user action or because the underlying campaign automaticallyissues the content to the userNot yet activated, is currently not implemented

Parameter Description Activatedcontent

Not yetactivatedcontent (notimplemented)

ScheduleId LIQUID Barcodes' internal Schedule identifier. Mandatory Mandatory

ContentId LIQUID Barcodes unique content identifier. Mandatory

TopImageUrl Optional: URL to the top image part of the content. Either TopImageUrl or ContentUrl has to bepresent

Optional Optional

TopText Top text for the coupon which can be 1-3 lines of text. The most common use of thisOptional:parameter is the text "Valid to ...", but it can have other information as well. This is used if the the appbuilds the complete coupon itself, otherwise this is optional

Optional

BarcodeUrl Url to the barcode proper. This will have a small white border around it. Optional: Optional

BottomText Optional: Bottom text for the coupon. Optional

BottomImageUrl URL to a bottom image of a coupon.Optional: Optional

BackUrl If present this points to an image to present on the back side of the content. Optional Optional

ThumbUrl If present this points to an smaller representation of the content to be used in an overview display Optional Optional

ContentUrl If content is a HTML based content, this URL is to be opened in the in-app browser. Either TopImageUrlor ContentUrl has to be present

Optional

BackgroundColour If present this represents a background colour to use with this coupon. The background colour isrepresented in #AABBCC notation

Optional Optional

Type Content type.

CouponHTML (this is a link to an HTML page)

If the app feed returns an unknown or unrecognized app type the application should default back on theCoupon type

Mandatory Mandatory

Description The content description. Optional Optional

SubText Optional: A short text to present with the content image. Optional

AmountLeft Optional: If this content has a limited amount of validations, the remaining count is given here. A valueof 0 means that no further validations will be possible. If this parameter is not in use the value is empty

Optional Optional

ExpiryDate The time/date after which the coupon will be expired. The expiration date/time is given in UTC Mandatory Optional

RatingCategory Optional: The rating category to use. Optional Optional

Id The Id of the Rating category Optional Optional

Name The name of the Rating category (e.g. COFFEE) Optional Optional

ShareType Can take the values ''NotSharable', 'Shareable' or 'ShareAndCare'. If not present then content is notshareable

Optional Optional

ValidForStore Optional: If the content can only be used in particular store, this field has the StoreId value of thisonestore

Optional

ValidForStoreTags Optional: A list of all the storeTagIDs where this content can be used. The StoreTags can be resolved toa list of stores. It is up to the app to decide how to display this to the consumer

Optional Optional

GiftCardBalance Optional: Balance of the gift card Optional

Activated If true the coupon is already issued/activated. If false only a subset of the coupon object will be returned,and the content must be activated before they can be used

True False

All images in the coupons will have Last-Modified and E-Tag HTTP-headers to indicate if the image has been updated or not. It is recommendedusing this check instead of the version number.

Content types that require special handling

Most coupon types are simply displayed in the same manner, with all of them having a coupon image, a back image and the thumb sizedrepresentation of the coupon. The following coupon types contain information that should be displayed in addition to/instead of:

HTML, always has the contentURL that needs to be opened in the in-app browser. If for some reason it is not possible to open in the. If the TopContentUrl is also present it should be displayed and whenin-app browser the content should be opened in the device browser

When activated (pressed on) the overlay URL should be loaded in a in-app browser window that takes focus. The user can then finish thesurvey/HTML page and will once finished there will be a HTML button to close the HTML window. The app should provide a separatemechanism to allow the user to close the browser window and allow the user to return to the app independent of the HTML content.

Content organization

The coupons provided by Liquid Barcodes are organized in sections. When setting up a campaign the retailer will define which section the contentshould be assigned to. All content types can appear in all sections, provided that the app supports this. From the app perspective each of thesesections should be mapped to one app view. However the content in each section should be kept together in the order specified by the section.

Content images and device caching

All image URLs that is returned contains the form . Whenever an image changes thehttps://www.domain.com/path/filename.extension?v=guidURL will also change (possibly the filename, but always the GUID). Thus an image change will result in a new and unique URL. Any device/app

In order to improve the user experience, it is suggestedcaching mechanisms used must miss and load the image for such new and unique URLs.to have a graceful offline caching.

How to build the content image

The coupon image can be built with the following five elements:

TopImageUrlTopTextBarcodeUrlBottomTextBottomImageUrl (Often not present)

You are required to use all 5 elements to depict the content for each element that is present. The content image must be built the following way:

Addtional some content may have a sub-text. This should be placed below the 5 content elements

GET /content

Gets an overview of all the coupons assigned to a user. This call is primarily used to get an overview of the coupons available to check forchanges that have occurred since last time the app was used.

The service expects the following parameters as part of the URL query-string.



SectionIds If desirable to only get the content for one or more sections, it can be specified as an array of sectionIds. If not presentOptional:or empty the response will contain all the available sections



https://www.domain.com/path/filename.

1. 2.

3.


Sections Array of sections

Id The Id of the section

Name The name of the section

Content Array of content objects (see ) that is placed in this sectionContent model

POST /share

Shares some content with the user's friend. This function call should only be used if the content has been assigned as shareable (see contentmodel's ).ShareType

The service expects the following parameters as part of the URL.



ScheduleId LIQUID Barcodes' internal Schedule identifier.

ContentId The Id of the content to share.

FriendUserRef The unique user reference to the friend that the user wants to give the coupon to. Normally this is the phone number of thefriend (MSN).

The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + UserID + ContentId + Your secret salt



ResultCode The result of the operation. The following values are supported

Code Description

SharedOnSms The content has already been shared directly to the friend through SMS

SharedByApp The content has already been shared to the friend's app

ShareByUrl The content has to be shared from the user's mobile phone. The 'Message' parameter contains whatneeds to be shared

CouldNotShare The content couldn't be shared to the proposed end user.

ResultMessage A human readable text of the result

Message Optional: The default text to use when the content to be shared should be sent through the user's phone (SMS or someother means). The typical use case is when the recipient has not given consent to the retailer

Ratings

When certain conditions are met the user is given a possibility to rate into a rating category (typically the category is a type of product). Typicallyafter the user has tried a particular product. The user is given a pending rating and 2 hours to complete that.The sequence of calls is:

The app gets the users rating status from GET /ratings/categories .All rating categories are always included and can be presented (whether they have pending ratings or not). Various counters that arerelevant to present for the category is explained below.If a category has set, it means that the user may complete that rating by submitting to .PendingRating POST /rating

GET /ratings/categories

Returns all rating categories. Per category also includes the first of any any pending ratings.

The following parameters are expected in the URL query-string:



CategoryId ID of the rating category to get. If not set, rating categories with pending ratings will be returned.Optional: all

The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + UserID + CategoryId + Your secret salt

Upon a successful request the service returns a 200 OK with the following parameters


Categories One object per rating category.

Id Category ID

Name Category name

RatingsSinceReward Number of ratings the user has submitted since last rewarded.

RatingsUntilReward Number of remaining ratings before the next reward.

RatingsPending Number of currently pending ratings. A value of 1 means that only 1 pending rating is available (this one).

PendingRating If any pending ratings are found for this category, the first (oldest) pending rating is returned here.Optional:

RatingId The ID of the rating.

TimeToLive Time before the rating expires. If value is in the past, it is not possible to rate the product. The time is given in UTC.

Store Details of the store where the pending rating was created / where the product was bought.

Id The ID of the store where the product was bought/redeemed.

Name The name of the store where the product was bought/redeemed.

POST /rating

Submits a user rating for a given rating

The following parameters are expected in the body of the request.



RatingId The ID of the pending rating. This idea is only available through the previous function call GET /RatingState/

Rating The rating of the product. Any integer value.

The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + UserID + RatingId + Rating + Your secret salt



Bonus TRUE a reward was given, FALSE otherwise.

Backlog Number of pending ratings that can still be submitted.

GET /ratings/statistics

Gets the statistics for all stores.



CategoryId The ID of the category to get the statistics for

The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + CategoryId + Your secret salt



Array of all stores

StoreId The ID of the store where the product was bought/redeemed.

StoreName The name of the store where the product was bought/redeemed.

Av2MonthRating The average rating for the store going back 2 months.

Tot2MonthRatings The number of ratings for the store going back 2 months.

AvRating The average/current rating of the store all time.

TotRatings The total number of ratings for this store all time.

GET /ratings/statistics/store

Gets the stats for one specific store.




CategoryId Refers to a product category.

The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + StoreId + CategoryId + Your secret salt




StoreName The name of the store where the product was bought/redeemed.

Av2MonthRating The average rating for the store going back 2 months.

Tot2MonthRatings The number of ratings for the store going back 2 months.

AvRating The average/current rating of the store all time.

TotRatings The total number of ratings for this store all time.

WeekRatings Array of 9 data points of (week no, average rating) presented in oldest first. The 9th data point is the current week.

Stores management

This section of the API allows the app to get the full list of stores from the LIQUID system. Note that only active stores will be available meaningstores that are not closed down for maintenance/refurbishment, closed permanently etc. It is recommended to download the stores list on aregular interval (say 24 hours) and cache it locally, as the store list can be significant amount of data, in addition to it by nature being fairly static.

GET /stores

No parameters are expected in the calling function. The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + Yoursecret salt

Upon a successful request the service returns a 200 OK with the following parameters (if available)


Stores List of stores, each object containing:

1.

2. a.

3.

Id LIQUID internal ID.

ExternalId External (customer's) ID.

Name Name.

ShortName Short name.

Address Address.

Telephone Phone number.

Latitude Geolocation, latitude.

Longitude Geolocation, longitude.

CurrentState The current state of the store. Permitted values are:

Open. The store is open for businessClosed. The store is not open for businessTemporarilyClosed. The store is not open for business but will open again in the futurePermanentlyClosed. The store is no longer operational

TagIds Contains a comma separated list of TagIds that are used to group stores

Logo Optional: URL to store logo (if the store uses a different logo from the company logo)

Metadata Contains a comma separated list of key:value pairs related to this particular store. Any keys that the app is unaware ofshould be ignored

OpeningHours Optional: Array of opening hours, one entry for each way of the week from Monday to Sunday.Each entry takes the format "H1:M1-H2:M2" where H1/M1 are opening time hours/minutes and H2/M2 are closing timehours/minutes.For example: "09:00-18:00"

Note Store defined text to signify some special announcements, e.g. 'Closed on Monday due to public holidays'

GET /storetagids (Store Tags)

No parameters are expected in the calling function. The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + Yoursecret salt



StoreTags List of store tags, each object containing:

Id The ID of the tag/region.

Title The full name of the tag/region.

StoreIds An array of IDs of all stores that belong to this tag/region.

As with the store list, it is recommended to download this list of StoreTags on a regular basis and cache it locally.

Recruitment

The sequence is as follows:

App user clicks "Recruit a friend" in his app, and fills in which MSN to recruit. The app calls to check if the MSN is already registered.GET /ValidReferral/...

If already registered the app user is told the MSN he entered cannot be recruited.And the sequence stops here...

The app presents the devices Send-SMS interface with the MSN and message prefilled.

3.

4.

5.

The message text should be set from the SMS template returned in step 2.

When the message has been sent, the app immediately calls to activate the referral.POST /Referral If the recruited MSN is then registered, within a certain time window, it will trigger a reward to the recruiter and/or the recruited.

GET /validreferral (Valid Referral)Checks whether the referral user is already a member or is eligible for referral.The following parameteres are expected in the URL query-string:



MSN The MSN of the user that is to be issued a referral

The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + UserID + MSN + Your secret salt

The service replies with HTTP-200 status when the operation was successful (e.g. the MSN is eligible for referral) with the following return values


SmsTemplate The template for the SMS text to send to the person being referred

POST /referral

Allows a user to refer a friend. If the friend registers the app inside a given time period the referral and/or referee is given a reward. This functioncall should only be called if the mechanism for referral distribution confirms that the referral has been sent (or as close as possible)

The service expects the following parameters as part of the URL.



MSN The MSN of the user that is to be issued a referral

The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + UserID + MSN + Your secret salt

The service replies with HTTP-200 status when the operation was successful.

Push notification support

Liquid Barcodes supports sending push notifications depending on certain events to the app provided that the following steps are completed bythe app developer/publisher:

Register the application with the relevant push notification services (Apple, Google, etc)Forward the credentials to Liquid Barcodes. The credentials we require are:

Apple push notification service: The iOS Push certificateGoogle Cloud Messaging (GCM) service: The API key

Add functionality to register each instance of the application running on the consumers' devices with the relevant push notificationservices to obtain the DeviceToken/RegistrationIDEvery time the DeviceToken/RegistrationID changes, AND upon achieving a successful registration, the app must call the RegisterDevicefunction described below:

Registering the device with Liquid Barcodes

POST /device

This function registers a device with Liquid Barcodes. Note that it is possible to have 0, 1 or many devices associated with a particular UserId (notregistered, registered on exactly one device or registered on many devices, respectively). Also for this function we expect the UserAgent HTTPheader in the request.


DeviceId This is the HW ID of the device that is making the call. This ID should be persistent and unique, and is used by Liquid to identifyif a particular UserID has installed the app on several devices. It is acceptable that the device identifier changes upon are-install.

UserID This is the UserId for the application. If left blank the consumer has not yet registered.

DeviceToken The device token assigned to the device upon registrering with the appropriate push notification service. If empty the applicationuser has declined to receive push notifications

MSN The telephone number the user has registered with.

Language The language setup for the user device according to ISO 6391

DeviceType The device type, where the following values are allowed 'iOS', 'Android'

AppVersion The version of the application (used to track how many users have upgraded to the latest versions)

Notes This is a free-text field that can be used to convey any information deemed relevant.

The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + DeviceId + UserId + DeviceToken + MSN + Language +DeviceType + AppVersion + Your secret salt

The service replies with HTTP-200 status when the operation was successful

Receipts handling

The following functions are supported for displaying receipts to the user, and to forward the receipts to the user outside of the app

GET /receipts

Thefollowing parameters are expected in the URL query-string.



StoreIds Optional: Will limit the retrieved receipts to this list of stores. Should use the s available in the GET /Stores/ call StoreId a

DateFrom Optional: Will limit the retrieved receipts to this datetime and forwards. This is used to get the receipts for the last 6 months f.e.x

Note this function call may be slow to respond and the app should be lenient towards any timeouts. The signature is calculated by SHA-2 256checksum of DateTime (HTTP header) + UserId + Your secret salt

The service replies with HTTP-200 status when the operation was successful with the following return values


Logo Url to companylogo

Note: If a particular store needs a separate logo, the store logo is available for each store from GET /storesfunction call

Array ofreceipts

Format Receipt format, e.g. for this field. The format is detailed belowLiquid/1.0

Receipt Optional: A JSON representation of the whole receipt for the complete transaction.The JSON should takethe following format:

1234567

https://en.wikipedia.org/wiki/ISO_639-1

89

1011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071

{ "ReceiptId":"", "TransactionDateTime":"", "SubTotal":0, "RebateOnSubTotal":0, "TenderOnSubTotal":0, "TaxAmount":0, "TotalToPay":0, "Currency":"", "Store":{ "StoreId":"", "ExternalStoreId":"", "StoreName":"", "GLN":"", "OrganizationNumber":"", "POSId":"", "EmployeeId":0, "EmployeeName":"" }, "Saleslines":[ { "Description":"", "EAN":"", "ProductCode":"", "PLU":"", "Quantity":0, "Unit":"", "Brand":"", "SalesPrice":0, "Rebate":0, "Tender":0, "RebatedPrice":0, "TaxAmount":0, "TaxPercentage":0, "Comment":"" } ], "Payments":[ { "type":"Card", "card_issuer":"", "card_issuer_country":"", "terminal_id":"", "terminal_print":"", "transaction_id":"", "ref_auth":"", "ref":"", "auth":"", "bax":"", "censored_card_number":"", "card_token":"", "amount":0, "tip_amount":0, "processing_fee":0, "currency":"" }, { "type":"Cash", "amount":20000, "tip_amount":0, "currency":"NOK" } ], "customer":{ "id":"", "loyalty_id":"", "msn":"", "name":"", "gender":"", "birthdate":"" }}

1.

2. 3. 4.

a.

b.

5.

Note: The JSON code must be escaped so that the Receipt field is just a regular string.

POST /forwardreceipts (Forward Receipts) (NOT IMPLEMENTED)

The service expects the following parameters.



ReceiptIds A list of receiptIDs to be forwarded

MediaType The media to forward the receipts, currently only 'email' is accepted

UserReference Optional: The recipient of the receipts. Not necessary if it appropriate information is already stored with the user (e.g. thee-mail address). Note that this value will override any values stored with the user (if the user wants to forward it to anotherperson or another e-mailaddress)

The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + UserId + ReceiptIds + MediaType + Your secret salt

The service replies with HTTP-200 status when the operation was successful

Coupon shop

The following paragraph describes the functionality required to present a 'coupon' shop area in your app. This functionality consists of three parts:

Shop front-end, this is the virtual store where the consumer can choose which products he wants to buy. Shop back-end, this is the handling of the shop items and the issuing of content based on shop transactions.Payment provider, this is a third party payment provider that handles the transaction of real money. If the currency in the shop is loyaltypoints this can be handled entirely by Liquid Barcodes, otherwise a integration between Liquid Barcodes and the payment provider mustbe implemented.

The interaction flow for the while process is as follows (where the app is only involved in step 1 to 3, and 7)

The App calls the function ShopOffers and gets a list of offers that can be bought for a certain price by the consumer. This call willprovide all the details necessary for the consumer to make a choice, and all the necessary details for issuing coupons.The consumer selects which offer he wants by putting them into a basket.When checkout of the basket is selected, the app sends a request to the shop back-end using the ProcessShopBasket call The back-end will request the baskets grand total to be reserved by the payment provider (note that this is not the actual payment, butreserving an amount of money on the consumers account).

The shop back-end will check that the request is valid and represents the offers that was provided in GET /shopoffers. This is toprevent tampering.Dependent on the third party payment provider the request will be processed synchronously ( orSuccessCode = OK) asynchronously (SuccessCode = InProcess). If processed asynchronously the app needs to request the status using GET/ShopTransactionStatus

Appropriate information should be given to the user that the process has completed, how much was paid and, if any, which couponscould not be issued.

Service definitions

Shop offer model

This is how shop offer model looks like:


ShopOfferId The unique ID for this particular offer.

PaymentProviderId The ID of the payment provider where the OfferToken must be sent.

MaximumAmount The maximum number of times the offer can be bought. If not present or NULL it means unlimited

ThumbUrl If present this points to an smaller representation of the shop offer to present on f.ex the front page of theapplication.

Url URL to the offer details image.

BackgroundColour If present this represents a background colour to use with this coupon. The background colour is represented in#AABBCC notation.

Type Defines the type of shop offer. Can take two values 'Shop' and 'Local'

LocalData Optional: If type is Local this section is mandatory (not implemented)

StoreId The StoreId that the local shop offer can be used

RemainingOffers The number of remaining offers

PickupStartDateTime The earliest time/date this offer be be picked up. The date/time is given in UTC.

PickupEndDateTime The latest time/date this offer be be picked up. The date/time is given in UTC.

Description A textual description of the shop offer.

ExpiryDate The time/date when this offer is no longer available . The expiration date/time is given in UTC.

RetailPrice The price to the consumer.

Currency Will always be the currency of the app's country (one app, one country).

OfferToken Deprecated: This is the token that represents the offer for this user. The OfferToken will be used to trigger couponsbetween the App vendor and Liquid Barcodes backends. NOTE: All the offer tokens will expire according tothe OfferTokensExpiration field below.

OfferInstanceId The unique instance ID for each individual shop offer

GET /shopoffers

Gets an overview of all the offers available in the shop for this user. This call is primarily used to get an overview of the shop offers that areavailable.

Request

The service expects the following parameters as part of the URL query-string:



CategoryIds Optional: If desirable to only get the shop offers for one or more categories, it can be specified as an array of CategoryIds. If not present or empty the response will contain all the available categories


Response

All images referred to in the response will have the HTTP headers Last-Modified and E-Tag set and the app should use this to detect whenimages have changed (do a HEAD request for the images).



Categories Array of categories

Id The Id of the category

Name The name of category

ShopOffers Array of content objects (see Shop offer model) that is placed in this category

OfferTokensExpiration The expiration time for included offer tokens in this category. After this time the offer tokens will beinvalid. A new set of shop offers must be fetched to supply the user with fresh offer tokens.

GET /shopcategories

Returns all shop offer categories.

No parameters are expected in the calling function. The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + Yoursecret salt.



Categories List of shop offer categories, each object containing:

CategoryId The Id of the category

CategoryName The name of category

It is recommended to download this list of shop offer categories on a regular basis and cache it locally.

POST /ProcessShopBasket

This will process the basket of specified shop offers and withdraw credits from the account associated with the user. Each call to this function is aseparate purchase transactions for the user

Request


UserId The UserId of the user

StoreId Optional: The Liquid Barcodes storeId is required if the offer can only be used at a given store.

PaymentProviderId The Liquid Barcodes Payment Provider Id. The appropriate value to use here will be provided by Liquid Barcodes

PaymentInformation Optional: Any information that is necessary to process the transaction with the payment provider, an example could bethe payment provider session if this session is started from the app. This parameter is an array of Key:Value pairs.

TotalBasketValue The total value of the basket. This is used to control that what has been presented to the consumer matches the offers tobe processed

ShopOffers An array of shop offers tokens that are to be processed.

OfferInstanceId The offer instanceId that is unique for this shop offer and UserId

Amount The number of products to buy. This parameter have a value between 1 and MaximumAmount set in the shop offer

The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + UserId + PaymentProviderId + TotalBasketValue +Concatenated(OfferInstanceId + Amount) + Your secret salt

A successful call will return a HTTP 200 OK with the following format

Response

Fieldname Title Description

TransactionId Transactionreference

A reference to LIQUIDs internal transactionID.

Timestamp Transactiontimestamp

The date and time when the reservation was completed.

TotalValue Total transactionvalue

This is the total value that is used for the transaction

ShopOffers Optional: An array of shop offers tokens that are to be processed. The array is only present if the order has beenfulfilled

OfferInstanceId Offer instance ID The offer instance Id that was purchased

Amount Amount The number of products bought.

SuccessCode Success code Optional: On success returns

OK - The purchases was completed synchronously and the transaction is finalisedInProcess - The order is currently processed. The status of the order can be checked with GET/ShopTransactionStatus

SuccessMessage Successmessage

Optional. A human readable response message when the call was successful. Only set when is set.SuccessCode

RejectCode Reject code Optional. A code that can be used to programatically recognize the cause of a rejection. Either SuccessCode orRejectCode will be present in the response.

The following values can occur:

PriceChanged. The app needs to get updated pricing information and re-issue ProcessShopBasketNothingIsSelected. ShopOffers collection is emptyWrongPaymentProvider. The appropriate value to use here will be provided by Liquid BarcodesTotalBasketValueNotMatch. This is used to control that what has been presented to the consumer matches theoffers to be processedWrongStore. ShopOffer can only be used at another storeInvalidAmount. ShopOffer is configured with MaximumAmountWrongUser. UserId in request is wrongUnknownError. Some server error

RejectMessage Reject message Optional. A human readable cause of rejection message in case a rejection occurred. Only set when isRejectCode set.

GET /ShopTransactionStatus

Can be called to check the status of the transaction at a later stage.

Request



TransactionId A reference to LIQUIDs internal transactionID.

The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + UserId + TransactionId + Your secret salt


Response


TransactionId Transactionreference

A reference to LIQUIDs internal transactionID.

Timestamp Transactiontimestamp


TotalValue Total transactionvalue

This is the total value that is used for the transaction

ShopOffers Optional: An array of shop offers tokens that are to be processed. The array is only present if the order has beenfulfilled

OfferInstanceId Offer instance ID The offer instance Id that was purchased

Amount Amount The number of products bought.

SuccessCode Success code Optional: On success returns

Fulfilled - The order has been fulfilledInProcess - The order is currently processed. The status of the order can be checked with GET/ShopTransactionStatus


Optional. A human readable response message when the call was successful. Only set when is set.SuccessCode

RejectCode Reject code Optional. A code that can be used to programatically recognize the cause of a rejection. Either SuccessCode orRejectCode will be present in the response.


PriceChanged. The app needs to get updated pricing information and re-issue ProcessShopBasketNothingIsSelected. ShopOffers collection is emptyWrongPaymentProvider. The appropriate value to use here will be provided by Liquid BarcodesTotalBasketValueNotMatch. This is used to control that what has been presented to the consumer matches theoffers to be processedWrongStore. ShopOffer can only be used at another storeInvalidAmount. ShopOffer is configured with MaximumAmountWrongUser. UserId in request is wrongUnknownError. Some server error

RejectMessage Reject message Optional. A human readable cause of rejection message in case a rejection occurred. Only set when isRejectCode set.

Code management

POST /code/usage

This allows the app to use codes issued by Liquid Barcodes. The effect of such a usage is controlled entirely by Liquid Barcodes system.

Request



TransRef A 'unique' reference to this transaction. If several ReserveCodes call use the same transaction reference it means that theredemption of these codes should be considered a single transaction

Code The code to be reserved

StoreId Optional: If the app is simulating a redemption from a store the StoreId must be present

Position . An attempt to acquire geographical location.OptionalShould be set whenever an attempt to acquire location was made. In this object you must set either Position or ErrorCode+Error.

Position . Must be set when the attempt to acquire geographical locationOptional succeeded.The position will be used to attempt identification of which store performed the reservation.Position is given as decimal degrees (DD). Conversion from sexagesimal (DMS): With degrees, add minutes as /60 fractions, addseconds as /3600 fractions.

Longitude Longitude / meridian. Range from -180.0 (180 degrees west) to 180.0 degrees (180 degrees east).

Latitude Latitude / parallel. Range from -90.0 (south pole) to 90.0 degrees (north pole).

Accuracy . The accuracy for the position in meters.Optional

Altitude Altitude in meters, relative to sea level.Optional.

AltitudeAccuracy . The accuracy for the altitude in meters.Optional

Speed . Current velocity of the device in meters per second.Optional

Heading . Current heading in degrees of clockwise deviation from heading true north (which means that 0, 90, 180, 270 degrees isOptionalnorth, east, south and west, respectively).

ErrorCode . Must be set when the attempt to acquire geographical locationOptional failed.Error classification. One of: PermissionDenied, Unavailable, Timeout, NotSupported, Unknown.

Error . Must be set when the attempt to acquire geographical locationOptional failed.Error message / details. May be a blank string if there are no further details that ErrorCode.

The signature is calculated by SHA-2 256 checksum of DateTime (HTTP header) + TransRef + Code + Your secret salt UserId +


Response


LiquidLogRef Logreference

A reference to LIQUIDs internal logs.

UniqueCode Uniquecouponcode

The reserved unique coupon code.

Timestamp Reservationtimestamp


Value Reservationvalue

Optional: The monetary value of the reservation

SuccessCode Successcode

Optional. The success code that can be used to programmatically recognize the successful result of theoperation. Either SuccessCode or RejectCode will be present in the response.


Optional. A human readable response message in case the codes was used. Only set when SuccessCode is set.

RejectCode Reject code Optional. A code that can be used to programatically recognize the cause of a rejection. If this field is set itmeans that the reservation has failed, all other values for this reservation must be disregarded. EitherSuccessCode or RejectCode will be present in the response. (Our suggested user response in italic andbrackets)


CustomerMismatch, the requested UniqueCode belongs to a campaign that is not (Invalid code), associated with the authenticated user.CampaignInactive, the requested UniqueCode belongs to a campaign that is no longer / (Invalid code), not yet active.CampaignOncePerSaleOnly, the campaign setup demands that the UniqueCode can (Invalid code), only be used once per receipt and this requirement was not fulfilled.ReservationCountTooHigh, too many unvalidated+uncancelled reservations exist for (Code is depleted), this UniqueCode.ScheduleInactive, the requested UniqueCode belongs to a campaign that is no longer / (Invalid code), not yet active.ScheduleStoreMismatch, the UniqueCode was issued for use in a specific store, this (Wrong store), requirement was not fulfilled.ScheduleNoRemainingValidations, , the campaign has a limited amount of (Campaign is depleted)validations and there are no validations left.CodeInactive, , the requested UniqueCode has expired. (Code has expired)CodeAlreadyUsed, the requested UniqueCode only allows one validation and is (Code is depleted), already validated.CodeNotFound, the requested UniqueCode is invalid. (Invalid code), CodeDepleted, the requested UniqueCode has already been used the maximum (Code is depleted), number of allowed timesDailyValidationsExceeded, the code has reached or exceeded the maximum (Code is depleted today), number of validations per day.Blocked, , the code or campaign has been blocked. Used when phasing out a (Code has expired)campaign, for example.

RejectMessage Rejectmessage

Optional. A human readable cause of rejection message in case a rejection occurred. Only set when Rejectis set.Code

List of errors

The raw error ID can be read from the HTTP header.X-Liquid-ErrorId

Error ID HTTPStatus

Services Description

0 500 0 Any. Unknown error, contact Liquid Barcodes.

1 401 1 Any. The signature in the X-Liquid-Signature HTTP header was wrong.

2 401 2 Any. The timestamp in the X-Liquid-Timestamp HTTP header was not parsable or had more than 10minutes deviation from our current time.

8 500 8 Any. Unauthorized access. User either not exists or not allowed to use app.

10 500 10 POST /pin Failed to send PIN.

12 500 12 POST /user Incorrect PIN.

13 500 12 POST /user Expired PIN.

22 500 22 POST /user Cannot find device ID for the user.

23 500 23 GET /validreferralPOST /referral

Too many recruitment attempts.

33 500 33 POST /pin Too many MSNs has been used from the same device.

34 500 34 GET /validreferral

POST /referral

Missing or invalid MSN.

44 500 44 PUT /user Failed to update user profile.The response body is an array of UserGroups that wasn't processed + ErrorCode + Message, witherror description:

1001 Can't validate code [UserCode] for group tag [GroupId].1002 Can't find active group for tag [GroupId]1003 Can't quit group [GroupId], because user is not member of this group1004 Group [GroupId] is not user configurable

45 500 45 POST /initialize Missing or invalid Device ID.

47 500 47 POST /user Minimum age not met.

48 500 48 Any. A service requires master consent approval before it can be used.

49 500 59 Any. Reset user exception. The user has been marked for a reset, force a new POST /initialize, POST /pin,POST /user.

50 500 45 POST /share Missing or invalid Schedule ID.

51 500 51 POST /referral Attempted to refer a MSN that was not referable.

52 500 52 POST /device Missing or invalid language code.

53 500 53 POST /device Missing or invalid device type.

54 500 54 POST /device Missing or invalid app version.

55 500 55 POST /user Invalid PIN.

56 500 56 POST /user Invalid person name.

57 500 57 POST /user Invalid address.

58 500 58 POST /user Invalid city.

59 500 59 POST /user Invalid post code.

60 500 60 POST /user Invalid email.

61 500 61 POST /user Invalid date of birth, should be yyyy-mm-dd.

62 500 62 Any with UserId. Missing or invalid User ID.

63 500 63 ValidateScratchCard Invalid card ID.

64 500 64 POST /code/usage Invalid code

App feed API Unified v3 - Liquid Barcodeskb.liquidbarcodes.com/wp-content/uploads/2018/05/...May 16,...

Documents

Transcript of App feed API Unified v3 - Liquid Barcodeskb.liquidbarcodes.com/wp-content/uploads/2018/05/...May 16,...