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:
- 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 name | API URL | SCOPE | PROPERTY |
---|---|---|---|
Create order | https://www.wishpost.cn/api/v2/create_order | user.order.write | 基本 |
Order status | https://www.wishpost.cn/api/v3/order_status | user.order.read | 基本 |
Get channel | https://www.wishpost.cn/api/v3/get_channels | user.order.read | 基本 |
Generate lable | https://www.wishpost.cn/api/v2/generate_label | user.label.read | 基本 |
Get tracking info | https://www.wishpost.cn/api/v2/tracking | user.tracking.read | 基本 |
Get announcements | https://www.wishpost.cn/api/v3/announcements | user.announcement.read | 基本 |
Get scopes | https://www.wishpost.cn/api/v3/scopes | user.scope.read | 基本 |
Get Account Info | https://www.wishpost.cn/api/v3/account_info | user.payment.read | 私有 |
Get Order Payment
Note | https://www.wishpost.cn/api/v3/get_order_payment | user.payment.read | 私有 |
Download Payment Statement | https://www.wishpost.cn/api/v3/payment_statement/download | user.payment.read | 私有 |
Download Payment Statement Check Status | https://www.wishpost.cn/api/v3/payment_statement/check-status | user.payment.read | 私有 |
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:
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:
Authorization | Basic {client_id:client_secret base64 code} |
---|---|
Content-Type | application/x-www-form-urlencoded |
grant_type | authorization_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
{
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:
2. Or you can also put an access token into the request body for existing APIs:
access_token | Your 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.
Authorization | Basic {client_id:client_secret base64 code} |
---|---|
Content-Type | application/x-www-form-urlencoded |
grant_type | refresh_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
{
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.
Code | Error | Explanation |
---|---|---|
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. |