A new API has been developed to specifically allow Getting Personal (GP) to put orders into OMS using their own bespoke data format.

Partial Orders

GP send the order header and lines separately, so an order for three lines will be sent as four separate requests, potentially not in any particular sequence.

This means that an order may exist in the system in a partial state. The status of the partial order will be On System Hold until all information has been received.

Primary and Secondary Companies

GP have been instructed to use the 18624 company reference ID when creating orders using the new API. This company will be used as the primary company (retailer) on all of their orders.

In addition, GP will specify which secondary company (supplier) to use for the order using their own supplier reference code.

This means that for each supplier used by GP, a corresponding dropship company must exist in OMS with GP’s supplier reference set as the dropship company’s external reference.

For example, 18625 is Getting Personal - Promotional Ceramics and has GP’s supplier reference (1) set as the external reference.

The dropship company must have 18624 set as the retailer.

If the company hierarchy is not correct then the secondary company will not be automatically determined and the order will exist in an error state until it is manually fixed.

GP are responsible for splitting orders by supplier before sending the order details via the API.

SKU Mapping

No SKU mapping is required. GP must send either the CPP supplier SKU or retailer SKU verbatim.

Supplier Mapping

No manual supplier map is required.

The supplier map is determined automatically based on the company hierarchy (the available suppliers are derived from the dropship companies that have 18624 set as the retailer).

Technical Details

There are two endpoints:

https://api-sl-gp.custom-gateway.net/order-header
https://api-sl-gp.custom-gateway.net/order-line

The API is locked down to GP’s own IP addresses and is only available via HTTPS.

The API is a ZF3 CPP/OMS module and resides in zf3/module/Apis/GettingPersonal/src.

Example Usage

$ cat GP/CustomGateway-orderheader.json 
{
	"orderId": 1,
	"orderlineIds": [ 1, 2 ],
	"brand": "gettingpersonal",
	
	"supplier": {
		"name": "Promotional Ceramics",
		"id": 1
	},

	"shippingAddress": {
		"recipientName": "Andy Scott",
		"line1": "Getting Personal",
		"line2": "Southmoor Industrial Estate, Southmoor Road",
		"city": "Manchester",
		"county": "Greater Manchester",
		"postcode": "M23 9XD",
		"country": "United Kingdom",
		"countryIsoCode": "GB"
	},

	"customer": {
		"name": "Andrew Scott",
		"telephone": "0161 947 5915",
		"emailaddress": "ascott@gettingpersonal.co.uk"
	},

	"slaStartDate": "2017/07/17 22:26:45"
}

$ curl -d @GP/CustomGateway-orderheader.json -H 'content-type: application/json' "https://api-sl-gp.custom-gateway.net/order-header" -k -H 'authorization: basic 18624:APIKEY'
{"order":{"id":2800491,"ref":"j9pb38kryt", ... "status_name":"System Hold"}}

$ cat GP/CustomGateway-orderline-text.json 
{
	"orderId": 1,
	"orderlineId": 2,
	"orderlineIds": [ 1, 2 ],
	"orderlineType": "text",
	"expectedDespatch": "2017/07/19",

	"personalisation": [ {
		"key": "labeltext",
		"value": "Afternoon"
	}, {
		"key": "giftbox",
		"value": true
	} ],

	"supplierSku": "comicctea",
	"quantity": 1,
	"product": {
		"name": "Personalised Tea Tin - Time For Tea (Green)",
		"id": 28991,
		"imageUrl": "https://media.gettingpersonal.co.uk/263386/images/products/91/28991/rwf/personalised-tea-tin---time-for-tea-green_a.jpg?width=700"
	},

	"pdf": null 
}

$ curl -d @GP/CustomGateway-orderline-text.json -H 'content-type: application/json' "https://api-sl-gp.custom-gateway.net/order-line" -k -H 'authorization: basic 18624:APIKEY'
{"order":{"id":2800491, ... }}

$ cat GP/CustomGateway-orderline-pdf.json
{
	"orderId": 1,
	"orderlineId": 1,
	"orderlineIds": [ 1, 2 ],
	"orderlineType": "pdf",
	"expectedDespatch": "2017/07/19",

	"personalisation": [ {
	  "key": "labeltext",
	  "value": "Afternoon"
	}, {
	  "key": "giftbox",
	  "value": true
	} ],

	"supplierSku": "comicctea",
	"quantity": 1,
	"product": {
		"name": "Personalised Tea Tin - Time For Tea (Green)",
		"id": 28991,
		"imageUrl": "https://media.gettingpersonal.co.uk/263386/images/products/91/28991/rwf/personalised-tea-tin---time-for-tea-green_a.jpg?width=700"
	},

	"pdf": {
		"barcodeId": "1",
		"file": "<<base64 encoded pdf>>",
	}
}

$ curl -d @GP/CustomGateway-orderline-pdf.json -H 'content-type: application/json' "https://api-sl-gp.custom-gateway.net/order-line" -k -H 'authorization: basic 18624:APIKEY'
{"order":{"id":2800491, ... }}