This is basic information website about Correos Marketplace Merchant API.
TEST: correos-marketplace.test-comandia.info/oauth
PRODUCTION: market.correos.es/oauth
TEST: merchant-api-correos-marketplace.test-comandia.info
PRODUCTION: merchant-api.market.correos.es
Here is the sample request from Correos Marketplace authorization server to your application:
POST https://yourapp.example.org/yourcallbackpath
Parameter name | Example value | Type | Description |
---|---|---|---|
merchantid | 1234 | Integer | Unique merchant idendification number |
locale | en | String | Locale code of the merchant user session. This parameter will not be used at authorization flow. |
requestid | 254f6ab71d8f8d3627ac064974e528e0 | String | Unique generated identification per prequest |
hmac | 361e1f12643897a2d33484bec3abc88dad974dc395fcaf34aa0b0027f0b3c1f7 | String | Calculated hash value |
Remove hmac parameter and sort parameters lexicographically by key:
locale=en&merchantid=1234&requestid=254f6ab71d8f8d3627ac064974e528e0
Use your API-SECRET and process string with HMAC-SHA256. Result must be equals to hmac value.
Example verification process for PHP:
$parameters = $_POST;
unset($parameters["hmac"]);
ksort($parameters);
$_POST["hmac"] == hash_hmac('sha256', http_build_query($parameters), $secret);
When merchant users installing your app or requesting your app from merchant backoffice, they will be redirected to your app callback URL:
POST
https://app.domain.tld/callback?merchantid=1&hmac=361e1f12643897a2d33484bec3abc88dad974dc395fcaf34aa0b0027f0b3c1f7&requestid=254f6ab71d8f8d3627ac064974e528e0
If your app is not authenticated by that merchant user before, merchant user will see authorization screen.
To request authorization of merchant user (Requires merchant backoffice session):
https://market.correos.es/oauth/authorize?response_type=code&client_id=[API-KEY]&redirect_uri=[APP-CALLBACK-URL]
Name |
Optional (O) / Required (R ) |
Description |
---|---|---|
client_id |
R |
Client API key |
redirect_uri |
R |
Client callback url Query string parameters not allowed in callback url. |
response_type |
R |
In this process this value must be “code”. |
Right after authorization request step, merchant user will see confirmation screen for granting client app. When users click to authorize button, they will be redirected to your app callback url with additional parameters:
GET
https://app.domain.tld/callback?code=[[authorization code]]&hmac=[[hmac]]&requestid=[[requestid]]
Note: Authorization code can be used once.
When your app get authorization code then you can request access token.
https://market.correos.es/oauth/token?grant_type=authorization_code&code=[[authorization code]]&client_id=[[api key]]&client_secret=[[app secret]]
All parameters are required
In this process this value must be "authorization_code".
Authorization code
Client API key
API secret of your app
Response of access token request:
{
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "c183f4b23e338f1471247bb316581a0d",
"access_token": "afd7de2e5b80acd24e74a1d26994e5f9"
}
Bearer
It shows lifetime of access token, in seconds.
When access token lifetime ends, you can request new access token with refresh token.
Access token will be expired in 1 hour. The client can request new access token with refresh token:
https://market.correos.es/oauth/token?grant_type=refresh_token&refresh_token=[[refresh token]]&client_id=[[api key]]&client_secret=[[app secret]]
All parameters are required
In this process this value must be "refresh_token"
Refresh token
API key
API secret of your app
Each API request must contain Authorization header with authorization type and access token. Also make sure to send User-Agent header correctly:
Authorization=Bearer afd7de2e5b80acd24e74a1d26994e5f9
User-Agent=[Your App or client name]
App will be informed when an app uninstalled by merchant user with GET request with standard request parameters besides status=uninstall
parameter.
https://app.domain.tld/callback?hmac=53bf75904041722cc41dd64fca3a349537ec5eb70bf41d7b7db13de76c210a11&locale=en&merchantid=1&requestid=56b1380875aee9fc4fa12a136a10c25a&status=uninstall