Introduction

OrangeConnex is a standardized interface for fulfillment service providers and their customers.

Getting started

OC’s ERP team receive connection request

seller/ERP initiate connection request

Unless account details have been provided by the local OC team, the Seller/ERP system should send the following request to：development.it@itiaoling.com

Customer Name	********limited（3PP-ERP do not required）
Country/Region	Mainland China/HK/DE/UK/AU
OCID	00000000（3PP-ERP do not required）
ERP Type	Seller-ERP or 3PP-ERP
ERP Code	Unique ERP Code
ERP Name	Seller-ERP Name/3PP-ERP Name
OC Service	Fulfillment service in DE/UK/AU/US warehouses（3PP-ERP do not required）

*3PP-ERP means third party’s ERP , Seller-ERP means seller has its own ERP

OC open the testing account & information
The OC team will request test accounts on behalf of Australian 3PPs. On receipt of a test account request, the OC team will generate a unique ClientKey & SecretKey for each 3PP.
SELLER/ERP initiate connection request in SANDBOX environment

The OC team will verify the testing results and record the API connectors’ testing status as quickly as possible.
Opening of the production environment account
After passing the ‘testing environment tests, the OC team will then open a production-environment account for the user and ERP system. It takes around 1-2 working days to action. In addition, third-party ERP needs to provide user set-up guidelines to help users finish set-up.

Authorization introduction

Authorization code & token’s connector explanation

API name in document	Connector Usage Explanation
URL(getAuthorizationCode)	Purpose：To allow the ERP system to request OC’s authorization code
accessToken&refreshToken	Usage：To allow the ERP system to request accessToken & refreshToken Please Note：The ‘access_token’ is valid for 3,600 seconds. If it has expired, please use ‘refresh_token’ to retrieve a new one. The “refresh token” is valid for one year, please store a record of the “refresh token” to make sure you can retrieve the ‘access token’
refresh accessToken	Purpose：To allow the ERP system to use the ‘refeshToken’ to retrieve a new “accessToken”

Important note regarding the authorization code & token connectionURL(getAuthorizationCode)
The ERP system receives OC’s authorization code via this connector.
For more information, please refer to URL(getAuthorizationCode).
A connection example is shown below:

https://openapi-cn.orangeconnex.com/oauth/authorize?response_type=code&client_id=ClientKey&redirect_uri=http://en.newsign.com&state=userID

Please Note：
The highlighted sections are placeholders; Clients should replace these with their own information.
ClientKey: the ClientKey which the client applyed before
http://en.newsign.com: the website which the client wishes to access
userID: username/userID used by ERP

After inserting the link, the webpage will return to the OC website home page. At this point, please enter the client’s username/userID and password.

Click "AGREE” button

Following this, the webpage will return to the website entered into the code.
The following syntax is used to copy the authorization code from the address. Please copy the returned authorization code into the highlighted area

http://en.newsign.com?act=getAuthorizationCode&code=returned authorization code&state=userID (ERP user account)

(Example of a returned web page)

accessToken&refreshToken
The ERP system retrieves the ‘accessToken&refreshToken’ for the user via this connector.
For more information, please refer to OC API SPECIFICATION section 1.1 accessToken & refreshToken.
The following is an example connection message:
https://openapi-cn.orangeconnex.com/oauth/token?grant_type=authorization_code&code=accessed authorization code&redirect_uri=http://en.newsign.com&client_id= ClientKey
OC will return 2 tokens back to the ERP system
```
{
  "access_token": "access_token information",
  "token_type": "bearer",
  "refresh_token": "refresh_token information",
  "expires_in": 3600
}
```
*[·-·]:Please Note
access_token：is only valid for 3,600 seconds. If expired, please use the refresh token to generate another access token.
refresh token：is valid for one year. Please store details of the refresh token to make sure you can retrieve a new access token.
refresh accessToken
The ERP system will use the refresh_token to generate another access_token.
For more information, please refer to OC API SPECIFICATION section 1.2 refresh accessToken.
Connection example:
POST /oauth/token?grant_type=refresh_token&refresh_token=“refresh_token”&client_id=“yourclientid” HTTP/1.1（Host: server.example.com, Content-Type: application/x-www-form-urlencoded）
Response:
```
{
  "access_token": "new access_token",
  "token_type": "bearer",
  "expires_in": 3600
}
```
*[·-·]:Please Note
The Access_token’s validation time is very short, OC suggests that the code includes a re-access rule to prevent problems from occurring.

About this API

The base url of this api is

Sandbox: https://openapi-stage-hk.orangeconnex.com/openapi.
Production: https://openapi-hk.orangeconnex.com/openapi.

Authorization

The eF openAPI uses OAuth2 with the Authorization Code Grant for its endpoints. Users must have an active OrangeConnex Seller Portal account to authorize against the OAuth2 server. Applications and services using the API must acquire client credentials from OrangeConnex.

Application credentials

When making calls against the API, you need to do it in the context of an application. You will get the credentials for your application from OrangeConnex.

Application credentials consist of the following:

client_id - uniquely identifies your application
client_secret - secret used to authenticate your application
redirect_uri - the uri the OAuth2 server redirect to on authorization requests

Requesting authorization

When you want to authorize a user you redirect him to
https://openapi-stage-hk.orangeconnex.com/oauth/authorize
with the following query string parameters:

response_type - Must be set to "code" for the Authorization Code Grant.
redirect_uri - After the user accepts your authorization request this is the url that will be redirected to. It must match the redirect_uri in your client credentials.
client_id - Your applications identifier from your application credentials.
state - An opaque value that will be included when redirecting back after the user accepts the authorisation. This is not required, but is important for security considerations.

After successful authorization by the user, the OAuth2 server will redirect back to your applications callback with the following query string parameters:

code - The authorization code.
state - The state parameter that was sent in the request.

Verifying authorization

The authorization code you acquired in the last step will now be exchanged for an access token. In order to do this you need to POST a request to https://openapi-stage-hk.orangeconnex.com/oauth/token.

POST https://openapi-stage-hk.orangeconnex.com/oauth/token

Authorization: Basic application_basic_auth\n>Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=code&redirect_uri=redirect_uri

In the Authorization header Basic HTTP authentication is used. Your application credentials client_id will be used as the username and your client_secret as the password. The header should have the value "Basic" plus the Base64 encoded string comprising of client_id:client_secret.

The body of the request consist of the form encoded parameters:

grant_type - Must be set to "authorization_code".
code - The authorization code received from the previous step.
redirect_uri - Must match the redirect_uri in your client credentials.

A successful verification request will return a JSON response with the properties:

token_type - is always "Bearer"
expires_in - the time in seconds until the access token will expire
access_token - the access token used for API requests
refresh_token - token used to get a new access_token without needing to ask the user again

Now the APIs endpoints that need authorization can be called by setting the header

Authorization: Bearer access_token

Refreshing authorization

To get a new access_token (for example when the old one expired) one can POST a request to https://openapi-stage-hk.orangeconnex.com/oauth/token.

POST https://openapi-stage-hk.orangeconnex.com/oauth/token

Authorization: Basic application_basic_auth\n>Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=refresh_token

The Basic HTTP Authorization works exactly as in the verification step.