NEDIS Connect (EN)

Technical Implementation Manual

Real time Price & Availability Request v1.0 B.N. Vervoort – Project Engineer E-commerce May 2013

Page 1 of 15

Version control Date

Version

Change

Author(s)

20-04-2013

1.0

First version

B.N. Vervoort

Page 2 of 15

Table of Contents Version control ................................................................................................................................................. 2 Table of Contents .............................................................................................................................................. 3 1

INTRODUCTION ........................................................................................................................ 4

2

NEDIS API .................................................................................................................................. 5

2.1

IP Address Authentication ....................................................................................................................... 5

2.2

Authentication Request ........................................................................................................................... 5

2.3 Authentication Response ......................................................................................................................... 5 2.3.1 Authentication Successful ................................................................................................................ 5 2.3.2

Authentication Failed ...................................................................................................................... 7

3

NEDIS CONNECT: P&A CHECK................................................................................................ 8

3.1

Limitations ............................................................................................................................................... 8

3.2

Error Responses ....................................................................................................................................... 8

OBTAINING PRICE INFORMATION ................................................................................................... 9 3.3

Price Request ........................................................................................................................................... 9

3.4

Price Response....................................................................................................................................... 10

4

OBTAINING AVAILABILITY (STOCK) INFORMATION ............................................................ 13

4.1

Stock Request ........................................................................................................................................ 13

4.2

Stock Response ...................................................................................................................................... 14

Page 3 of 15

1

Introduction

The real time stock check is very useful before accepting an order from your client. Why? Because it allows you to see if there is stock available at the NEDIS warehouses hence preventing backorders and allowing to maintain customer satisfaction. In order to use the service please contact your local NEDIS office for more information.

Example process of Realtime stock check implemented in an online environment:

An electronic version of this document can be downloaded through our corporate website.

The location of this document is: http://www.nedis.com/upload/image/nedis-connect-price-availability-check.pdf Caused by the strong development of the e-Commerce possibilities and infrastructure at NEDIS, this document will be subject to change. Please check back regularly to see if updates are available.

Regards, NEDIS E-Commerce Team ecommerce@nedis.com

Page 4 of 15

2

NEDIS API

The NEDIS API is the gateway to usage of the NEDIS Connect services. To make use of the NEDIS Connect services an access token has to be obtained from the API. When successfully authenticated as a user the access token will be granted by NEDIS. The token can be used for the duration of 60 minutes to make requests. After 60 minutes the token expires and a new token needs to be obtained before any new requests can be made using the API. It’s also possible to acquire an access token per separate request, do note however that this will take slightly longer to process.

2.1

IP Address Authentication

When applying for the API services one or more IP addresses have to be provided to NEDIS from where requests will be made. We accept only requests from prelisted IP addresses. In case of IP address changes, please communicate this timely to prevent loss of service.

2.2

Authentication Request

A connection needs to be established between your system and the NEDIS API. Depending on the desired response this can be done using one of the following URL’s: XML api.nedis-connect.com/oauth2/token.xml JSON api.nedis-connect.com/oauth2/token.json

The following variables need to be posted here (make sure to use a POST request) grant_type: This parameter has a fixed value; authorization_code client_id: This is your specific client id. This is not the NEDIS customer number but a separate ID which will be provided by NEDIS with the confirmation of the usage for this service. code: This is the API Key specific to your account and will be provided by NEDIS with the confirmation of the usage for this service.

2.3

Authentication Response

In case the authentication as described above was successful an Access Token is granted in the response message.

2.3.1 Authentication Successful For all successful responses an HTTP Response code 200 will be communicated by the server together with the following parameters and values.

Page 5 of 15

<access_token> This is the generated key that can be used to make requests <expires_in> Time in seconds the token will be valid <token_type> This tag will be filled by default with the value bearer <scope> Tag will be displayed but will be left empty (currently not in use) <refresh_token> Tag will be displayed with a value (currently not being used) Example XML Response:

Example JSON Response:

Page 6 of 15

2.3.2 Authentication Failed NOTE: On all errors an HTTP Response code 400 will be communicated by the server together with the following parameters and values. <error> Possible error messages are: 1.

invalid_request

2.

invalid_client

3.

invalid_grant

<error_description> 1.

Invalid grant_type parameter or parameter missing

2.

The client credentials are invalid

3.

Code doesn't exist or is invalid for the client

Example XML Response:

Example JSON Response:

Page 7 of 15

3

NEDIS CONNECT: P&A Check

The following items apply to the entire P&A check service.

3.1

Limitations

With the activation of your API account a daily request limit for the P&A check is set and communicated to you.

In case this limit is reached no more request can be made for that day. We always strive to come to a mutual beneficial and fair number of requests in order to do business.

3.2

Error Responses

Below are the possible error responses that could be encountered while using the service.

Status Code

Counts as Request

Description

200

Yes

Success

400

No

Missing or incorrect parameter: (parameter name)

401

No

Authentication error / Unauthorized

403

No

IP Address not allowed

600

Yes

Request limit reached

610

Yes

Item not found

620

No

System error

Note: these are not HTTP server status codes but status codes communicated in the response messaging (XML/JSON)

Page 8 of 15

Obtaining Price Information Using the realtime price check allows you to obtain actual pricing information for your specific account. This includes customer specific price agreements / discounts.

3.3

Price Request

Depending on the desired response this can be acquired by using one of the following urls XML api.nedis-connect.com/articles/price.json JSON api.nedis-connect.com/articles/price.xml The following variables need to be posted here (make sure to use a POST request) request_type (string) possible values here are articleid (NedisArtlid as being communicated in the Article Datafeeds) nedispartnumber (NedisPartnr / Productcode as being communicated in the Article Datafeeds) eancode (EAN13 code of the item) vendorpartnumber (the partnumber of the vendor / manufacturer, in case of NEDIS brands this is the same as the nedispartnumber) request_value (string) value of the request_type as chosen at option 1 quantity (int) This concerns the quantity of articles you are requesting the price for ( > 0 ) access_token (string) This concerns the access token as received back from NEDIS after succesfully completing the authentication process.

Example of the parameters with their values:

Page 9 of 15

3.4

Price Response

For all successful responses an HTTP Response code 200 will be communicated by the server together with the following parameters and values. <response> Start of main message <status> Start of status messaging <code> Status code of the response <description> Status <requestcount> Quantity of requests done so far <requestlimit> Quantity of maximum requests that can be made with this API key <data> Start of data messaging <locale> Language / Country of the messaging (Eg. En-US) <nedispartnr> Attention for XML Responses; Since this is a !CDATA field it can contain HTML or non-standard characters.

The NEDIS productcode <articleid> The NEDIS Article Id as communicated in the Article Datafeeds <vendorpartnumber> Attention for XML Responses; Since this is a !CDATA field it can contain HTML or non-standard characters.

The Vendor / Manufacturerâ&#x20AC;&#x2122;s product code <eancode> EAN13 code <brandname> Attention for XML Responses; Since this is a !CDATA field it can contain HTML or non-standard characters.

Brandname of the requested article <shortdescription> Attention for XML Responses; Since this is a !CDATA field it can contain HTML or non-standard characters.

Short description to identify the requested product <productstatus> Start of productstatus messaging

Page 10 of 15

<statuscode> this concerns the status of the product options here are: NORMAL / GOTO / OOP <replacement> Attention for XML Responses; Since this is a !CDATA field it can contain HTML or non-standard characters.

Product identifier of the replacement article (this will be in the same format as the request has been done for) in case the statuscode is GOTO <pricing> Start of pricing messaging <currency> currency the monetary values are communicated in <price> Start of price line <amount> Monetary value <quantity> Quantity the price is valid for <tax> Start of tax messaging <description> Attention for XML Responses; Since this is a !CDATA field it can contain HTML or non-standard characters.

Description of the TAX charged <advisedsalesprice> Start of advised sales price messaging <specialoffers> In case a special offer is active this is the start of the special offer messaging Every price level will receive itâ&#x20AC;&#x2122;s own entry consisting out of <entry> Start of a new special offer price entry <amount> Monetary value <quantity> Quantity the price is valid for <validTo> Special offer pricing valid until; in format YYYY-MM-DD

Page 11 of 15

Example XML Response:

Example JSON Response:

Page 12 of 15

4

Obtaining Availability (Stock) Information

Using the realtime availability check allows you to obtain actual stock information from NEDIS.

4.1

Stock Request

Depending on the desired response this can be acquired by using one of the following urls XML api.nedis-connect.com/articles/stock.json JSON api.nedis-connect.com/articles/stock.xml The following variables need to be posted here (make sure to use a POST request) request_type (string) possible values here are; articleid (NedisArtlid as being communicated in the Article Datafeeds) nedispartnumber (NedisPartnr / Productcode as being communicated in the Article Datafeeds) eancode (EAN13 code of the item) vendorpartnumber (the partnumber of the vendor / manufacturer, in case of NEDIS brands this is the same as the nedispartnumber) request_value (string) value of the request_type as chosen at option 1 access_token (string) This concerns the access token as received back from NEDIS after succesfully completing the authentication process.

Example of the parameters with their values:

Page 13 of 15

4.2

Stock Response

For all successful responses an HTTP Response code 200 will be communicated by the server together with the following parameters and values.

<response> Start of main message <status> Start of status messaging <code> Status code of the response <description> Status <requestcount> Quantity of requests done so far <requestlimit> Quantity of maximum requests that can be made with this API key <data> Start of data messaging <locale> Language / Country of the messaging (Eg. En-US) <nedispartnr> Attention for XML Responses; Since this is a !CDATA field it can contain HTML or non-standard characters.

The NEDIS productcode <articleid> The NEDIS Article Id as communicated in the Article Datafeeds <vendorpartnumber> Attention for XML Responses; Since this is a !CDATA field it can contain HTML or non-standard characters.

The Vendor / Manufacturerâ&#x20AC;&#x2122;s produc code <eancode> EAN13 code <brandname> Attention for XML Responses; Since this is a !CDATA field it can contain HTML or non-standard characters.

Brandname of the requested article <shortdescription> Attention for XML Responses; Since this is a !CDATA field it can contain HTML or non-standard characters.

Short description to identify the requested product <productstatus> Start of productstatus messaging

Page 14 of 15

<statuscode> this concerns the status of the product options here are: NORMAL / GOTO / OOP <replacement> Attention for XML Responses; Since this is a !CDATA field it can contain HTML or non-standard characters.

Product identifier of the replacement article (this will be in the same format as the request has been done for) <stock> Start of stock messaging <centralstock> Start of central stock messaging; stock available in the central warehouse in the Netherlands (only appears when your NEDIS office also has a local warehouse) <freestock> stock value of freestock available Example XML Response:

Example JSON Response:

Page 15 of 15