Init Authorization REST documentation (Swagger)
Welcome!

This is basic information website about Correos Marketplace Merchant API.

Authorization domain:
TEST: 		correos-marketplace.test-comandia.info/oauth
PRODUCTION: market.correos.es/oauth
API domain:
TEST: 		merchant-api-correos-marketplace.test-comandia.info
PRODUCTION: merchant-api.market.correos.es
Standard request parameters

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
Verification

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);
Asking for permissions

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.

Authorization request

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]
Description for authorization request parameters:

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”.
Granting application

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.

Requesting access token

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]]

Description for access token request parameters:

All parameters are required

grant_type

In this process this value must be "authorization_code".

code

Authorization code

client_id

Client API key

client_secret

API secret of your app

Response of access token request:

{
							"token_type": "Bearer",
							"expires_in": 3600,
							"refresh_token": "c183f4b23e338f1471247bb316581a0d",
							"access_token": "afd7de2e5b80acd24e74a1d26994e5f9"
						}

Description for access token response parameters:
token_type

Bearer

expires_in

It shows lifetime of access token, in seconds.

refresh_token

When access token lifetime ends, you can request new access token with refresh token.

Refresh token flow

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]]

Description for request parameters:

All parameters are required

grant_type

In this process this value must be "refresh_token"

refresh_token

Refresh token

client_id

API key

client_secret

API secret of your app

Authorized API requests

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]

Uninstalling App

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