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

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

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

Integration Scenarios

The flow described below is an example of a POS integration with CRM.COM Rewards, including both purchase and spend transactions

Award and Spend Flow

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

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

{
	"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"
	}
}

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

{
	"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"
}