Revision as of 13:47, 5 December 2018 by Docadmin (talk | contribs) (Checkin)

Contents

Overview

UrbanBuz is an easy-to-manage cloud-based customer engagement platform that helps businesses capture relevant customer information; incentivize customers based on different behaviors, and engage with them in a personal and relevant manner through different channels (SMS/Email/Mobile). The cloud-based platform is designed for marketers so they can start making sense of the customers data and engage with them without the need for coding or having to deal with different tools and most importantly in real time. Marketers can define their own customer profiles, filter data accordingly, setup automated marketing based on certain behavior and filters, track marketing campaign live, and incentivize customers.

Getting started

Introduction to UrbanBuz API

Application Programming Interfaces (APIs) available with UrbanBuz can be used by businesses across different segments to integrate with UrbanBuz platform. Businesses can use these APIs to manage customer data, sales data, marketing data and so on. User credentials are provided by UrbanBuz to access the APIs. All API calls need to be made using the HTPP protocol to ensure data security. The UrbanBuz APIs are based on Representational State Transfer (REST) standards. REST defines a set of principles for defining Web services, including how a system’s resource states are transferred over HTTP.

About this document

This document is intended for developers who want to use UrbanBuz APIs. This document is based on REST API version 3. It describes how to use REST API to authenticate, make requests, and retrieve data. The APIs use (JavaScript Object Notation) JSON as the default message format. JSON provides a lightweight, simple, and more flexible message format that increases the speed of communication. You need to use standard HTTP methods to access the UrbanBuz APIs. For example, HTTP GET is used by a client application to retrieve a resource, get data from a Web server or to execute a query. Common HTTP methods for REST are:

  • GET – Retrieve a resource from the server
  • POST – Update a resource on the server
  • PUT – Create a resource state on the server.
  • DELETE – Remove a resource state on the server.

Version information

This document is based on REST API version 3.

Authentication

UrbanBuz uses customized OAuth 1.0b authentication specification with HMAC-SHA1 signature method that requires a Key and Secret. The following sections explain how to generate an OAuth 1.0b HMAC-SHA1 signature for an HTTP request. This signature is required for passing all UrbanBuz APIs as part of an authorized request. UrbanBuz will provide the Key and Secret along with an OAuth connection library that is required to a create a signature for accessing resources via OAuth (currently using PHP).

Collecting the request method and URL

To create a signature, you need to determine the HTTP method and URL of the request. The base URL is the URL to which the request is directed, excluding any query string or hash parameters. Make sure that the “http//” portion of the URL matches the actual request sent to the API.

Base URL:

http://[subdomain].urbanbuz.com

Query Parameter:

All the query parameter values MUST be URL encoded with UTF-8. See the following example:

http://[subdomain].urbanbuz.com/program/account/search?first=MiKe+Kate

Here, the query parameter value Mike+Kate is encoded to result to MiKe%2BKate.

Collecting the parameters

Collect all the parameters included in the request. There are two locations for these additional parameters - the URL (as part of the querystring) and the request body. In addition to the request parameters, authentication parameters such as auth_key, oauth_nonce, oauth_signature_method, and oauth_timestamp should be included. The parameters (request parameter and authentication parameters) are listed as follows: The values need to be encoded into a single string, called the parameter string.

Parameter Value Description
append_payment True This is the request parameter
oauth_key String API key assigned for the branch or program. Example: pIddeizKeygxPDRuaLNt
oauth_nonce String Random alphanumeric string, uniquely generated to allow the server to verify that a request has never been made before. The nonce value is unique across all requests. Example: lxucb66OAp0
oauth_signature_method String Keyed-hash message authentication specification known as HMAC-SHA1 to sign API calls.
oauth_timestamp String Indicates when the request was created.

The following string will be produced with the parameters collected in the table above:

append_payment=true&oauth_key=xvz1evFS4wEEPTGEFPHBog&oauth_nonce=kYjzVBB8Y0ZFab&oauth_signature_method=HMAC-SHA1&oauth_timestamp=123456789

Creating the signature base string

The three request elements such as HTTP method, base URL, and the parameters must be concatenated to make a single string, from which the signature will be generated. This is called the signature base string by the OAuth specification.

  • HTTP method: The HTTP request method
  • Base URL: The URL the request is being sent to. This URL should not include any query parameters
  • Parameter string: String of the parameters in the request (excluding the oauth_signature parameter). Example: append_payment=true,oauth_key=key&oauth_nonce=nonce&oauth_timesta mp=123456789

To encode the HTTP method, base URL, and parameter string into a single string:

  1. Convert the HTTP Method to uppercase and set the output string equal to this value.
  2. Append the ‘&’ character to the output string.
  3. Percent encode the URL and append it to the output string.
  4. Append the ‘&’ character to the output string.
  5. Percent encode the parameter string and append it to the output string.

This will produce the following signature base string:

PUT&http%3A%2F%2Fapi.urbanbuz.com%2Ftxn%2Ftransactions%2Fsubmit&append_payment%3Dtrue%26oauth_key%3Dtest_key%26oauth_nonce%3D8LbvcvYFqqG5RKl1zhr5%26oauth_timestap%3D123456789

Generating the signature

The signature is calculated by passing the signature base string and signing key to the HMAC-SHA1 hashing algorithm. The generated signature is then added to the request as oauth_signature before sending it to the API.

Status code and error messages

API requests can at times result in errors and return appropriate status code that help you identify the error type. The following table describes standard error codes returned by the APIs:

Status code Text Description
200 OK Indicates that the request was correct and sent to the core for further processing.
400 Bad request Indicates that the request does not contain all the information/ parameters in order to proceed. This

error is returned from the Resource class. Domain validation errors, missing data, etc. are some examples.

401 Not authorized Indicates that the request was not authorized and cannot proceed. This error code is

returned from Authentication Filter class.

500 Internal server error The server encountered an unexpected condition which prevented it from fulfilling the request.

This need to be analyzed further.

The following table describes the standard error codes returned by UrbanBuz APIs.

Error code Description
1001 The request payload is empty
1002 Certain field values are empty
1003 Internal Server Error
1004 Certain fields are not unique
1005 No data found in the database for the sent request parameters
1009 No data found in the database for the sent request parameters
1010 At least one of the fields required to be filled

Timestamp

Timestamps are returned in the UTC format: YYYY-MM-DDTHH:MM:SSZ

Transaction APIs

The following sections describe the transaction API calls.

Accounts

Signup

When a customer accesses the Registration page and submits the registration details by filling in the form, the Signup API call is invoked. If the API response is success, it indicates that the customer is new and gets registered. If the response indicates that the customer is already registered, the customer is provided the option to send an email to confirm identity and to update existing profile.

URL Method Returns Permission
http://[subdomain].urbanbuz.com/customer/online/signup POST
  • 200: Successful
  • 400: Bad request
  • 401: Not authorized
  • 500 Internal server error
Authentication

Request elements

Parameter Type Required Description
gender String Yes Gender of the customer
first String Yes First name of the customer
last String No Last name of the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
birth_date Date Yes Birth date of the customer
nationality String Yes The nationality the customer belongs to
country String Yes Country of residence of the customer
state_city_emirate String No State or city or Emirate of residence of the customer
home_location String No Area where the customer resides
work_location String No Work location of the customer
pin String Yes A secret pin for identification (Please set a secret

number for identification)

Example request

POST http://[subdomain].urbanbuz.com/customer/online/signup

{

   "customer" : {
       "gender"             : "M",
       "first"              : "Jad",
       "last"               : "Hajj Obeid",
       "phone"              : "971557802482",
       "email"              : "jad@urbanbuz.com",
       "birth_date"         : "1970-12-01"
       "nationality"        : "LB",
       "country"            : "AE",
       "state_city_emirate" : "LB",
       "home_location"      : "Tecom",
       "work_location"      : "Discovery Gardens",
       "pin"                : "1234"
    }

}

Example response

{
   "status" : "SUCCESS"

}

Checkin

When a customer logs in to the Registration page, the checkin call is invoked using the phone number or the email ID of the customer. If checkin is successful, the call will retrieve all the details about the customer updated in the system. The checkin call will also return a token that needs to be used when logging in for all subsequent calls to the API.

URL Method Returns Permission
http://[subdomain].urbanbuz.com/customer/online/checkin POST
  • 200: Successful
  • 400: Bad request
  • 401: Not authorized
  • 500 Internal server error
Authentication

Request elements

Requires either phone number or email.

Parameter Type Required Description
include_loyalty Boolean Yes True if customer’s loyalty account details need to be fetched.
include_token Boolean Yes True if token is required in the response.
phone* String Yes Phone number of the customer
email* String Yes Email ID of the customer
  • Note: Requires either the phone number or email ID of the customer.

Example request

POST http://[subdomain].urbanbuz.com/customer/online/checkin?include_loyalty=true&include_token=true

{

   "email"              : "javid@urbanbuz.com"

}

Example response

{
 "customer": {
   "gender": "F",
   "birth_date": "2012-11-10 00:00:00 UTC",
   "profile_set": true,
   "email": "971552222220@email.com",
   "country_iso": "AE",
   "last": "B",
   "nationality": "IN",
   "user_id": 4357289,
   "phone": "971552222220",
   "first": "Sumaya"
 },
 "loyalty": {
   "program": {
      "name": "Loyalty Program Name",
      "logo": " https://urbanbuz.com/images/loyalty_program_1.jpg "
   },
   "tier": {
     "name": "Loyalty Tier 1",
     "logo": "https://urbanbuz.com/images/loyalty_tier_1.jpg",  
     "order": 1,
     "expiry": "2019-01-01"
        },
   "wallets": [
     {
       "countryIso": "AE",
       "currency": "AED",
       "point": 1575,
       "value": 15.75
     }
   ],
   "redeemable": {
     "point": 1000,
     "value": 10,
     "currency": "AED"
     },
     "expiry": {
       "point": 256,
        "date": "2018-07-03"
        },
        "token": "GEnuH4SLV811"

}

Login with token

Use the login call to retrieve customer details with the token obtained during checkin. The call will retrieve the same details as retrieved through the checkin call. The login call will return all the details about the customer including his/her profile along with the loyalty details (balance, expiry, tier, etc…). Also, the login call will return a session token that needs to be used in all subsequent calls to the API.

URL Method Returns Permission
http://[subdomain].urbanbuz.com/api/customers/login POST
  • 200: Successful
  • 400: Bad request
  • 401: Not authorized
  • 500 Internal server error/api/customers/login
Authentication

Request elements

Parameter Type Required Description
token String Yes Customer’s token received as a query parameter

Example request

POST http://[subdomain].urbanbuz.com/api/customers/login

{

   "token" : "abc123"

}

Example response

{

   "phone"          : "971557802482",
   "email"          : "jad@urbanbuz.com",
   "first"          : "Jad",
   "last"           : "Hajj Obeid",
   "nationality"    : "LB",
   "gender"         : "M",
   "birth_date"     : "1970-12-01",
   "profile_set"    : true, // indicates if customer’s profile is set
   "current_credit" : 12.34, // customer’s loyalty balance
   "expires"        : "Aug 9, 2018 7:48:55 AM", // loyalty balance expiry
   "level"          : 1, // customer’s level
   "label"          : "Blue", // customer’s level name
   "level_expires"  : "Aug 9, 2018 7:48:55 AM", // level expiry
   "token"          : "abc123", // customer’s session token
   "tokenExpires"   : "Aug 12, 2017 12:56:02 PM", // session token expiry
   "refreshToken"   : "abc123" // customer’s refresh token

}

Login with OTP

Customers will receive SMS or Email with a short-code (4 digits) to be used during login. This will redirect to a page to verify the code in order to login. After entering the code, it is submitted along with the email or phone previously entered, through the /login API call. This will retrieve all the details about the customer.

URL Method Returns Permission
POST http://[subdomain].urbanbuz.com/api/customers/otp POST
  • 200: Successful
  • 400: Bad request
  • 401: Not authorized
  • 500 Internal server error/api/customers/login
Authentication

Request elements

Requires either phone number or email.

Parameter Type Required Description
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
code Integer Yes OTP received as communication

Example request

POST http://[subdomain].urbanbuz.com/api/customers/login

{

   "phone" : "971557802482",
   "code"  : "1234"

}

Example response

{

   "phone"          : "971557802482",
   "email"          : "jad@urbanbuz.com",
   "first"          : "Jad",
   "last"           : "Hajj Obeid",
   "nationality"    : "LB",
   "gender"         : "M",
   "birth_date"     : "1970-12-01",
   "profile_set"    : true, // indicates if customer’s profile is set
   "current_credit" : 12.34, // customer’s loyalty balance
   "expires"        : "Aug 9, 2018 7:48:55 AM", // loyalty balance expiry
   "level"          : 1, // customer’s level
   "label"          : "Blue", // customer’s level name
   "level_expires"  : "Aug 9, 2018 7:48:55 AM", // level expiry
   "token"          : "abc123", // customer’s session token
   "tokenExpires"   : "Aug 12, 2017 12:56:02 PM", // session token expiry
   "refreshToken"   : "abc123" // customer’s refresh token

}

Create account

This call is executed to create account for programs. The parameters of this call are dynamic based on the business setup of the account’s profile.

URL Method Returns Permission
http://[subdomain].urbanbuz.com/program/accounts POST
  • 1004: The following field is not unique
  • 1010: At least one of the following fields is required
Authentication

Request elements

Parameter Type Required Description
first String No First name of the customer
last String No Last name of the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
gender String No Gender of the customer
birthdate Date No Date of birth of the customer
nationality String No Nationality of the customer

Example request

POST http://[subdomain].urbanbuz.com/program/accounts

{ "profile": { "phone": "971502189231",

"email": "john@email.com",

"first": "John",

"last": "Samuel",

"birthdate": "1988-06-06",

"gender": "M",

"city": null,

"country": null,

"nationality": "India",

"language": null,

"businessFields": {

"maritalStatus": "Married",

"residency": "tourist",

"ethnicity": "Asian" } } }

Example response

{
   "status" : "success",
   "account" : {
        "accountId" : "f64f2940-fae4-11e7-8c5f-ef379131"
   }

}

Search for account

This call is executed to search for the accounts.

URL Method Returns Permission
http://[subdomain].urbanbuz.com/program/accounts/search?phone={phone}&email={email}&first={first}&last={last}& businessFieldsRequired={commaSeparated}&page={pageNum}&size={pageSize} GET
  • 200: Successful
  • 400: Bad request
  • 401: Not authorized
  • 500 Internal server error
Authentication

Request elements

Parameter Type Required Description
first String No First name of the customer
last String No Last name of the customer
phone String No Phone number of the customer
email String No Email Id of the customer
employeeId String No Employee ID of the customer
businessFieldsRequired String No Business fields required in the response
page Integer Yes Search page number
size Integer Yes Number of records to return by page

Example request

GET http://[subdomain].urbanbuz.com/program/accounts/search?first=Jenn&last=C& businessFieldsRequired=title,street1&page=1&size=10

Example response

{
 "pageNumber": 1,
 "pageSize": 10,
 "totalCount": 7,
 "data": [
   {
     "phone": "971502188801",
     "email": "jane@gmail.com",
     "accountId": "2a5676fe-0151-435f-b392-131ab2eae0c5",
     "first": "Jennifer",
     "last": "Christi",
     "birthdate": "1987-09-11",
     "profileSet": "2018-03-26 12:44:55 GST",
     "businessFields": {
       "title": "Mr."
   },    
   {
     "phone": "971502188844",
     "email": "jen124@gmail.com",
     "accountId": "e4670b54-4d13-40c3-a49a-64d225231152",
     "first": "Jennie",
     "last": "Cooks",
     "birthdate": "1987-09-11",
     "profileSet": "2018-03-28 06:56:03 GST",
     "businessFields": {
       "street1": "M street"
     }
   }
 ]

}

Get account by ID

This call is executed for obtaining the details of the account by IDs for a particular program. The parameters of this call are dynamic based on the business setup of the account’s profile.

URL Method Returns Permission
http://[subdomain].urbanbuz.com/program/accounts?accountId={accountId}&loyalty=true GET
  • 1005: Data Not Found
Authentication

Request elements

Requires either phone number or email.

Parameter Type Required Description
accountId String Yes Unique identity of the customer account
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
loyalty Boolean Yes Flag to indicate to return loyalty information

Example request

GET http://[subdomain].urbanbuz.com/program/accounts?accountId=f64f2940-fae4-11e7-8c5f-ef379131&phone=971551467246&loyalty=true

Example response

{

"profile": { "phone": "971502189231",

"email": "john@email.com",

          "accountId": "f64f2940-fae4-11e7-8c5f-ef379131",

"first": "John",

"last": "Samuel",

"birthdate": "1988-06-06",

"gender": "M",

"city": null,

"country": null,

"nationality": "India",

"language": null,

"businessFields": {

               "title": "Mr.",

"maritalStatus": "Married",

"ethnicity": "Asian" } },

    "loyalty" : {
       "program" : {
           "name"   : "Loyalty Program Name",
           "logo"   : " https://urbanbuz.com/images/loyalty_program_1.jpg "
       },
       "tier" : {
           "name"   : "Loyalty Tier 1",
           "logo"   : "https://urbanbuz.com/images/loyalty_tier_1.jpg",
           "order"  : 1,
           "expiry" : "2019-01-01"
       },
       "wallets" : [{
           "countryIso" : "AE",
           "currency"   : "AED",
           "point"      : 1575,
           "value"      : 15.75,
       }],
      "redeemable": {
         "point": 1000,
          "value": 10,
         "currency": "AED"
        },
       "expiry": {
      "point": 256,
      "date": "2018-07-03"
   }

}

Update account by ID

This call is executed for updating account by IDs for programs. The parameters of this call are dynamic based on the business setup of the account’s profile.

URL Method Returns Permission
http://[subdomain].urbanbuz.com/program/accounts?accountId={accountId}&phone={phonenumber} PUT
  • 1004: The following field is not unique
  • 1010: At least one of the following fields required
Authentication

Request elements

Requires either phone number or email.

Parameter Type Required Description
accountId String Yes Unique identity of the account
first String No First name of the customer
last String No Last name of the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
gender String No Gender of the customer
birthdate Date No Date of birth of the customer
nationality String No Nationality of the customer

Example request

PUT http://[subdomain].urbanbuz.com/program/accounts?accountId=f64f2940-fae4-11e7-8c5f-ef379131

{ "profile": { "phone": "971502189231",

"email": "john@email.com",

"first": "John",

"last": "Samuel",

"birthdate": "1988-06-06",

"gender": "M",

"city": null,

"country": null,

"nationality": "India",

"language": null,

"businessFields": {

                "title": "Mr.",

"maritalStatus": "Married",

"ethnicity": "Asian" } } }

Example response

{
   "status" : "success"

}

Get account mapping

URL Method Returns Permission
http://[subdomain].urbanbuz.com/online/{token}/brand_mappings GET
  • 200: Successful
  • 400: Bad request
  • 401: Not authorized
  • 500 Internal server error
Authentication

Request elements

Parameter Type Required Description
token String Yes Customer’s token received as the query parameter

Example request

GET http://[subdomain].urbanbuz.com/online/​{token}/brand_mappings

Example response

{
    ​"countryIso"  ​: ​"AE"​, 
    ​"countryName"​ : ​"United Arab Emirates"​,   
 ​   "brandId"​     : ​22​,    
    ​"brandName"​   : ​"Bershka" 

},

{

    ​"countryIso"  ​: ​"AE"​,  
  ​  "countryName" ​: ​"United Arab Emirates"​,  
    ​"brandId"     ​: ​45​,    
    ​"brandName"   ​: ​"Zara" }

Get account communication preferences

URL Method Returns Permission
http://[subdomain].urbanbuz.com/online/{token}/communication/preferences GET
  • 200: Successful
  • 400: Bad request
  • 401: Not authorized
  • 500 Internal server error
Authentication

Request elements

Parameter Type Required Description
token String Yes Customer’s token received as query parameter

Example request

GET http://[subdomain].urbanbuz.com/online/​{token}/communication/preferences

Example response

{
   ​"channel"     ​: ​1​, 
   ​"channelName" ​: ​"SMS"​,    
​"countryBrandPreferences" ​: [{     
   ​"countryIso"  ​: ​"AE"​,        
   ​"countryName"​ : ​"United Arab Emirates"​,  
      ​"brandId"​     : ​22​,       
   ​"brandName"​   : ​"Bershka"​,     
   ​"communicationCategories" ​: [{     
  ​"optOut"       ​: ​true​,      
 ​ "categoryId"​   : ​8​,       
  ​"categoryName"​ : ​"Newsletter"   
     }]  
  }] 

}

Brands

Get brands

This call is executed to obtain all brands registered with a program.

URL Method Returns Permission
http://[subdomain].urbanbuz.com//online/brands GET
  • 200: Successful
  • 400: Bad request
  • 401: Not authorized
  • 500 Internal server error
Authentication

Example request

GET http://[subdomain].urbanbuz.com/online/brands

Example response

{

 "brand_id" ​: ​20​, 
 "name"     ​: ​"Bershka" 

}, {

"brand_id" ​: ​21​,
"name"     ​: ​"Zara" 

}

Get categories

This call is executed to obtain the product categories associated with the brand.

URL Method Returns Permission
http://[subdomain].urbanbuz.com//online/categories GET
  • 200: Successful
  • 400: Bad request
  • 401: Not authorized
  • 500 Internal server error
Authentication

Example request

GET http://[subdomain].urbanbuz.com/online/categories

Example response

{
 "id" ​: ​20​, 
 "name"     ​: ​"Fashion & Accessories" 

},

{ "id" ​: ​21​,

"name"     ​: ​"Beauty&Wellness" 

}

Vouchers

Get vouchers of customer

This API call is executed to obtain the list of all vouchers associated with a particular customer, which includes Available, Expired, and Already Used vouchers for that customer.

URL Method Returns Permission
http://[subdomain].urbanbuz.com/online/{token}/vouchers GET
  • 200 - successful
  • 400 - bad request
  • 401 - not authorized
  • 500 - internal server error
Authentication

Request elements

Parameter Type Required Description
token String Yes Customer’s token received as a query parameter

Example request

GET http://[subdomain].urbanbuz.com/online/{token}/vouchers

Example response

{
   "title"     : "Voucher A",
   "icon"      : "https://urbanbuz.com/images/vouchera.jpg",
   "code"      : "7bf147",
   "issued"    : "2018-01-01",
   "expires"   : "2018-02-01",
   "value"     : "20",
   "valueType" : "percentage",
   "status"    : "active"

}, {

   "title"     : "Voucher B",
   "icon"      : "https://urbanbuz.com/images/voucherb.jpg",
   "code"      : "e3a962",
   "issued"    : "2017-01-01",
   "expires"   : "2018-01-01",
   "value"     : "100",
   "valueType" : "fixed",
   "status"    : "expired"

}, {

   "title"     : "Voucher C",
   "icon"      : "https://urbanbuz.com/images/voucherc.jpg",
   "code"      : "5b103c",
   "issued"    : "2017-01-01",
   "expires"   : "2018-01-01",
   "value"     : "10",
   "valueType" : "percentage",
   "status"    : "redeemed",
   "redeemed"  : "2017-12-30 12:34:56",
   "redeemedBranch" : {
       "name"       : "Dubai Mall",
       "brandName"  : "Brand A"
   }

}

Get vouchers by account ID

This call is executed for obtaining the list of vouchers by account ID. The parameters of this call are dynamic based on the business setup of the account’s profile.

URL Method Returns Permission
http://[subdomain].urbanbuz.com/program/accounts/vouchers?accountId={accountId} GET
  • 200 - successful
  • 400 - bad request
  • 401 - not authorized
  • 500 - internal server error
Authentication

Request elements

Requires either phone number or email.

Parameter Type Required Description
accountId String Yes Unique identity of the account

Example request

GET http://[subdomain].urbanbuz.com/program/vouchers?accountId=f64f2940-fae4-11e7-8c5f-ef379131

Example response

[{
   "title"     : "Voucher A",
   "icon"      : "https://urbanbuz.com/images/vouchera.jpg",
   "code"      : "7bf147",
   "issued"    : "2018-01-01",
   "expires"   : "2018-02-01",
   "value"     : "20",
   "valueType" : "percentage",
   "status"    : "active"

}, {

   "title"     : "Voucher B",
   "icon"      : "https://urbanbuz.com/images/voucherb.jpg",
   "code"      : "e3a962",
   "issued"    : "2017-01-01",
   "expires"   : "2018-01-01",
   "value"     : "100",
   "valueType" : "fixed",
   "status"    : "expired"

}, {

   "title"     : "Voucher C",
   "icon"      : "https://urbanbuz.com/images/voucherc.jpg",
   "code"      : "5b103c",
   "issued"    : "2017-01-01",
   "expires"   : "2018-01-01",
   "value"     : "10",
   "valueType" : "percentage",
   "status"    : "redeemed",
   "redeemed"  : "2017-12-30 12:34:56",
   "redeemedBranch" : {
       "name"       : "Dubai Mall",
       "brandName"  : "Brand A"
   }

}]


Transaction

Submit transaction

URL Method Returns Permission
http://[subdomain].urbanbuz.com/transaction/transactions/submit PUT
  • 1004: The following field is not unique
  • 1006: The following fields are invalid
  • 1002: Fields are empty
Authentication

Request elements

Parameter Type Required Description
customer.accountId String Yes Unique identity assigned to the customer
customer.phone String Yes Phone number of the customer
customer.email String Yes Email ID of the customer
receipt String Yes Transaction’s unique identity
openTime Date Yes Transaction’s open time
closeTime Date Yes Transaction’s time of closing
operatorId String No Cashier’s unique identity
operatorName String No Cashier’s name
deviceId String No POS terminal’s unique identity
deviceName String No POS terminal’s name
billed Decimal Yes Transaction’s gross total
paid Decimal Yes Transaction’s net paid
redeemed Decimal Yes Transaction’s net paid in loyalty redemption
billDiscount Decimal Yes Transaction’s total bill level discount
itemDiscountTotal Decimal Yes Transaction’s total item level discount
billTax Decimal Yes Transaction’s total bill level tax
itemTaxTotal Decimal Yes Transaction’s total item level tax
sku String Yes Line item’s unique identifier
qty Decimal Yes Line item’s quantity
unitPrice Decimal Yes Line item’s gross unit price
payments.name String Yes Currency type (e.g. UAE currency)
payments.typeName String Yes Payment type (e.g. Cash)
payments.amount Decimal Yes Payment amount
payments.referenceId String Yes Unique identity of the voucher if voucher is set to true
redemption Boolean Yes True: Indicates that the voucher is redeemable
voucher Boolean Yes True: Indicates that the voucher has been assigned to the customer

API Validations on the values

Field Description
itemTaxTotal This should be the total of all the taxes in the items (Sum of items.tax*items.qty)
itemDiscountTotal This should be the total of all the discounts in the items (Sum of items.discount.amount*items.qty)
billed This should be a sum of all items, taxes and extras, that is,

Sum(items.unitPrice*qty)+ Sum(extras.amount)+ billTax+ itemTaxTotal

paid This should be billed-billDiscount-itemDiscountTotal-redeemed

Example request

PUT http://[subdomain].urbanbuz.com/transaction/transactions/submit

{

 "customer": {
   "accountId": "03000000252",
   "phone": "971551467246",
   "email": "john@email.com",
 },
 "receipt": "T3HH17E7E1GK113474AQQ4J",
 "operatorId": "111111",
 "openTime": "2018-09-07 20:01:01",
 "closeTime": "2018-09-07 20:01:33",
 "billed": 1260,
 "paid": 1060,
 "redeemed": 200,
 "billDiscount": 0,
 "itemDiscountTotal": 0,
 "billTax": 0,
 "itemTaxTotal": 60,
 "deviceId": "301", 
 "items": [
   {
     "sku": "9999999",
     "name": "Product Name",
     "qty": 1,
     "unitPrice": 1200,
     "tax": 60,
    }
   ],
     "payments": [
         {
       "name": "AED_CURRENCY",
       "typeName": "Cash",
       "referenceId": null,
       "amount": 1060,
      "redemption": false,
       "voucher": false
     },
   {
     "name": "VOUCHER_REDEMPTION",
     "typeName": "Voucher",
     "referenceId": "7kwPsl",
     "amount": 200,
     "redemption": true,
     "voucher": true
   }
  ]
 }

Example response

{
   "status" : "success"

}

Cancel transaction

URL Method Returns Permission
http://[subdomain].urbanbuz.com/transaction/transactions DELETE
  • 200 - successful
  • 400 - bad request
  • 401 - not authorized
  • 500 - internal server error
Authentication

Request elements

Parameter Type Required Description
receipt String Yes Receipt of the transaction
openTime Date Yes Opentime of the transaction

Example request

DELETE http://[subdomain].urbanbuz.com/transaction/transactions

{

 "receipt": "123987",
 "openTime": "2017-05-14 10:33:15"

}

Example response

{
 "status": " SUCCESS"

}

Order

Submit order

URL Method Returns Permission
http://[subdomain].urbanbuz.com/transaction/orders/submit PUT
  • 1004: The following field is not unique
  • 1006: The following fields are invalid
  • 1002: Fields are empty
Authentication

Request elements

Parameter Type Required Description
customer.accountId String Yes Unique identity assigned to the customer
customer.phone String Yes Phone number of the customer
customer.email String Yes Email ID of the customer
receipt String Yes Transaction’s unique identity
openTime Date Yes Transaction’s open time
closeTime Date Yes Transaction’s time of closing
operatorId String No Cashier’s unique identity
operatorName String No Cashier’s name
deviceId String No Unique identity of the POS terminal
deviceName String No Name of the POS terminal
billed Decimal Yes Transaction’s gross total
paid Decimal Yes Transaction’s net paid
redeemed Decimal Yes Transaction’s net paid in loyalty redemption
billDiscount Decimal Yes Transaction’s total bill level discount
itemDiscountTotal Decimal Yes Transaction’s total item level discount
billTax Decimal Yes Transaction’s total bill level tax
itemTaxTotal Decimal Yes Transaction’s total item level tax
items.sku String Yes Line item’s unique identifier
items.qty Decimal Yes Line item’s quantity
items.unitPrice Decimal Yes Line item’s gross unit price
items.discount.amount Decimal Yes Line item’s discount amount
payments.typeName String Yes Payment type (e.g. Cash)
payments.amount Decimal Yes Payment amount

Example request

PUT http://[subdomain].urbanbuz.com/transaction/orders/submit

{

   "customer" : {
       "accountId"     : "f64f2940-fae4-11e7-8c5f-ef379131"
   },
   "receipt"           : "REC-001",
   "openTime"          : "2018-01-31 11:01:21",
   "closeTime"         : "2018-01-31 11:01:21",
   "operatorId"        : "STAFF001",
   "operatorName"      : "Jad",
   "salesPersonId"     : "STAFF001",
   "salesPersonName"   : "Jad",
   "deviceId"          : "POS001",
   "deviceName"        : "Front-desk",
   "billed"            : 105,
   "paid"              : 85,
   "redeemed"          : 0,
   "billDiscount"      : 0,
   "itemDiscountTotal" : 20,
   "billTax"           : 0,
   "itemTaxTotal"      : 5,
   "items" : [{
       "sku"           : "Item A",
       "qty"           : 2,
       "unitPrice"     : 50,
       "tax"           : 5,
       "discount" : {
           "amount"    : 20
       }
   }],
   "payments" : [{
       "typeName"      : "Cash",
       "amount"        : 80
   }],
   "extras" : [{
       "name"      : "Delivery Charge",
       "amount"        : 5
   }]

}

Example response

{
   "status" : "success"

}

Update order status

URL Method Returns Permission
http://[subdomain].urbanbuz.com/transaction/orders/status PUT
  • 1002: Fields are empty
Authentication

Request elements

Parameter Type Required Description
receipt String Yes Transaction’s unique identifier
status Decimal Yes Status of the placed order: Confirmed/Dispatched/Delivered/Canceled

Example request

PUT http://[subdomain].urbanbuz.com/transaction/orders/status

{

   "receipt"           : "REC-001",
   "status"            : "confirmed"

}

Example response

{
   "status" : "success"

}


Customer profile

Get customer profile

This call is executed to obtain information about registered customer.

URL Method Returns Permission
http://[subdomain].urbanbuz.com/customer/online/{token}/profiles GET
  • 200: Successful
  • 400: Bad request
  • 401: Not authorized
  • 500 Internal server error
Authentication

Request elements

Parameter Type Required Description
token String Yes Token received as query parameter

Example request

GET http://[subdomain].urbanbuz.com/customer/online/abc123/profiles

Example response

{
   "customer" : {
       "gender"             : "M",
       "first"              : "Jad",
       "last"               : "Hajj Obeid",
       "phone"              : "971557802482",
       "email"              : "jad@urbanbuz.com",
       "birth_date"         : "1970-12-01"
       "nationality"        : "LB",
       "country"            : "AE",
       "state_city_emirate" : "LB",
       "home_location"      : "Tecom",
       "work_location"      : "Discovery Gardens",
       "pin"                : "1234"
   }

}

Update customer profile

To update user profile, you will receive an email with a link redirecting to the website, along with a token received as a query parameter. This token value needs to be used with the API call to update customer profile and retrieve existing profile to pre-fill the form.

URL Method Returns Permission
http://[subdomain].urbanbuz.com/customer/online/{token}/profiles PUT
  • 200: Successful
  • 400: Bad request
  • 401: Not authorized
  • 500 Internal server error
Authentication

Request elements

Parameter Type Required Description
token String Yes Token received as query parameter
gender String Yes Gender
first String Yes First name
last String No Last name
phone String Yes Phone number
email String Yes Email
birth_date Date Yes Date of birth
nationality String Yes Nationality
country String Yes Country of residence
state_city_emirate String No State or city or emirate of residence
home_location String No Home location
work_location String No Work location

Example request

PUT http://[subdomain].urbanbuz.com/customer/online/abc123/profiles

{

   "customer" : {
       "gender"             : "M",
       "first"              : "Jad",
       "last"               : "Hajj Obeid",
       "phone"              : "971557802482",
       "email"              : "jad@urbanbuz.com",
       "birth_date"         : "1970-12-01"
       "nationality"        : "LB",
       "country"            : "AE",
       "state_city_emirate" : "LB",
       "home_location"      : "Tecom",
       "work_location"      : "Discovery Gardens",
       "pin"                : "1234"
   }

}

Example response

{
   "status" : "SUCCESS"

}

Send Update Profile Email

This call is executed to send an Email after a customer profile is updated.

URL Method Returns Permission
http://[subdomain].urbanbuz.com/customer/online/email/update_profile POST
  • 200: Successful
  • 400: Bad request
  • 401: Not authorized
  • 500 Internal server error
Authentication

Request elements

Parameter Type Required Description
email String Yes Email ID of the customer

Example request

PUT http://[subdomain].urbanbuz.com/online/email/update_profile

{

   "email": "abc@urbanbuz.com"
   }

Example response

{
   "status" : "SUCCESS"

}

Schedule campaign

Campaigning is done as part of marketing strategy. Campaigns are categorized as generic (Email and SMS) and voucher campaign. The schedule campaign API lets you schedule a campaign for customers as part of marketing either by following your business marketing calendar or by scheduling based on an event of local marketing importance.

URL Method Returns Permission
http://[subdomain].urbanbuz.com/marketing/campaigns POST
  • 1002: Fields are empty
  • 1010: At least one of the following fields is required
Authentication

Request elements

Parameter Type Required Description
title String Yes Title of the campaign (example: Skin Products Marketing)
channel Number Yes Channel represents SMS or Email ( 1 For SMS and 2 For Email)
countries List Yes List of countries targeted
category String Yes Communication Category ID (This will be shared by UrbanBuz through a lookup values or an API call)
communication.subject String Yes Subject of the Email. Mandatory if the channel is Email
communication.body String Yes Campaign content
communication.senderId String Yes Sender ID of the Campaign (Eg:- Kaya Clinic for SMS , no-reply@kayame.net for Email)
schedule.date Date Yes Date and time of the campaign to be send (Eg: 2018-05-20 15:30:00)
schedule.timeZone String Yes Time zone of the schedule
target String Yes Name of the target file uploaded

Example request

POST http://[subdomain].urbanbuz.com/marketing/campaigns

{

 "title": "We Miss you",
 "channel": 2,
 "countries": [
   {
     "countryIso": "AE"
   },
   {
     "countryIso": "KW"
   }
 ],
 "category": "10",
 "communication": {
   "subject": "We Miss You",
"body": "

Dear %%first%% We miss you

",
   "senderId": "Kaya"
 },
 "schedule": {
   "date": "2018-05-20 17:30:00",
   "timeZone": "Asia/Dubai"
 },
 "target": "kaya/Campaign_1527683113.csv"

}

Example response

{
   "status" : "success",
   "campaign" : {
        "campaignId" : "f64f2940"
   }

}

File Structure

SMS Email
"971551467246"

"971526985698"

"971544585784"

"971508878179"

"971527844678"

"email1@email.com"

"email2@email.com"

"email3@email.com"

"email4@email.com"

"john@email.com"

"mariyam@gmail.com"


Appointment

Submit appointment

Validations:

  • Reference number should be mandatory and unique across the branch.
  • Customer Object should have any of the following identifiers: phone/email/customerId
  • Line items of the appointment should be added to the “items” array of line item object.
  • “Sku” will be mandatory for each line item.
URL Method Returns Permission
http://[subdomain].urbanbuz.com//appointments/submit POST
  • 200 - successful
  • 400 - bad request
  • 401 - not authorized
  • 500 - internal server error
Authentication

Request elements

Parameter Type Required Description
customer_id String Yes Unique identity assigned to the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
referenceNumber String Yes Reference number for the appointment made
generated Date Yes Date and time when the appointment was made and registered
start Date Yes Start date and time of the appointment
end Date Yes End date and time of the appointment
rebooking Boolean Yes False indicates no rebooking is permitted for the booked appointment
operatorId String Yes ID of the staff who recorded the appointment
operatorName String Yes Name of the staff who recorded the appointment
deviceId String Yes The Id of the device that was used to register the appointment
deviceName String Yes Name of the device that was used to register the appointment
status Boolean Yes open/confirmed/closed/canceled/no-show/deleted: Status of the booked appointment
receipt String Yes The appointment receipt
source String Yes The medium through which the appointment was made (online booking)
sku String Yes Unique identifier for the service purchased (appointment)
name String Yes Name of the consulting doctor
duration String Yes Duration of the appointment
consultantId String Yes Unique identity of the consulting doctor
consultantName String Yes Name of the consulting doctor
consultantType String Yes Type of consultant (doctor)

Example request

POST http://[subdomain].urbanbuz.com//appointments/submit

{

 "customer": {

"customer_id": "BSNS-10249", "phone": "971581111148", "email": "jhon2@email.com"

 },
 "referenceNumber": "APPO-2017-10-19-001",
 "generated": "2017-10-22 10:33:15",

"start": "2017-11-14 10:00:00",

 "end": "2017-11-14 11:00:00",
 "rebooking": false,
 "operatorId": "Moo-Foo",
 "operatorName": "Moo Operator",
 "deviceId": "Foo Device",
 "deviceName": "Foo Device Name",
 "status": "open/confirmed/closed/canceled/no-show/deleted",
 "checkin": "2017-05-14 10:33:15",
 "receipt": "BSNS-201705141056",
 "source": "Online Booking",
 "items": [

{

 	"sku": "DR-CONSU-001",
 	"name": "Doctor Consultant",
 	"start": "2017-11-14 10:00:00",
 	"end": "2017-11-14 11:00:00",
 	"duration": 30,
 	"consultantId": "DR-001",
 	"consultantName": "John",
           "consultantType": "Doctor"

}

 ]

} }

Example response

{
   "status" : "success"

}

Update appointment status

This API call allows to change the status of an existing transaction. The reference number will be the key for the update.

URL Method Returns Permission
http://[subdomain].urbanbuz.com/appointments/status PUT
  • 200 - successful
  • 400 - bad request
  • 401 - not authorized
  • 500 - internal server error
Authentication

Request elements

Parameter Type Required Description
customer_id String Yes Unique identity assigned to the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
referenceNumber String Yes Reference number for the appointment made
checkin String Yes Checkin by the customer
status String Yes Status of the appointment (closed)

Example request

PUT http://[subdomain].urbanbuz.com//appointments/submit

{

"customer": {

"customer_id": "BSNS-10249", "phone": "971581111148", "email": "jhon2@email.com"

 },
 "referenceNumber": "BSNS-201705141033",
 "checkin": "2017-05-14 10:33:15",
 "status": "closed"

}

Example response

{
   "status" : "success"

}

Send OTP and validate redemption

URL Method Returns Permission
http://[subdomain].urbanbuz.com/program/accounts/otp/loyalty POST
  • 1006: The following fields are invalid
Authentication

Request elements

Parameter Type Required Description
accountId String Yes Account ID of the Customer
redemption.value BigDecimal Yes Value of the Redemption

Example request

POST http://[subdomain].urbanbuz.com/program/accounts/otp/loyalty

{

 "accountId": "ba215440-430d-11e8-842f-0ed5f89f718b",
 "redemption": {
   "value": "16.5"
 }

}

Example response (Success)

{
 "status": "success",
 "otp": "2459",
 "redemption": {
   "point": "1650",
   "value": "16.5"
 },
 "loyalty": {
   "program": {
     "name": "Loyalty Program Name",
     "logo": " https://urbanbuz.com/images/loyalty_program_1.jpg "
   },
   "tier": {
     "name": "Loyalty Tier 1",
     "logo": "https://urbanbuz.com/images/loyalty_tier_1.jpg",
     "order": 1,
     "expiry": "2019-01-01"
   },
   "wallets": [
     {
       "countryIso": "AE",
       "currency": "AED",
       "point": 1570,
       "value": 15.75
     }
   ],
     "redeemable": {
     "point": 1000,
     "value": 10,
     "currency": "AED"
 },
  "expiry": {
     "point": 256,
     "date": "2018-07-03"
 },
 "reason": null

}

Example response (Failure)

{
 "status": "failure",
 "reason": {
   "errorCode": "1017",
   "errorMessage": "Insufficient points"
 },
 "otp": null,
 "loyalty": {
   "program": {
     "name": "Loyalty Program Name",
     "logo": " https://urbanbuz.com/images/loyalty_program_1.jpg "
   },
   "tier": {
     "name": "Loyalty Tier 1",
     "logo": "https://urbanbuz.com/images/loyalty_tier_1.jpg",
     "order": 1,
     "expiry": "2018-01-01"
   },
   "wallets": [
     {
       "countryIso": "AE",
       "currency": "AED",
       "point": 1575,
       "value": 15.75,
       "expiry": "2018-05-03"
     }
   ]
 }

}

Reports APIs

The following sections describe the reporting API calls.

Fetch and export campaigns

This API call is made to retrieve all the details pertaining to a scheduled campaign (SMS campaign or Email campaign) and export these details to obtain the statistics of the scheduled campaigns. The campaign details mainly include:

  • Campaign scheduled date
  • Location where the campaign is scheduled
  • Count of sent, delivered and undelivered campaigns, and so on
URL Method Returns Permission
http://[subdomain].urbanbuz.com//reports/campaigns?export=true POST
  • 1005: No data found in the database for the sent request parameters
Authentication

Request elements

Parameter Type Required Description
start Date Yes Start date and start time of the SMS/Email campaign schedule
end Date Yes End date and end time of the SMS/Email campaign schedule
resultEndPoint String Yes The endpoint to update when the result is ready
export Boolean Yes To obtain the statistics of the scheduled campaign in the form of a csv file structure.

Example request

POST http://[subdomain].urbanbuz.com/program/reports/campaigns?export=true

{

 "start": "2018-09-10 00:00:00",
 "end": "2018-09-10 23:59:59,
 "resultEndPoint": "https://[subdomain].urbanbuz.com/campaigns/results"

}

Example request that generates the csv file (displaying the details of the campaign) when the parameter value export is set to be true.

POST http://company.com/campaigns/results

{ "jobId": "a1fTstz347",

"status": "Generated",

"fileName": Campaign_SMS_a1fTstz347_20180909.csv",

}

Example response

{
 "totalCount": 6,
 "status": "Generating",
 "fileName": "Campaign_SMS_a1fTstz347_20180909.csv",  
 "jobId":1246789454645,
 "data": [
   {
     "campaignId": "a1fTstz347",
     "campaignDescription":"Discount on bags"
     "channel": "SMS",
     "scheduled": "2018-09-09 14:00:00",
     "lastUpdated":"2018-09-10 11:25:00",
     "timeZone": "Asia/Dubai",
     "sent": "15000",
     "delivered": "13000",
     "undelivered": "2000",
     "filters": {
       "location": {
         "country": [{
             "countryIso": "AE",
             "name": "United Arab Emirates"
           }
         ],
         "brand": [{
             "name": "Elann"
           }
         ],
         "profile": [{
             "phoneCountry": "AE"
           },
           {
             "gender": "M"
           }
         ],
         "transaction": [{
             "active": {
               "from": "2017-01-01"
             }
           }
         ]
       }
     }
   }
 ]

}

Fetch accounts

URL Method Returns Permission
http://[subdomain].urbanbuz.com///reports/accounts?page={page}&size={size} POST
  • 1005: No data found in the database for the sent request parameters
Authentication

Request elements

Parameter Type Required Description
start Date Yes Start date and start time of retrieving data
end Date Yes End date and end time of retrieving data

Example request

POST http://[subdomain].urbanbuz.com/program/reports/accounts?page=1&size=10

{

"start": "2017-05-14 10:33:15",

"end": "2017-05-14 10:33:15 }

Example response

{

"pageNumber": 1,

"pageSize": 3,

"totalCount": 2242,

"data": [

{

"profile": {

"phone": "971506611149", "email": null,

"accountId": "ADBC29712",

"first": "Saeed",

"last": "Mohammed Alzaabi",

"birthdate": "1986-04-05",

"gender": "M",

"city": null,

"country": null,

"nationality": null,

"language": null,

"businessFields": {

"title": "Mr.",

"ethnicity": "Asian"

}

},

"originated": {

"brand": "Ghawali",

"name": "Ghawali-DUBAI MALL",

"branchCode": "13003",

"countryName": "United Arab Emirates",

"countryIso": "AE"

}

}

]

}

Fetch vouchers

Voucher is a type of a reward provided to customers. You can create vouchers to award your customers based on different criteria and to encourage a certain behavior. This API fetches the voucher issued/redeemed/expired within a given time range.

URL Method Returns Permission
http://api3.urbanbuz.com/program/reports/vouchers?page=1&size=100 POST
  • 400: bad request
  • 404: Given Resource not found
Authentication

Request elements

Parameter Type Required Description
start String Yes Start date to fetch the vouchers
end String Yes End date to fetch the vouchers

Response elements

- - - - - - - -
Parameter Type Required Description
code String Yes This is the voucher code
issued Date Yes Issued date of the voucher
redeemed Date No Redeemed date if the voucher is redeemed
expiry Date Yes Expiry date of the voucher
enabled boolean Yes True for enabled, false for disabled
issuedBranch Object Yes Details of the branch issuing the voucher
redeemedBranch Object No Branch details where the voucher was redeemed
campaign Object No Campaign title for which the voucher was issued
reward Object No Reward title for which the voucher was issued
voucher Object Yes Voucher details
voucher.title String Yes Voucher title
valueFixed Integer No Value if it is a fixed value voucher
valueDiscount Integer No Discount in percentage
redeemableBranchList Object No List of branches where voucher can be redeemed
country Object Yes Country for which the voucher was setup
brand Object Yes Brands for which the voucher was setup
customer Object Yes Details of the customer (phone/email/customer id) to whom the voucher is issued

Example request

POST http://api3.urbanbuz.com/program/reports/vouchers?page=1&size=100

{

  "start" : "2018-04-24 16:00:00",
   "end" : "2018-04-24 16:10:00"

}

Example response

{
  "pageNumber": 1,
 "pageSize": 100,
 "totalCount": 8,
 "offset": 0,
 "data": [
   {
     "id": 0,
     "code": "2cJRhV",                  
     "issued": "2018-04-24 16:07:00",    
     "redeemed": null,       
     "expires": "2019-04-24 16:07:00",  
     "enabled": true,
     "issuedBranch": {
        "brand": "Zippy",
        "name": "Dubai Mall",
        "branchCode": "S069",
        "countryIso": "AE",
      },
     "redeemedBranch": null,
     "campaign": {
        "title": "First Shopping voucher"
      }
     "reward": {
        "title": "First Shopping reward"
      },
     "voucher": {
       "title": "AED 100 Voucher UAE",     
       "icon": "https://newcem.urbanbuz.com/upload/images/1508139174.png",
       "valueFixed": 0,
       "valueDiscount": 10,                
       "redeemableBranchList": [
        {
        "brand": "Zippy",
        "name": "Dubai Mall",
        "branchCode": "S069",
        "countryIso": "AE",
        },
        {
        "brand": "Zippy",
        "name": "Marina Mall",
        "branchCode": "S052",
        "countryIso": "AE",
       }
       ],
       "country": {
         "countryIso": "AE",
         "countryName": "United Arab Emirates"
       },
       "brands": [
         "Brands",
         "POP"
       ]
     },
     "customer": {  
       "phone": "971507571736",
       "email": "mmm2111@yahoo.com",
       "customerId": "151501"
     }
   }
 ]

}

Fetch transactions

URL Method Returns Permission
http://[subdomain].urbanbuz.com/program/reports/transactions?page={page}&size={size} POST
  • 1005: Data not found
Authentication

Request elements

Parameter Type Required Description
start Date Yes Start date and time
end Date Yes End date and time

Example request

POST http://[subdomain].urbanbuz.com/program/reports/transactions?page=1&size=10

{

 "start": "2017-05-14 10:33:15",
 "end": "2017-05-14 10:33:15

}

Example response

{
 "pageNumber": 1,
 "pageSize": 1,
 "totalCount": 28,
 "offset": 0,
 "data": [
   {
     "transaction": {
       "receipt": "971552456810-18",
       "openedAt": "2018-01-22 13:59:00",
       "closedAt": null,
       "billed": 210,
       "paid": 100,
       "redeemed": 0,
       "billDiscount": 0,
       "itemDiscountTotal": 0,
       "billTax": 0,
       "itemTaxTotal": 0,
       "operatorId": null,
       "operatorName": null,
       "deviceId": "T004",
       "deviceName": "OASIS COUNTER 1",
       "items": [
         {
           "id": null,
           "sku": "S2597",
           "name": "SUIT2/375",
           "description": null,
           "type": "P",
           "inventoryId": null,
           "inventoryCategoryId": null,
           "qty": 1,
           "unit": null,
           "unitPrice": 60,
           "tax": null,
           "lineAmount": 60,
           "discount": null,
           "customFields": null
         },
         {
           "id": null,
           "sku": "S2600",
           "name": "SUIT2/895",
           "description": null,
           "type": "P",
           "inventoryId": null,
           "inventoryCategoryId": null,
           "qty": 1,
           "unit": null,
           "unitPrice": 100,
           "tax": null,
           "lineAmount": 100,
           "discount": null,
           "customFields": null
         },
         {
           "id": null,
           "sku": "S2599",
           "name": "SUIT2/585",
           "description": null,
           "type": "P",
           "inventoryId": null,
           "inventoryCategoryId": null,
           "qty": 2,
           "unit": null,
           "unitPrice": 25,
           "tax": null,
           "lineAmount": 50,
           "discount": null,
           "customFields": null
         }
       ],
       "payments": [
         {
           "id": null,
           "name": null,
           "typeId": null,
           "typeName": "Master Card",
           "date": null,
           "paymentAt": null,
           "amount": 100,
           "referenceId": null,
           "redemption": false,
           "customFields": null
         }
       ],
       "extras": null,
       "customFields": null
     }
   }
 ]

}