Exchange Integration API Documentation
Document Revision Draft 7.0 Date of Issue: 1 July 2015 Date of revision: 15 March 2017 Ashley Hopkins Director of Technology
Confidential Page 1 of 20
Exchange Integration API Documentation
Table of Contents 1.
Purpose ................................................................................................................................................. 3
2.
Glossary of Terms ................................................................................................................................... 3
3.
Technical Standards ................................................................................................................................ 3
4.
Request Header ...................................................................................................................................... 4
5.
API Listing .............................................................................................................................................. 5
6.
5.1
Heartbeat (HEAD or GET Method) ..................................................................................................... 5
5.2
Add Order Service (POST Method) .................................................................................................... 6
5.3
Delete Order Service (DELETE Method) ............................................................................................ 11
5.4
Confirm Trade (PUSH)..................................................................................................................... 14
5.5
Order Update (PUSH) ..................................................................................................................... 15
Response Codes ................................................................................................................................... 17 6.1
Request validation error codes ........................................................................................................ 17
6.2
Trade validation error codes ........................................................................................................... 18
6.3
HTTP Status codes.......................................................................................................................... 19
Confidential
Page 2 of 20
Exchange Integration API Documentation
1. Purpose To provide the API end point information and examples of the web services available for Exchange Integration.
2. Glossary of Terms Term
Meaning
L-WIN
L-WIN - the Liv-ex Wine Identification Number – serves as a universal wine identifier for the wine trade. L-WIN is a unique seven to eighteen-digit numerical code that can be used to quickly and accurately identify a product. L-WIN allows wine companies to keep their preferred naming system, while introducing a new universal code.
Wine
The word wine below is referring to a specific wine (the producer and brand, grape or vineyard), vintage and unit size combination.
Bid
A buyer places a bid on the Exchange for buying a certain amount of wine.
Offer
A seller places an offer on the Exchange for selling a certain amount of wine.
Order
Order is a generic term for both bid/offer.
Market Price
The Market Price is based on the cheapest 6 and 12-pack prices advertised by leading merchants in the EU and Switzerland. (Where appropriate, alternative unit sizes are used for the calculation.) It provides a guide as to the price you are likely to pay for SIB-compliant stock in the market
SIB
Standard in Bond trade terms: http://www.livex.com/staticPageContent.do?pageKey=Rules_and_Regulations
SEP
Standard En Primeur: http://www.livex.com/staticPageContent.do?pageKey=Rules_and_Regulations
Contract Type
Contract type is a generic term for SIB, SEP or Special (X).
3. Technical Standards
Confidential
Permitted users will be issued with a unique token (CLIENT_KEY) and password (CLIENT_SECRET) combination to control the access for all the web services covered under Exchange Integration. The web services will consume and produce both XML and JSON. The user can provide the content type in the request header. If the user does not provide any information, then the default content type will be JSON. The project will support ISO 8601. The project will only support HTTPS protocol for client and server communications. The API’s will support the following methods: 1. POST for create operation 2. GET for read operation 3. PUT for update operation 4. DELETE for delete operation Add and delete services are one order at a time by default, but multiple orders and deletions are possible. Page 3 of 20
Exchange Integration API Documentation
Pretty printing for output readability only is supported if required Compression for bandwidth savings are used For HTTP users who can only work on GET & POST methods, we provide a Header ‘X-HTTPMethod-Override’ for PUT & DELETE Authentication mechanism will be custom based on CLIENT_KEY and CLIENT_SECRET For PUSH services we require a direct POST URL which should be backed by a service capable of accepting and process XML payload as POST request. The Exchange Integration API will be accessible at https://api.liv-ex.com/exchange
4. Request Header This information will be used to authenticate valid access to the REST API. Each user will have to provide the following information in the request header.
Param Name
Mandatory
Description
CLIENT_KEY
Y
A valid merchant GUID which will be unique for each merchant.
CLIENT_SECRET
Y
Password/Secret for the merchants CLIENT_KEY.
ACCEPT
Y
Accept header is a way for a client to specify the media type of the response content it is expecting. The values for the content type will be application/json or application/xml.
If no/ invalid content type is found in the request, then JSON format will be used by default. CONTENT-TYPE
Y for POST requests
Content-type is a way to specify the media type of request being sent from the client to the server. The values for the content type will be application/json or application/xml.
If no/ invalid content type is found in the request, then JSON format will be used by default. e.g. CLIENT_KEY: 94B5CC70-BC3D-49C3-B636-C3C7552E543D CLIENT_SECRET: merchantpasswd ACCEPT: application/json CONTENT-TYPE: application/json
Invalid header JSON response
Confidential
Page 4 of 20
Exchange Integration API Documentation
{ "status": "Unauthorized", "httpCode": "401", "message": "Request was unsuccessful", "livexCode": "R000" "apiInfo": { "version": "1.0", "timestamp": "2015-06-04T11:12:30", "provider": "Liv-ex" } }
Invalid header XML response
Unauthorized 401 Request was unsuccessful. R001 1.0 2015-06-04T11:12:30 Liv-ex
5. API Listing 5.1 Heartbeat (HEAD or GET Method) Description This may be used by merchant systems to ping/poll the Exchange Integration service for availability, and if its available then further requests for Orders may be placed.
Base URI exchange/heartbeat
Response Exchange Integration service will respond with HTTP Code 200 - OK in the response, depending on whether a HEAD or GET request was made. E.g - HTTP HEAD - https://api.liv-ex.com/exchange/heartbeat OK 200 E.g. - HTTP GET - https://api.liv-ex.com/exchange/heartbeat { "status":"OK", "httpCode":"200", "message":"available", "internalErrorCode”: null, "apiInfo":{ "version":"1.0", "timestamp":1462458491889, Confidential
Page 5 of 20
Exchange Integration API Documentation
"provider":"Liv-ex" }, "orders”: null } If the Exchange Integration service is down (because of maintenance or any network issues) then the response will return HTTP Error Code 500 - Internal Server Error. Note: Liv-ex will automatically suspend integrated merchants’ SIB orders with ‘suspended’ status on the restart of the Exchange Integration service (if the Exchange Integration service has been down because of maintenance or any network issues). This should be followed by delete + add requests by the merchant system to be able sync and reinstate their respective positions. Throttling Every heartbeat invocation registers as a valid API request, and will be used against the allowable throttling limit i.e. API calls made on hourly basis. Once threshold is reached no more calls will be allowed till next allowable time period.
5.2 Add Order Service (POST Method) Description This service will be used to add a bid or offer.
Base URI exchange/v1/orders
Param Name
Confidential
Mandatory
Description
contractType
Y
A valid contract type of the order. The possible value can be SIB (Standard In Bond) and SEP (Standard En Primeur).
orderType
Y
A valid type of the order. The possible values can be B (Bid) and O (Offer).
orderStatus
Y
A valid order status. The possible values can be L (Live) and S (Suspended). See recommendation note.
expiryDate
N
A valid future date in yyyy-mm-dd format e.g. 2015-07-31.
lwin
Y
A valid L-WIN7or L-WIN18.
vintage
N
Mandatory only if L-WIN7 is provided. The value can be one year less than current year in YYYY format e.g.2004, 2014 etc. For No Vintage (NV) please use 1000.
Page 6 of 20
Exchange Integration API Documentation
bottleInCase
N
Mandatory only If L-WIN7 is provided. The values typically are 1, 6, 12, etc.
bottleSize
N
Mandatory only if L-WIN7 is provided. The values should be in ml (millilitres). For example,75cl should be 00750.
currency
Y
Either EUR or GBP. The currency used must match the trading currency pre agreed with Liv-ex.
price
Y
A valid positive value. Decimal point is only allowed for Euro per bottle customers such as 37.5.
quantity
Y
A valid positive integer value of quantity of packs such as 1,2, 50 etc.
merchantRef
N
If provided should not exceed 30 characters. The possible values can be any string up to 30character length.
Recommendation Notes: To unsuspend a suspended position through the Exchange Integration service, please send a delete for the suspended order first then add a new order.
Sample Request Body By default, we will have request as multiple array/list of Orders even though the Client may pass only one as given in the example below.
JSON Request {“orders:”[{ "contractType": "sib", "orderType": "B", "orderStatus": "L", "expiryDate": "2015-07-31", "lwin": "1122763", "vintage": "2007", "bottleInCase": "12", "bottleSize": "00075", "currency": "EUR", "price": "416", "quantity": "1", "merchantRef": "MyRef" }] }
JSON Request (multiple orders) {"orders": Confidential
[ Page 7 of 20
Exchange Integration API Documentation
{ "contractType": "sib", "orderType": "o", "orderStatus": "L", "expiryDate": "2017-03-06", "lwin": "1102200", "vintage": "2013", "bottleInCase": "6", "bottleSize": "00750", "currency": "GBP", "price": "150", "quantity": "1", "merchantRef": "MyRef" }, { "contractType": "sib", "orderType": "o", "orderStatus": "L", "expiryDate": "2017-03-06", "lwin": "1012316", "vintage": "1990", "bottleInCase": "6", "bottleSize": "00750", "currency": "GBP", "price": "875", "quantity": "1", "merchantRef": "MyRef" } ]}
XML Request sib o L 2017-02-05 1012316 1990 6 00750 GBP 5250 1 MyRef Confidential
Page 8 of 20
Exchange Integration API Documentation
XML Request (multiple orders) sib o L 2017-03-05 1012316 1990 6 00750 GBP 5250 1 MyRef sib o L 2017-03-05 1012387 2011 12 00750 GBP 525 1 MyRef
JSON Response The response is sent per order
Confidential
Page 9 of 20
Exchange Integration API Documentation
{ "status": "OK", "httpCode": "200", "message": "Request completed successfully", "internalErrorCode": "R001", "apiInfo": { "version": "1.0", "timestamp": "2015-06-04T11:12:30", "provider": "Liv-ex" }, "orders": [{ "merchantRef": "TestRef", "orderId": "94B5CC70-BC3D-49C3-B636-C3C7552E543D", "orderPlaceDate": "2015-06-04T07:22:25" "errors": "", }] }
Invalid JSON response { "status": "failure", "httpCode": "400", "internalErrorCode": "R002", "message": "Request partially completed", "apiInfo": { "version": "1.0", "timestamp": "2015-06-04T11:12:30", "provider": "Liv-ex" }, "orders": [{ "merchantRef": "TestRef", "orderId": "", "orderPlaceDate": "" "errors": { "error": [{ "code": "TR005", "message": "Please provide positive numeric value of qty." }, { "code": "TR006", "message": "Please provide positive decimal value of price." }] }, }] }
XML Response The response is sent per order
Confidential
Page 10 of 20
Exchange Integration API Documentation
OK 200 Request completed successfully. R001 TestRef 94B5CC70-BC3D-49C3-B636-C3C7552E543D 2015-06-04T07:22:25
Invalid XML Response failure 400 Sorry, problem encountered while processing the Order. R001 1.0 2015-06-04T11:12:30 Liv-ex TestRef TR005 Please provide positive numeric value of qty. TR006 Please provide positive decimal value of price
5.3 Delete Order Service (DELETE Method) Description This web service will be used to delete the bid or offer of a merchant.
Base URI exchange/v1/orders Confidential
Page 11 of 20
Exchange Integration API Documentation
Param Name
Mandatory
orderId
Y
Description A valid orderid (GUID) for the account.
Sample Request Body Order ID is a GUID number returned when using add order service [{ "orderId": "94B5CC70-BC3D-49C3-B636-C3C7552E543D" },{ "orderId": "94B5CC70-BC3D-49C3-B636-C3C7552E543D" }]
JSON Response Response with valid order ID { "status":"OK", "httpCode":"200", "message":"Request completed successfully.", "internalErrorCode":"R001", "apiInfo": { "version":"1.0", "timestamp":1462450114401, "provider":"Liv-ex" }, "orders": {"order": [{ "merchantRef":"test0505", "orderId":"94B5CC70-BC3D-49C3-B636-C3C7552E543D", "orderPlaceDate":1462450114337, "errors”: null }] } }
Response with invalid order ID
Confidential
Page 12 of 20
Exchange Integration API Documentation
{ "status": "failure", "httpCode": "400", "message": "Sorry, problem encountered while processing the Order.", "internalErrorCode": "R000", "apiInfo": { "version": "1.0", "timestamp": "2015-06-04T11:12:30", "provider": "Liv-ex" }, "orders": [{ "merchantRef": "TestRef", "orderId": "94B5CC70-BC3D-49C3-B636-C3C7552E543D", "response": "" "errors": [{ "error": { "code": "TR001", "message": "Merchant and order combination does not match." } }], }] }
XML Response Response with valid order ID OK 200 Request completed successfully R001 1.0 2015-06-04T11:12:30 Liv-ex TestRef 94B5CC70-BC3D-49C3-B636-C3C7552E543D
Response with invalid order ID
Confidential
Page 13 of 20
Exchange Integration API Documentation
failure 400 R000 Request unsuccessful 1.0 2015-06-04T11:12:30 Liv-ex TestRef 94B5CC70-BC3D-49C3-B636-C3C7552E543D TR001 Merchant and order combination does not match.
5.4 Confirm Trade (PUSH) Description This push will be invoked when a trade matches. The information will be pushed to a user’s system from Liv-ex as a POST request (XML/JSON Payload) to the merchant's URL.
Merchant URL This will be the URL which each merchant will provide to Liv-ex to push the information to their system. Note: Liv-ex will automatically suspend ALL SIB orders with suspended status if the Merchant URL is inaccessible. This should be followed by delete + add requests by the merchant system to be able sync and reinstate respective positions. PUSH notifications to the merchant’s URL can be disabled by Liv-ex if necessary.
Push service requirement (Merchant side) The Merchant URL should be backed by a simple HTTP based POST service that is capable of interpreting the incoming XML/JSON payload.
Push Data Name
Confidential
Value
Page 14 of 20
Exchange Integration API Documentation
notification_type notification_info
Trade XML 94B5CC70-BC3D-49C3-B636-C3C7552E543D test ref 123450 20 2015-06-12T17:00:00
JSON "trade": { "order_guid": "94B5CC70-BC3D-49C3-B636-C3C7552E543D", "merchant_ref": "test ref", "trade_id": "123450", "qty": "20" "trade_date": "2015-06-12T17:00:00" } }
Param Name
Description
order_guid
Bid or Offer Id.
merchant_ref
The merchant reference for the order. This node will only be pushed if there was a reference provided on the order.
trade_id
Liv-ex Trade Id.
Qty
The total quantity of the trade.
trade_date
The date and time of trade in ISO 8601 format.
5.5 Order Update (PUSH) Description This push will be invoked and pushed to a merchant’s system when an order of theirs is added, amended, suspended or deleted from the Liv-ex web platform. This information will be pushed as a POST request (XML/JSON Payload) to the merchant URL.
Merchant URL This will be the URL which each merchant will provide to Liv-ex to push the information to their system. Note: Liv-ex will push the Order Update to the same URL that’s provided for the Confirm Trade push. Confidential
Page 15 of 20
Exchange Integration API Documentation
Note: Liv-ex will automatically suspend ALL SIB orders with suspended status if the Merchant URL is inaccessible. This should be followed by delete + add requests by the merchant system to be able sync and reinstate respective positions. PUSH notifications to the merchant’s URL can be disabled by Liv-ex if necessary.
Push Data Name
Value
notification_type
Orderupdate
notification_info
XML 94B5CC70-BC3D-49C3-B636-C3C7552E543D Abc Order Suspended SIB Bid Suspended 2015-06-12T17:00:00 101430720081200750 240 1 2015-06-04T07:22:25 JSON "order": { "order_guid": "94B5CC70-BC3D-49C3-B636-C3C7552E543D " "merchant_ref": "Abc", "push_type": "Order Suspended" "contract_type": "SIB" "order_type": "Bid" "order_status": "Suspended" "expiry_date": "2015-06-12T17:00:00" "lwin": "101430720081200750" "price": "240" "qty": "1" "order_update_date": "2015-06-04T07:22:25" } }
Param
Confidential
Name
Description
order_guid
Order ID which was created/edited/deleted.
merchant_ref
Merchant reference for the order if provided. This node will not be pushed if there is no reference provided by merchant.
push_type
Type of push request. The possible values will be Order Created, Order Edited, Order Suspended, Unsuspended, Order Deleted, Order Blocked, Order Unblocked.
contract_type
The contract type of the order. The possible values will be SIB.
Page 16 of 20
Exchange Integration API Documentation
order_type
The order type. The possible values will be Bid/Offer.
order_status
The current order status in the system. The possible values will be Live, Suspended, Deleted
expiry_date
The expiry date in ISO 8601 format.
lwin
The L-WIN18 of the wine will be provided.
price
The order price provided by the merchant in their trading currency.
qty
The total quantity of the order provided by the merchant.
order_update_date
The order update date time in ISO 8601 format.
6. Response Codes This section describes the response codes that will be returned by the Exchange Integration services.
Code
Message
R000
Request was unsuccessful
R001
Request completed successfully
R002
Request partially completed
6.1 Request validation error codes
Confidential
Code
Message
V000
Mandatory field missing.
V001
Merchant is not allowed to access the requested feed.
V002
Invalid parameter(s).
V003
Wrong date format. Date should be 'yyyy-MM-dd'.
V004
Invalid number parameter: positive number expected for {paramName}.
V005
Merchant is not active.
V006
Invalid L-WIN number.
V007
Invalid LWIN 7.
V008
Invalid LWIN 18.
V009
Web service only supports B (Bid) and O (Offer) as order type parameter.
Page 17 of 20
Exchange Integration API Documentation
V010
Web service only supports SIB and SEP as contract type parameter.
V011
Web service only supports L (Live) and S (Suspend) as order state parameter.
V012
Invalid request headers. Please provide value for header {header name}.
V013
Please provide valid vintage.
V015
Invalid currency.
6.2 Trade validation error codes
Confidential
Code
Message
TR000
Invalid orderID.
TR001
Merchant and order combination does not match.
TR002
Order is already suspended.
TR003
Order type provided does not match with actual order.
TR004
Order did not confirm successfully. Please check it and try again.
TR005
Please provide positive numeric value of quantity.
TR006
Please provide positive decimal value of price.
TR007
A bid appears to be above Market Price. Please check carefully before proceeding.
TR008
An offer appears to be below Market Price. Please check carefully before proceeding.
TR009
Your En Primeur selling privileges have been restricted. Please contact your Exchange Manager for further information.
TR010
You are about to match your own bid.
TR011
You are about to match your own offer.
TR012
Merchant does not have trading privileges.
TR013
Merchant is not permitted to sell EP stock.
TR014
Merchant account is ‘sell only’.
TR015
Merchant is not permitted to buy EP stock. EP sell status is ‘resell only’.
TR016
Merchant is not allowed to buy and sell EP stock as the trading status is ‘sell special only: no EP allowed’.
TR017
You are currently only allowed to create special offers. Please change your offer. Page 18 of 20
Exchange Integration API Documentation
TR018
Contract type does not match with actual order.
TR019
You are not allowed to confirm this orders as doing this will take you over your buying limit.
TR020
You are not allowed to confirm this order as doing this will take you over your selling limit.
TR021
You are not allowed to confirm this order as doing this will take you over your EP selling limit.
6.3 HTTP Status codes HTTP defines a bunch of meaningful status codes that can be returned from our API. These can be leveraged to help our API Merchants/consumers route their responses accordingly:
Confidential
Code
Message
200 OK
Response to a successful GET, POST, PUT, DELETE. Can also be used for a POST that doesn't result in a creation.
201 Created
Response to a POST that results in a creation.
202 Accepted
The request has been accepted and will be processed later. It is a classic answer to asynchronous calls (for better UX or performances).
204 No Content
Response to a successful request that won't be returning a body (like a DELETE request)
400 Bad Request
The request is malformed, such as if the body does not parse
401 Unauthorized
When no or invalid authentication details are provided. Also useful to trigger an auth popup if the API is used from a browser
403 Forbidden
When authentication succeeded but authenticated user doesn't have access to the resource
404 Not Found
When a non-existent resource is requested
405 Method Not Allowed
When an HTTP method is being requested that isn't allowed for the authenticated user
406 Not Acceptable
Nothing matches the Accept-* Header of the request. As an example, you ask for an XML formatted resource but it is only available as JSON.
410 Gone
Indicates that the resource at this end point is no longer available. Useful as a blanket response for old API versions
415 Unsupported Media Type
If incorrect content type was provided as part of the request
Page 19 of 20
Exchange Integration API Documentation
Confidential
422 Unprocessable Entity
Used for validation errors. Should be used if the server cannot process the entity, e.g. if an image cannot be formatted or mandatory fields are missing in the payload.
429 Too Many Requests
When a request is rejected due to rate limiting
500 Internal Server Error
The general catch-all error when the server-side throws an exception. The request may be correct, but an execution problem has been encountered at our end.
Page 20 of 20
