Introduction
Welcome to Hancocks Family Merchants ("Hancocks") Business to Business ("B2B")!
Hancocks operates two B2B services. An Electronic Data Interchange ("EDI") involving the exchange of Extensible Markup Language ("XML") data files and an Application Programming Interface ("API") involving processing requests in JavaScript Object Notation ("JSON"). The API is detailed here.
API Overview
The B2B API portal is open to other businesses on the secure Uniform Resource Locator ("URL") address https://b2b.hancocks.co.nz and essentially works by processing information exchanges received on extensions of that URL and then issuing processing outcome responses. Both requests and responses are in JSON format and so the Multipurpose Internet Mail Extensions ("MIME") content type should be "application/json" and the data should use Universal Character Set Transformation Format 8 bit ("UTF-8") character encoding.
The service is available 24 hours every day excluding database maintenance periods.
API Information Exchange Requests
There are two parts to information exchange requests. The first is the URL that the request is sent to as that identifies the request. Requests that are currently supported are listed in the following table and detailed in more depth further on in this API.
| Request Method | Request URL |
|---|---|
| Stock List | https://b2b.hancocks.co.nz/stocklist |
| Stock Level | https://b2b.hancocks.co.nz/stocklevel |
All requests must comply with the security protocol agreed between Hancocks and the B2B user.
The second part of the information exchange request is the data payload sent to the URL. The JSON formatted payload is defined for each particular request, however, not all requests have a payload prerequisite.
API Information Exchange Responses
The primary API Response to an API Request is the Status Code as follows:
| Code | Status | Context |
|---|---|---|
| 200 | OK | The Request has been successfully handled, parse the Response's JSON payload for information |
| 201 | CREATED | The Request has been successfully processed, parse the Response's JSON payload for details |
| 400 | BAD REQUEST | The Request is invalid - usually caused by the request not containing a JSON payload with the requisite information |
| 401 | UNAUTHORISED | The Request has not passed the agreed security protocol for access |
| 404 | NOT FOUND | The Request URL is not associated with an API Request URL |
| 500 | INTERNAL SERVER ERROR | Hancocks failed to process the Request - this issue would have been logged for investigation |
| 503 | SERVICE UNAVAILABLE | Hancocks B2B API is offline - most likely for database maintenance |
The response JSON is a JSON object containing a JSON object "response". The structure of the response object is specified in the table below:
| Key Name | Value Type | Specification |
|---|---|---|
| method | string | The information exchange method/service called, which will correspond to the URL that the request was sent to |
| status | string | The outcome of the information exchange, "OK" confirms a successful request |
| comment | string | Optional |
| data | array / object | Contains information retrieved or outcomes of processing as per the API for the particular information exchange method/service request |
An abbreviated example of a JSON information retrieval response is:
"status":"OK",
"comment":"",
"data":[
Stock List
Stock List is an information retrieval request involving sending a request to the URL https://b2b.hancocks.co.nz/stocklist as discussed in the API Information Exchange Requests and API Information Exchange Responses sections above.
Upon a successful 200 status code response, the structure of the data component of the response object is an array of JSON objects. Each object represents an active stock item having the structure specified in the table below:
| Key Name | Value Type | Specification |
|---|---|---|
| stockcode | string | The Hancocks stockcode for supplying this item as a single pack. Refer to pack for the number of individual units in a pack. A stockcode may be prefaced by "KIT" where the item is sold as a kit |
| casecode | string | The Hancocks case stockcode for supplying this item as a case of packs. Refer to case for the number of individual units in a case |
| barcode | string | The GTIN barcode for unit pack |
| brand | string | The brand name of this stock item |
| stockname | string | The name of this stock item |
| description | string | A description of this stock item |
| alcohol | string | Alcohol percentage by volume of this stock item |
| pack | integer | The number of individual units in a pack of this stock item. Pack can be 1 such as for a single bottle of wine |
| case | integer | The number of individual units in a case of this stock item |
| vintage | string | The vintage year of this stock item's production - may be an empty string or "NV" for non-vintage |
| volume | string | The volume of each unit of this stock item inclusive of measurement unit such as "ml" for millilitres and "L" for litre |
| notes | string | (Tasting) notes pertaining to this stock item |
| variety | string | The variety of this stock item |
| style | string | The production style of this stock item |
| region | string | The region of the country that this stock item is produced in |
| country | string | The country that this stock item is produced in |
| image | string | The name of this stock item's image file on the Hancocks web server |
| imageURL | string | The URL to access this stock item's image file on the Hancocks web server |
| price | double | The current price in New Zealand dollars to buy a pack of this stock item from Hancocks. By default, the price is exclusive of freight and Goods and Services Tax ("GST") |
| caseprice | double | The current price in New Zealand dollars to buy a case of this stock item from Hancocks. By default, the price is exclusive of freight and "GST" |
| stocklevel | integer | If stocklevel data is available for your account group then it will be included here |
| awards | array | An array of strings being the names of any awards bestowed upon this stock item |
Stock Level
Stock level is an information retrieval request involving sending a JSON object to the URL https://b2b.hancocks.co.nz/stocklevel as discussed in the API Information Exchange Requests and API Information Exchange Responses sections above. For a stock level request the object must contain your Hancocks account number as a JSON integer and a JSON string of the stockcode that the stock level is to be returned for. An example of the request JSON object is as follows:
"stockcode":"yourHancocksStockcode"
The structure of the data component of the response object is a JSON object having the structure specified in the table below:
| Key Name | Value Type | Specification |
|---|---|---|
| basecode | String | The basecode used to find the stock level |
| stocklevel | Integer | The stock level for this stock item expressed as the number of units of currently in stock |
| stockReserved | Integer | The stock of this stock item exclusively reserved for you to sell expressed as the number of units reserved |