Here you will find a simple description to start developing a connection to Ricardo.
In order to ensure the security of end-users, they should never enter their Ricardo username and password outside an official Ricardo application. Therefore, to allow your application to access these data, we have put in place a two-way authentication process:
1. You have to create a temporary token: call SecurityService.CreateTemporaryCredential
Not mandatory: You can append to this ValidationUrl your own postback url in the querystring parameter “partnerurl”.
JSON Example
POST https://ws.betaqxl.com/ricardoapi/SecurityService.Json.svc/CreateTemporaryCredential HTTP/1.1
Content-Type: application/json
Ricardo-Username: [YOUR_PARTNERSHIP_ID]
Ricardo-Password: [YOUR_PARTNERSHIP_PWD]
Host: ws.betaqxl.com
{
"createTemporaryCredentialParameter": {}
}
You should receive something like this:
{
"CreateTemporaryCredentialResult": {
"TemporaryCredential": {
"ExpirationDate": "\/Date(1385462160000+0100)\/",
"TemporaryCredentialKey": "[TEMPORARY_TOKEN]",
"ValidationUrl": "blablabla"
}
}
}
2. You should then redirect the end-user to the ValidationUrl received, and enter your “normal” Ricardo credentials (the ones you use to log in on the website). When you click on “Authorize!” you should see a page indicating whether it worked or whether an error occurred or you should be redirected to the "partnerurl" you defined previously.
3. Then ask for the “real” token: call SecurityService.CreateTokenCredential, providing the [TEMPORARY_TOKEN] previously received.
JSON Example
POST https://ws.betaqxl.com/ricardoapi/SecurityService.Json.svc/CreateTokenCredential HTTP/1.1
Content-Type: application/json
Ricardo-Username: [YOUR_PARTNERSHIP_ID]
Ricardo-Password: [YOUR_PARTNERSHIP_PWD]
Host: ws.betaqxl.com
{
"createTokenCredentialParameter": {
"TemporaryCredentialKey": "[TEMPORARY_TOKEN]"
}
}
4. You should receive something like this:
{
"CreateTokenCredentialResult": {
"TokenCredential": {
"SessionDuration": 30,
"TokenCredentialKey": "[REAL_TOKEN]",
"TokenExpirationDate": "\/Date(1386664920000+0100)\/"
}
}
}
5. You can then call the other methods provided by the API using this [REAL_TOKEN].
POST https://ws.betaqxl.com/ricardoapi/SellerAccountService.Json.svc/GetTemplates HTTP/1.1
Content-Type: application/json
Ricardo-Username: [YOUR_PARTNERSHIP_ID]
Ricardo-Password: [YOUR_PARTNERSHIP_PWD]
Host: ws.betaqxl.com
{
"getTemplatesParameter": {}
}
The basic idea is that you should ask for a new token once every six months for each client. To do this, your application should have an internal token object with the following properties:
Current key (updated every time you have to refresh your token)
Expiration date (once initialised, this value will never change)
Session duration (once initialised, this value will never change)
Current session expiration date (updated every time you use your token)
When you create your token for the first time (the call to CreateTokenCredential), initialise all the properties of your object with the received values.
Check that your token has not expired (DateTime.Now < YourToken.ExpirationDate). If it has expired, follow the procedure to get a new one.
Check that the session of your token is still valid (DateTime.Now < YourToken.SessionExpirationDate). If it has expired, refresh your token (SecurityService.RefreshTokenCredential method) and update your Token.Key and your Token.SessionExpirationDate with the new values received.
Call all the methods you want, and update your Token.SessionExirationDate (Token.SessionExirationDate = DateTime.Now.AddMinutes(Token.SessionDuration))
In this step, you should also have an exception-catching process, to detect if the API returns an exception to you. For example, if the user manually modifies the date or time of his or her device/computer, your application could think that the token is still valid whereas it is in fact not (and conversely).
Please contact us as soon as you finished developing and testing your application. We then provide you the partnership credentials for our live environment. Make sure to use this URL for the go-live: https://ws.ricardo.ch/ .