eBay fulfillment openAPI
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 areahttp://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 applicationclient_secret
- secret used to authenticate your applicationredirect_uri
- the uri the OAuth2 server redirect to on authorization requests
Requesting authorization
When you want to authorize a user you redirect him tohttps://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 theredirect_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-urlencodedgrant_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 theredirect_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 expireaccess_token
- the access token used for API requestsrefresh_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-urlencodedgrant_type=refresh_token&refresh_token=
refresh_token
The Basic HTTP Authorization works exactly as in the verification step.
The body of the request consist of the form encoded parameters:
grant_type
- Must be set to "refresh_token".refresh_token
- Therefresh_token
you acquired during verification.
The response will be the same as in the verification step.