Panel

nameid	blue0

Table of Contents

Excerpt

Setup and Integration

The following sections include extensive and reference materials to aid POS system's developers for integrating any POS system with CRM.COM Rewards platform, using a set of recommended Web API concepts and methods provided by CRM.COM

Configuration

Authentication

Before performing any logical unit of work, an authentication token must be acquired and subsequently will be used by all other Web API methods in order to access and performed any operations in the system. All API requests must be made using a valid authentication token, otherwise such requests will fail

Acquiring an authentication token can be accomplished by using one of the following methods

Web API Key
Username & Password

Recommended Authentication Method

The recommended method of authentication is using Web API Keys of a "System Key" classification. Web API Keys are assigned to specific users in order to access a specific organization and can be used to authenticate users through Web API, resulting to an authentication token that can subsequently be used by other Web API calls, without any data restrictions

The authentication Web API call that should be performed is POST authentication/web_api_key/token (based on HTTP Basic Auth)

Web API Key Method Example

Note

icon	false
title	Reference

Visit API Authentication for more information

Using Fields Set

CRM.COM Web APIs offer the ability to select the fields that will be retrieved from each API method by specifying the "fields_set" input parameter

Using this parameter developers have the ability to filter the response object and retrieve only the fields that will be used for the desired implementation. If "fields_set" is not specified, then all fields of the response will be retrieved

The "fields_set" attribute is used for each call throughout the entire integration guide

Note

icon	false
title	Reference

Visit Introduction - Using Fields Sets for more information

Using Pagination

There are some API methods that retrieve a large number of entities, such as list API methods. Some of these CRM.COM API methods provide the option to apply pagination on the results retrieved

In such cases the API call should be constructed using the following input parameters

number_of_results: The number of results that can be retrieved through each call. The maximum number of results can be 50, and objects are returned in chronological order (oldest requests are retrieved fist)
offset: Defines the number of entities that should be skipped from the results. During the first call it should be set to 0 and then it should be increased based on the number of results that were retrieved

Note

icon	false
title	Reference

Visit Introduction - Using Pagination for more information

Integration Scenarios

Purchase and Spend Award Flow

The flow described below is an example of a POS integration with CRM.COM Rewards

...

Award and Spend Flow

No	Description	Web API Example	POS Conceptual Examples
Step 1 - Customer Identification
1	The customer is identified on the POS system by providing an

...

email address, a phone number, a card number, etc

Identifying a customer in CRM.COM (also referred as rewards participant) should be performed using the POST rewards_participants/show method

The following identification means can be used to identify a customer in CRM.COM

number: A unique number that is related to each rewards participant
access_token_identifier: An access token that is related to a rewards participant. An access token is the most common parameter to use for customer identification purpose, because it can be easily assigned to a rewards participant and usually is mapped to the customer's email address, phone number or card number

Code Block

title	POST Request

https://hostname/crmapi/rest/v2/rewards_participants/show

Code Block

title	Body
linenumbers	true
collapse	true

{
	"token": "{{token}}",
	"rewards_participant_identifier":{
		"access_token_identifier":{
			"authentication_code": "22265577"
		}
	},
	"fields_set": "accounts_receivable,wallet"
}

Prior Customer Identification

Image Modified

2

Once a customer is identified in CRM.COM, then the full information of the customer is returned back to the POS system

The following information can be displayed on the POS screen

The name of the customer (accounts_receivable.account_owner.name)
The available balance of the customer's wallet (wallet.balance)

Code Block

title	Response
linenumbers	true
collapse	true

{
	"data":{
		"wallet": {
			"number": "W0000000001,
			"balance": "10.00",
			...
		},      
		"accounts_receivable":{
			"life_cycle_state": "ACTIVE",
			"number": "400",
			"name": "John Doe",
			"id": "123456789"
			"account_owner":{
				"name": "John Doe",
				"first_name": "John"
				"last_name": "Doe",
				"life_cycle_state": "FINANCIAL",                
				"title": "Mr",
				"type": "PERSON",
				...
			},
			...
		}
	},
	"status":{
		"message": null,
		"description": null,
		"code": "OK"
	}
}

After Customer Identification

Image Modified

Step 2 - Preview Award and Spend Information (Optional)

No

Description

Web API Example

POS Conceptual Examples

1

Prior completing the sales transaction on POS, customer may request to know their available balance and the amount that are eligible to spend on the related transaction.

...

The preview method will determine whether the purchase customer event that will be submitted can be

...

performed (spend) by the Front-End System (i.e. POS) or by a Back-End System

...

Previewing such information should be performed using the POST customer_events/purchases/preview method, and the following information should be passed to CRM.COM

The related customer (accounts_receivable_identifier)
The sales transaction's reference number (reference_number)
The sales transaction's date (performed_on)
The sales transaction's merchant (performed_by_unit_identifier)
The sales transaction's items and the amount per each item (products_set)

Code Block

title	POST Request

https://hostname/crmapi/rest/v2/customer_events/purchases/preview

Code Block

title	Body
linenumbers	true
collapse	true

{
	"token": "{{token}}",
	"rewards_participant_identifier":{
		"access_token_identifier":{
			"authentication_code": "22265577"
		}
	},

	"reference_number": "REF0001",
	"performed_by_unit_identifier":{
		"name" : "Unit"
	},
	"performed_on": "2017-06-22T15:00:00",
	"products_set":[
		{
			"product_identifier":{
				"code": "Soft Drinks"
			},
			"quantity": 1,
			"total_amount": 10,
			"net_amount": 8,
			"vat_amount": 2
		},
		{
			"product_identifier":{
				"code":"Sandwiches"
			},
			"quantity": 10,
			"total_amount": 20,
			"net_amount": 26,
			"vat_amount": 4
		}
	],
	"fields_set": "total_additional_spend_amount,
		total_automatic_spend_amount,reduction_method,
		total_instant_spend_amount,
		total_award_amount"
}

Not Applicable

2

Once

...

performing such action is completed, the POS system can display the related award and spend amount information that are eligible for the current customer's basket products that were submitted to the POS

The following information can be displayed on the POS screen

The

...

reduction method (reduction_method)
The amount that will be spend automatically, without the customer's

...

title	Response
linenumbers	true
collapse	true

...

request (the sum of total_instant_spend_amount and total_automatic_spend_amount)
The amount that is available to be spend on that transaction (total_additional_spend_amount)
The amount to be awarded (total_award_amount)

Code Block

title	Response
linenumbers	true
collapse	true

{
	"data":{
		"total_

...

additional_spend_amount":

...

7.9,
		"total_

...

automatic_spend_amount": 0,
		"total_instant_spend_amount": 0,
		"total_award_amount": 0.08,
		"reduction_method": "FRONT_END_REDUCTION"
	},
	"status":{
		"message": null,
		"description": null,
		"code": "OK"
	}
}

After Preview

Image Modified


Step 3 - Submitting Sales Transaction

...

No	Description	Web API Example	POS Conceptual Example
and Award Customer
1	Once all products are registered in the POS, the sales transaction should be submitted in CRM.COM in the form of a purchase customer event. Creating such customer event, CRM.COM will validate whether the purchased items are eligible to be awarded by a reward offer and credit the customer's wallet balance

Submitting a purchase event in CRM.COM should be performed using the POST customer_events/purchases/create method, and capture the following information

The related customer (accounts_receivable_identifier)
The sales transaction's reference number (reference_number)
The sales transaction's date (performed_on)
The sales transaction's merchant (performed_by_unit_identifier)
The sales transaction's items and the amount per each item (products_set)
Whether the customer event should be processed immediately, depending various business processes or not (process_immediately) - in most cases processing is immediately
Optionally, the identifier of the POS can be specified (external_system)

Note
Products should already exist in CRM.COM in order for the POS to make transactions for them. In the event that a POS integration requires to perform transactions for such items, CRM.COM provides the ability to allow such transaction submission using a default product (everything is handled by CRM.COM without additional changes from the POS system)

Code Block

title	POST Request

https://hostname/crmapi/rest/v2/customer_events/purchases/create

Code Block

title	Body
linenumbers	true
collapse	true

{
	"token": "{{token}}",
	"accounts_receivable_identifier":{
		"number": "001"
	},

	"performed_by_unit_identifier":{
		"name":"Unit"
	},
	"performed_on":"2017-05-22T16:05:00",

	"process_immediately": true,
	"external_system": "POSID01",
	"reference_number":"REF00001",

	"products_set":[
		{
			"product_identifier":{
				"code": "Soft Drinks"
			},
			"quantity": 1,
			"total_amount": 10,
			"net_amount": 8,
			"vat_amount": 2
		},
		{
			"product_identifier":{
				"code": "Sandwiches"
			},
			"quantity": 4,
			"total_amount": 10,
			"net_amount": 8,
			"vat_amount": 2
		}
	],
	"fields_set":"number,total_awarded_amount,reference_number"
}

Not Applicable

2

Once the sales transaction submission is performed (purchase customer event creation), the POS system can proceed to the

...

spend step

...

The following information can be displayed on the POS screen

The amount that was awarded from the purchase (total_award_amount)
The amount that was automatically spend from the purchase (total_spend_amount)
The available balance of the customer's wallet after the purchase (initial wallet balance + total_award_amount - total_spend_amount)

Code Block

title	Response
linenumbers	true
collapse	true

{
	"data":{
		"number": "111",
		"total_awarded_amount": 20,
		"reference_number": "REF00001"
	},
	"status":{
		"message": null,
		"description": null,
		"code": "OK"
	}
}

After Customer is Awarded

Image Modified

Step 4 -

...

No	Description	Web API Example	POS Conceptual Example
Spend Awarded Amount
1	Customer may want to spend some of the available wallet amount

...

Spending a specific or the full awarded amount can be achieved by submitting a spend customer event in CRM.COM

The following information can be displayed on the POS spend request form

The amount that can be requested to be spent on that transaction (total_additional_spend_amount)
The minimum spend amount allowed to be spend per transaction (minimum_spend_amount_per_transaction)
The maximum spend amount allowed to be spend per transaction (maximum_spend_amount_per_transaction)

Submitting a spend request in CRM.COM should be performed using the POST customer_events/spend_requests/create method, and capture the following information

The related customer (accounts_receivable_identifier)
The related purchase customer event that was created above (purchase_customer_request_identifier)
The amount that is requested to be spend (spend_amount)
The sales transaction's date (performed_on)
The sales transaction's merchant (performed_by_unit_identifier)
Whether the customer event should be processed immediately, depending various business processes or not (process_immediately) - in most cases processing is immediately
Optionally, the identifier of the POS can be specified (external_system)

Code Block

title	POST Request

https://hostname/crmapi/rest/v2/customer_events/spend_requests/create

Code Block

title	Body
linenumbers	true
collapse	true

{
	"token": "{{token}}",
	"accounts_receivable_identifier":{
		"number": "001"
	},

	"performed_by_unit_identifier":{
		"name": "Unit"
	},
	"performed_on": "2017-05-12T11:41:00",

	"external_system": "POSID01",
	"process_immediately": true,

	"spend_amount": 10,
	"purchase_customer_request_identifier":{
		"number": "936"
	},

	"fields_set":"number,
		spend_amount,
		reduction_method,
		spend_reward_transaction"
}

Spend Request Form

Image Modified

2

Once the spend request is performed, it will return back the actual amount that was spent, which might be different than the amount that was requested to be spend

...

The following information will be used in the next step of reducing and closing the sales transactions

The actual amount that was spent (spend_reward_transaction.total_amount)

Code Block

title	Response
linenumbers	true
collapse	true

{
	"data":{
		"number": "294",
		"spend_amount": 10,
		"reduction_method": "FRONT_END_REDUCTION",
		"spend_reward_transaction":{
			"number": "205",
			"total_number": 7.9,
			"net_amount": 7.9,
			"vat_amount": 0,
			"life_cycle_state": "POSTED",
			...
		}
	},
	"status":{
		"message": null,
		"description": null,
		"code": "OK"
	}
}

After Spend Request

Image Modified

Step 5 - Closing the sales transaction

No

Description

Web API Example

POS Conceptual Example

1

Once the sales transaction (purchase customer event) and spend transaction (spend request customer event) are submitted successfully ,

...

the POS system can calculate the

...

total spend amount, reduce it from the total amount of the sales transactions, and close the sales transaction with the customer's payment

The

...

total spend amount is calculated as the sum of the following attributes

The actual amount that was spent (spend_reward_transaction.total_amount), as retrieved from the "spend_request/create" method, and
The amount that was spent automatically, which is the total_spend_amount as retrieved by the "purchases/create" method or from the sum of total_instant_spend_amount, total_additional_spend_amount and total_automatic_spend_amount as retrieved from the "purchases/preview" method

...

Note
The total_spend_amount is also the sum of total_instant_spend_amount, total_additional_spend_amount and total_automatic_spend_amount as retrieved by the "purchases/create" (all these three values are retrieved from the same method as well)

The calculated

...

total spend amount is deducted from the POS sales transaction by applying a discount on the sales transaction

...

Upon completion, the following information is displayed and printed on the customer's receipt

The amount that was awarded from the purchase (total_award_

...

Not Applicable

...

Receipt

Image Removed

amount retrieved by the "purchases/preview" or "purchases/create")
The wallet balance after the purchase. The new balance is calculated as the wallet's initial balance + awarded amount - total spend amount

Not Applicable

Receipt

Image Added

Amend Award and Spend Flow

Step 1 - Customer Identification

No

Description

Web API Example

POS Conceptual Examples

1

The customer is identified on the POS system by providing an email address, a phone number, a card number, etc and list all previous purchases

Retrieving such information from CRM.COM should be performed using the POST customer_events/purchases/list method

The following identification means can be used to identify a customer in CRM.COM and retrieve all his purchases

number: A unique number that is related to each rewards participant
access_token_identifier: An access token that is related to a rewards participant. An access token is the most common parameter to use for customer identification purpose, because it can be easily assigned to a rewards participant and usually is mapped to the customer's email address, phone number or card number

Code Block

title	POST Request

https://hostname/crmapi/rest/v2/customer_events/purchases/list

Code Block

title	Body
linenumbers	true
collapse	true

{
	"token": "{{token}}",
	"rewards_participant_identifier":{
		"access_token_identifier":{
			"authentication_code": "22265577"
		}
	},
	"fields_set": "number, performed_on"
}

Not Applicable

2

Once a customer is identified in CRM.COM, then the full information of the customer's purchases is returned back to the POS system

The following information for each purchase can be displayed on the POS screen

The number of each purchase transaction (number)
The performed date of each transaction (performed_on)

Code Block

title	Response
linenumbers	true
collapse	true

{
	"data":[
		{
			"number": "473",
			"performed_on": "2018-12-21T10:15:02"
		},
		{
			"number": "479",
			"performed_on": "2018-12-21T11:02:59"
		}
	],
	"status":{
		"message": null,
		"description": null,
		"code": "OK"
	}
}

Not Applicable

Step 2 - Amend Award and Spend

No

Description

Web API Example

POS Conceptual Examples

1

Cancelling a customer's purchase will result into amending the award and spend amounts that were related to that purchase

Performing such action should be executed using the POST customer_events/purchases/cancel method and provided the related purchase that should be cancelled

The following information should be passed to CRM.COM

The related customer event identifier that result into awarding and spending the customer (customer_event_identifier)

Code Block

title	POST Request

https://hostname/crmapi/rest/v2/customer_events/purchases/cancel

Code Block

title	Body
linenumbers	true
collapse	true

{
	"token": "{{token}}",
	"customer_event_identifier":{
		"number":"479"
	},
 
	"fields_set": "number, life_cycle_state"
}

Not Applicable

2

Once the purchase is cancelled, CRM.COM will return all related information to that transaction

The following information can be displayed on the POS screen

The number of the cancelled purchase (number)
The state of the date of each purchase (life_cycle_state)

Code Block

title	Response
linenumbers	true
collapse	true

{
	"data":{
		"number": "479",
		"life_cycle_state": "CANCELLED"
	},
	"status":{
		"message": null,
		"description": null,
		"code": "OK"
	}
}

Product Synchronization Flow

The flow described below is an example of synchronizing products from a POS system into CRM.COM

...

Product Synchronization can be achieved using existing CRM.COM Web API methods, where product information (as described previously) can be passed through a product parameter set

Note
The maximum number of products that can be synchronized per call is 1,000

No	Description	Web API Example	POS Conceptual Examples
Step 1 - Synchronize Products
1	Product synchronization on a POS system can be implemented as a batch process that is performed on a repeated basis (i.e. every day at 2 am), where product information is sent to CRM.COM

...

Submitting a product synchronization request in CRM.COM should be performed using the POST products/synchronise method, and capture the following information

The product synchronization definition that describes how the products information from the POS system will be handled by CRM.COM (synchronisation_definition_identifier)
The POS products and their related attributes (code, description, family, brand, categories, etc) per each product (products_set)

...

Note
The maximum number of products that can be synchronized per call is 1,000

Code Block

title	POST Request

https://hostname/crmapi/rest/v2/products/synchronise

Code Block

title	Body
linenumbers	true
collapse	true

{
	"token": "{{token}}",
	"synchronisation_definition_identifier":{
		"alternative_code": "Product_Sync"
	},

	"products_set":[
		{
			"code" : "Orange Cookie",
			"alternative_code" : "10021",
			"description":"Cookie with orange cream",
		},
		{
			"code" : "Iced Caramel Latte",
			"alternative_code" : "20071",
			"description":"Latte with caramel syrup",
			"family_identifier" :{
				"code" : "Iced Coffee"
			}
		}
	],

	"fields_set":"unprocessed_products_set,processed_products_set"
}

Not Applicable

2

Once the product synchronization request is submitted and upon completion processing from the CRM.COM, the following information is returned (and handled accordingly by the POS system)

The products that were not processed by CRM.COM due to an error was thrown (unprocessed_products_set)
The products that were processed successfully by CRM.COM (unprocessed_products_set)

Code Block

title	Response
linenumbers	true
collapse	true

{
	"data": {
		"unprocessed_products_set": [
			{
				"error_description": "Error:Product Family (Iced Coffee) Not Found. - Description:The specified API value was not found.",
				"error_code": "NotFoundAPIValueException",
				"request_code": "Iced Caramel Latte"
			}
		],
		"processed_products_set": [
			{
				"code": "Orange Cookie",
				"request_code": "Orange Cookie",
				"id": "E15E0F60F5D147B28C8FD50ADE4E0116"
			}
		]
	},
	"status":{
		"message": null,
		"description": null,
		"code": "OK"
	}
}

Not Applicable

...

Versions Compared

Old Version 1

New Version Current

Key

Setup and Integration

Configuration

Authentication

Using Fields Set

Using Pagination

Integration Scenarios

Purchase and Spend Award Flow

Award and Spend Flow

Step 1 - Customer Identification

Step 2 - Preview Award and Spend Information (Optional)

Step 3 - Submitting Sales Transaction

and Award Customer

Step 4 -

Spend Awarded Amount

Step 5 - Closing the sales transaction

Amend Award and Spend Flow

Step 1 - Customer Identification

Step 2 - Amend Award and Spend

Product Synchronization Flow

Step 1 - Synchronize Products

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

Setup and Integration

Configuration

Authentication

Using Fields Set

Using Pagination

Integration Scenarios

Purchase and Spend Award Flow

Award and Spend Flow

Step 1 - Customer Identification

Step 2 - Preview Award and Spend Information (Optional)

Step 3 - Submitting Sales Transaction

and Award Customer

Step 4 -

Spend Awarded Amount

Step 5 - Closing the sales transaction

Amend Award and Spend Flow

Step 1 - Customer Identification

Step 2 - Amend Award and Spend

Product Synchronization Flow

Step 1 - Synchronize Products