Authorization Guidance of New OAuth

A third-party client cannot access the wishpost data without being authorized by the user. Wishpost uses OAuth 2.0 to define the process for third-party clients to access resources. This document will be used to guide users and third-party clients to obtain the authorization for Wishpost OAuth.

To learn how to call the API with an access token, please click here.

Note: third party clients can use our sandbox environment during they carry out docking tests: https://sandbox.wishpost.cn There is no conflict between the new OAuth and the old OAuth at present. You can still use the old OAuth for the existing API. However, the old OAuth may not be applicable for the newly released API. Please refer to the notes in the first step for details.


Specific Terms

  • App

    Third-party client, which usually refers toERP(店小秘等),想要获取wishpost用户数据的应用程序:

    公有的EPR(店小秘等)都有属于自己的client id和client secret,详细公有的ERP列表,请进入hereView

    私有的EPR请进入here,点击私人应用程序进行创建

  • User

    Wishpost users, who can grant third-party clients accesses to the Wishpost user data

  • Access Token

    the access token, which refers to the key of a third-party client to access user data

  • Refresh Token

    refresh token, when an access token expires, you need to use a refresh token to get a new access token


Step 1: Apply for Permissions

Firstly, you need to obtain authorization from the user.

The third-party client needs to guide users into this interface. Users must login Wishpost to click "Accept" to authorize a third-party client:


https://www.wishpost.cn/oauth_v3/authorize?response_type=code& client_id={client_id}&state={state}& scope=user.order.write&force_login={force_login}
  • response_type:which refers to the authorization type, mandatory, where the value is fixed as"code"
  • client_id:which refers to the ID of the client-side, mandatory
  • scope:is the scope of permission applied and options. Please separate difference scopes with space.
  • state:which refers to the current state of the client. You can specify any value, and Wishpost will return the value intactly
  • force_login:Indicates whether to force the user to login again, optional boolean

Note: With scope setting added into the new OAuth, Wishpost APIs will belong to different scopes, and each scope is divided into public and private attributes. Since the existing APIs of Wishpost are all public attributes, if the scopes are not specified, the access tokens obtained can also access all APIs under the public scopes. For the APIs under the private scopes, the third-party client should write the parameters of scopes clearly for the API to be called. If the scope is not specified, the applied access token will be unable to access the API under the private scope. And all the new APIs to be released in future may be private attributes. To apply multiple scopes, please separate them with spaces. Currently, the correspondence between API and scope is as follows:

API nameAPI URLSCOPEPROPERTY
Create orderhttps://www.wishpost.cn/api/v2/create_orderuser.order.write基本
Order statushttps://www.wishpost.cn/api/v3/order_statususer.order.read基本
Get channelhttps://www.wishpost.cn/api/v3/get_channelsuser.order.read基本
Generate lablehttps://www.wishpost.cn/api/v2/generate_labeluser.label.read基本
Get tracking infohttps://www.wishpost.cn/api/v2/trackinguser.tracking.read基本
Get announcementshttps://www.wishpost.cn/api/v3/announcementsuser.announcement.read基本
Get scopeshttps://www.wishpost.cn/api/v3/scopesuser.scope.read基本
Get Account Infohttps://www.wishpost.cn/api/v3/account_infouser.payment.read私有
Get Order Payment

Note

https://www.wishpost.cn/api/v3/get_order_paymentuser.payment.read私有
Download Payment Statementhttps://www.wishpost.cn/api/v3/payment_statement/downloaduser.payment.read私有
Download Payment Statement Check Statushttps://www.wishpost.cn/api/v3/payment_statement/check-statususer.payment.read私有
There will be an API and tools for ERP/third-party clients and users to view the correspondence between the existing API and scope.


Step 2: Get the Authorization Code

After the user clicks "Accept" to authorize the third-party client, Wishpost will jump to the URL of the third-party client at the time of creation:

https://example.redirect.uri.com?code={authorization_code}&state={state}

Authorization_code is the obtained authorization code, which can be used to redeem the access token.

Please note that the authorization code will expire five minutes after it is redeemed and can only be used once.


Step 3: Get the Access Tokens

In order to obtain an access token, the third-party client needs to call the following API with the authorization code obtained from the user to redeem an access token:

POST https://www.wishpost.cn/api/v3/access_token
Header
AuthorizationBasic {client_id:client_secret base64 code}
Content-Typeapplication/x-www-form-urlencoded
Parameters
grant_typeauthorization_code
code{authorization_code}
redirect_uri{same with client redirect url}
client_id{client_id}
  • Header Authorization in Header is the base64 encoding of "Basic" plus "client_id:client_secret"
  • grant_type:which refers to the authorization mode used, mandatory, where the value is fixed as"authorization_code"
  • code:which refers to the authorization code obtained in the previous step, mandatory
  • redirect_uri:which refers to the redirect URI, mandatory, and it must be consistent with the parameters in step A
  • client_id:which refers to the client ID, and it's a required field
Return

{
user_id:{},
username:{},
token_type:{},
access_token:{},
access_token_expires_in:{},
access_token_expiry_time:{},
refresh_token:{},
refresh_token_expires_in:{},
refresh_token_expiry_time:{},
scope:{}
}

Wishpost will return an access token and a refresh token. Third-party clients need to store these two tokens. An access token is used to get the wishpost data and call the API. When an access token expires, the refresh token is used to get a new one access token. Access tokens aretemporary token and is currently valid for 30 days. When an access token expires, please refer to 第5步, Use a refresh token to get a new access token. The expire date of a refresh token is 45 days.

Note: Access tokens will be valid for 1 day and refresh tokens will be valid for 30 days in the future.

Example

Assume your client id was 55c277347770e02e65d4cd83, your client_secret was 123456789012345678901234, your redirect uri was https://example.com and your authorization code was 111222333444555666.

Example Header

Authorization=Basic base64.b64encode(55c277347770e02e65d4cd83:123456789012345678901234)
Content-Type=application/x-www-form-urlencoded

Example Request

格式是x-www-form-urlencoded,不是json
grant_type=authorization_code
code=111222333444555666
redirect_uri=https://example.com
client_id=55c277347770e02e65d4cd83

Example Response

{ 'user_id': '56f98f9aaddd6390e41abfhe',
  'username': 'test',
  'token_type ': 'Bearer',
  'access_token': u'a989812452d34d3f80e0f6e0dc284c31',
  'access_token_expires_in': 2591996,
  'access_token_expiry_time': 1471054161,
  'refresh_token': '62de399b0c4d432124f7f28dfbc9d1c5'
  'scope':['user.order.read', 'user.order.write', 'user.label.read', 'user.tracking.read']
}


Step 4: Call the API with an access token

1. To call the Wishpost API, you need to add the following coding into the request Header:

Authorization: Bearer {access_token}

2. Or you can also put an access token into the request body for existing APIs:

POST https://www.wishpost.cn/api/v2/auth_test
Parameters
access_tokenYour access token

We recommend to put the access_token into the request Header for the newly released API of V3 in the future.

To learn how to call the API with an access token, please click here.


Step 5: Refresh the Access Token

When an access token expires, you can use a refresh token to get a new access token.

POST https://www.wishpost.cn/api/v3/access_token/refresh
Header
AuthorizationBasic {client_id:client_secret base64 code}
Content-Typeapplication/x-www-form-urlencoded
Parameters
grant_typerefresh_token
refresh_token{refresh token}
  • Header Authorization in Header is the base64 encoding of "Basic" plus "client_id:client_secret"
  • grant_type:which refers to the authorization mode used, mandatory, where the value is fixed as "refresh_token"
  • refresh_token:which refers to an update token that was received earlier, mandatory
Return

{
user_id:{},
username:{},
token_type:{},
access_token:{},
access_token_expires_in:{},
access_token_expiry_time:{},
refresh_token:{},
refresh_token_expires_in:{},
refresh_token_expiry_time:{},
scope:{}
}

Note:The expire date of refresh token is 45 days Each third-party app needs two tokens. Authorization needs to be provided again.

Example

Assume your client id was 55c277347770e02e65d4cd83, your client_secret was 123456789012345678901234, and your refresh token was mju7nhy6bgt5vfr4cde3.

Example Header

Authorization=Basic base64.b64encode(55c277347770e02e65d4cd83:123456789012345678901234)
Content-Type=application/x-www-form-urlencoded

Example Request

格式是x-www-form-urlencoded,不是json
grant_type=refresh_token
refresh_token=mju7nhy6bgt5vfr4cde3

Example Response

{ 'user_id': '56f98f9aaddd6390e41abfhe',
  'username': 'test',
  'token_type ': 'Bearer',
  'access_token': u'a989812452d34d3f80e0f6e0dc284c31',
  'access_token_expires_in': 2591996,
  'access_token_expiry_time': 1471054161,
  'refresh_token': '62de399b0c4d432124f7f28dfbc9d1c5'
  'scope':['user.order.read', 'user.order.write', 'user.label.read', 'user.tracking.read']
}


Handling errors and debugging

In the event of an error, the Wishpost API will return an error code and an error message. Some common errors are listed below.

CodeErrorExplanation
1001 Missing Parameter A required parameter was missing in your request. Please review this guide and make sure you included all the necessary parameters.
1002 Invalid Http Header This means that there is a http header format error in your request. Please check your request url and header.
1003 Invalid Xml A xml format error was found in your request. This means that we can't parse the params written in xml in your request. Please check whether there is any xml syntax error.
1005 Connection Failed This means it took too long to receive a response after sending your request. Please make sure there are no problems with your network.
1006 Invalid Header This was always caused by badly formatted authorization header in your request. Please check your authorization format. The right format should be like: Authorization: Bearer <ACCESS-TOKEN >
1007 Access Token Expired Access tokens expire after a period of time. To learn how to renew your access tokens, see Step 5.
1008 Access Token Revoked This means that the access token has been disabled. A common cause for this is the generation of a new access token; when a token is generated, earlier tokens will be revoked. If all tokens are revoked, the user will need to authorize your app again.
1009 Authorization Code Expired Authorization codes expire after a short period of time. When you receive your authorization code at the redirect URI, you should immediately exchange it for an access token.
1010 Access Token Redeemed This means that the authorization code has already been used to redeem a token. For security reasons, each authorization code can only be used once.
1012 Invalid Json A json format error was found in your request. This means that we can't parse the params written in json in your request. Please check whether there is any json syntax error.
4000 Unauthorized Access This means that there was something wrong with the authorization of your request. This error will happen if your access token or authorization code are not recognized.
9000 Unknown This is an unrecognized error, and should rarely happen. Please notify Wish if you receive this error.