B2B API

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
Order https://b2b.hancocks.co.nz/order
Order Status https://b2b.hancocks.co.nz/orderstatus

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:

{"response":
{
"method":"stocklist",
"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:

{"data":
{
"account":yourHancocksAccount,
"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

Order

Order is an information exchange request involving sending a request to the URL  https://b2b.hancocks.co.nz/order  as discussed in the API Information Exchange Requests and Information Exchange Responses sections above. For an Order request the data object must contain a JSON object of the order details and a JSON array of the order items that are being ordered. An abbreviated example of the request JSON object is as follows:

{"data":
{"orderdetails":
…
}
{"orderitems":
[
…
]
}
}

The information required in orderdetails is specified in the table below:

Key Name Value Type Specification
account integer The Hancocks Account Number of the purchaser
purchaseorder string The Purchaser's internal Purchase Order identifier for this Order

The information required in orderitems is specified in the table below:

Key Name Value Type Specification
stockcode string The Hancocks Stockcode for this Item
description string The Item's product Description
refcode string The Purchaser's internal Stockcode for this Item. Note, this data is optional as it is only used for reference purchases.
refprice string The Purchaser's expected price for this Item. Note, this data is optional as it is only used for reference purchases.
quantity integer The Ordered Quantity for this Item. Note, the Quantity must be of the Stockcode Ordered f.ex if cases are being Ordered then the Quantity is the number of cases.

For an Order request the API Response Status Codes should be interpreted as follows:

Code Status Context
201 CREATED The Order Request has been successfully processed, parse the Response's JSON payload for details
400 BAD REQUEST The Order Request is invalid. This relates to not being able to extract a valid Hancocks Account Number, Purchase Order Identifier, or Order Items
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
409 CONFLICT Hancocks already has a processed Order for this Account Number and Purchase Order i.e. this Order is rejected as a duplicate
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

Upon a successful 201 status code response, the structure of the data component of the response object is a JSON object of the orderdetails and a JSON array of the orderitems

The structure of the orderdetails data component of the data object is a JSON object having the structure specified in the table below:

Key Name Value Type Specification
account integer The Hancocks Account for this Order
order integer The Hancocks Order Number Identifier
purchaseorder string The Purchaser's Purchase Order Identifier
deliveryto string The Purchaser's Name for Delivery as per the Purchaser's Hancocks Account configuration
deliveryline1 string The first line of the Purchaser's Delivery Address as per the Purchaser's Hancocks Account configuration
deliveryline2 string The second line of the Purchaser's Delivery Address as per the Purchaser's Hancocks Account configuration
deliveryline3 string The third line of the Purchaser's Delivery Address as per the Purchaser's Hancocks Account configuration
deliveryline3 string The fourth line of the Purchaser's Delivery Address as per the Purchaser's Hancocks Account configuration
deliverycode string The post code of the Purchaser's Delivery Address as per the Purchaser's Hancocks Account configuration
deliveryinstructions string Any Delivery Instructions as per the Purchaser's Hancocks Account configuration
itemcount integer The number of Order items Hancocks has processed
subtotal double The subtotal of Order items Hancocks has processed exclusive of GST

The structure of the orderitems data component of the data object is a JSON array of JSON objects having the structure specified in the table below:

Key Name Value Type Specification
stockcode string The Hancocks Stockcode for this Item
refcode string Any Purchaser's internal Stockcode submitted for this Item
status string Status is either ORDERED or REJECTED. A REJECTED Item may be accompanied by a bracketed reason for the ordering Account, price = the Hancocks pricing calculation did not complete for this Item, stock = no Hancocks stock was retrieved for this Item, pack = no orderable pack quantity was found for the Stockcode
description string The ORDERED Item's Hancock's product Description
vintage string The ORDERED Item's Vintage
quantity integer The ORDERED Item's Quantity as processed by Hancocks
price double The ORDERED Item's Price as processed by Hancocks - the calculated Price includes any discounts applicable to the Account and Item for the Quantity Ordered - exclusive of GST
saving string A note of the ORDERED Item's Saving on Trade Price
tier string The ORDERED Item's pricing Tier applicable to the Account and Item for the Quantity Ordered
line double The ORDERED Item's Price x Quantity Line Total exclusive of GST
bonuses array Any Bonus Items that have been triggered by purchasing the Quantity of the ORDERED Item are listed in this JSON array

Any ORDERED Item's Bonus Items have the JSON object structure specified in the table below:

Key Name Value Type Specification
stockcode string The Hancocks Stockcode for this Bonus Item
description string The Bonus Item's Hancock's product Description
vintage string The Bonus Item's Vintage
quantity integer The Bonus Item's Quantity
price double The Bonus Item's Price exclusive of GST

Order Status

Order Status is an information retrieval request involving sending a request to the URL  https://b2b.hancocks.co.nz/orderstatus  as discussed in the API Information Exchange Requests and Information Exchange Responses sections above. For an Order Status request the data object must contain JSON integers of the account number and order number that the order status is to be returned for. An abbreviated example of the request JSON object is as follows:

{"data":
"account": …,
"order": …
}

The information required in the data object is specified in the table below:

Key Name Value Type Specification
account integer The Hancocks Account Number of the purchaser
order string The Hancocks Order identifier for this Order

Upon a successful 200 status code response, the structure of the data component of the response object is a JSON object orderdetails and a JSON array events of processing events

The structure of the orderdetails component of the data object is a JSON object having the structure specified in the table below:

Key Name Value Type Specification
order integer The Hancocks Order Identifier
salesorder integer The Hancocks Sales Order Identifier

The JSON objects contained in the events JSON array in data component have the structure specified in the table below:

Key Name Value Type Specification
timestamp string The date timestamp of this processing event in the format "yyyy-MM-dd'T'HH:mm:ss.SSS"
comment string The text comment explaining this processing event
invoice string If this event is associated with Hancocks Invoices then the Invoice identifers are stated in this optional element
photo string If this processing event has any associated photos of the Order at the point of its dispatch then the URL to access those photos is stated in this optional element
trackingurl string If this processing event has an associated courier tracking URL for the Order then that URL is stated in this optional element