Clearing house API
The ReCiPPS project provides a public API, which can be used by customers to transmit data in an automated way. The clearing house API is accessed via HTTP protocol and uses token based authentication. All information exchange with the API is based on the JSON format.
Authentication
Requests to the API should use the "Authorization" header with the value "Bearer <TOKEN>", where "<TOKEN>" is an access token obtained through the OAuth work flow.
- The client makes a request to the authentication server sending the "<CLIENT_ID>", the "<CLIENT_SECRET>", along with the "<AUDIENCE>". (The support team will provide you the values for "<CLIENT_ID>", "<CLIENT_SECRET>" and "<AUDIENCE>".)
- The authentication server validates the request, and, if successful, sends a response with an access token.
- The client can now use the access token to interact with the API.
- The token expires after after 24 hours and has to be renewed.
Example:
curl -X POST https://c-eco.eu.auth0.com/oauth/token \
--header 'Content-Type: application/json' \
--data '{ "grant_type": "client_credentials",
"client_id": "<CLIENT_ID>",
"client_secret": "<CLIENT_SECRET>",
"audience": "<AUDIENCE>"}'Response
{
"access_token": "<TOKEN>",
"expires_in": 86400,
"token_type": "Bearer"
}API interaction
URL
https://clearinghouse.coremannet.app/api/v1.
Endpoint /options
Description:
This endpoint is used to create options. It requires a JSON string "<Data>" describing the options. To create real Options the VAT id of your company must be the value of "writer". To create options for reporting purpose the VAT id of your company must be the value of "holder".
Example:
curl -X PUT https://clearinghouse.coremannet.app/api/v1/options \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data '<DATA>'Message Content:
{
"transferId": "0bbc3526-d771-46c2-b6c8-5f9ea28fa5cc",
"options": [
{
"writer": "10001",
"holder": "762004",
"expiryDate": "2018-11-23",
"underlying": {
"remanufacturer": "10001",
"partNumber": "851024410"
},
"numberOfOptions": 4,
"surcharge": {
"value": 50.0,
"currency": "eur"
},
"reference": {
"writer": "some order id",
"holder": "some delivery id"
},
},
{ ## next option description
"writer": "10001",
.
.
.
}
]
}with
| Key | Value |
|---|---|
"transferId" |
UUID to identify duplicate transfers (! UUID v4) |
"options" |
list of options to be created |
"writer" |
sells the option and is obligated to accept a returned core, the value is your company's internal reference for the option-writer (or your company's VAT-ID in case your company is the writer) |
"holder" |
owns the option and has the right, but not the obligation to return a core, the value is your company's internal reference for the option-holder (or your company's VAT-ID in case your company is the holder) |
"expiryDate" |
the option is valid until this date 23:59 UTC |
"underlying" |
constract defining the conditions to return a core (e.g. acceptance criteria) |
"remanufacturer" |
the value is your company's internal reference for the remanufacturer that is using this underlying |
"partNumber" |
reman part number or oen |
"numberOfOptions" |
number of options to create, corresponds to the number of purchased reman products |
"surcharge" |
additional fee paid for the reman product, to be returned by the option writer |
"reference.holder" |
allows to connect the option to an order of a reman product, reference given by option-holder e.g. ordernumber |
"reference.writer" |
allows to connect the option to a delivery of a reman product, reference given by option-writer e.g. deliverynumber |
Response:
For successful requests the response body will contain following message
{
"status": "succeeded",
"code": 200,
"message": "Processed successfully"
}In case of unknown data the response body will contain following error messages
{
"status": "failed",
"code": 400,
"message": "IllegalOptionParameter",
"details": {
"key": "illegal-option-parameter-error",
"params": {
"unknownCompanies": "7723"
},
"code": 400
}
}or
{
"status": "failed",
"code": 400,
"message": "IllegalOptionParameter",
"details": {
"key": "illegal-option-parameter-error",
"params": {
"unknownPartNumbers": "851024410"
},
"code": 400
}
}or
{
"status": "failed",
"code": 400,
"message": "DuplicatedTransferId: the transfer id 0bbc3526-d771-46c2-b6c8-5f9ea28fa5cc already exists.",
"details": {
"key": "error.duplicated-transferId",
"params": {
"transferId": "0bbc3526-d771-46c2-b6c8-5f9ea28fa5cc"
},
"code": 400
}
}In case of missing, expired or wring token the response body will contain following error message
{
"status": "failed",
"code": 403,
"message": "Forbidden",
"details": {
"key": "token-error",
"code": 403
}
}In case of unexpected application errors the response body will contain following error message
{
"status": "failed",
"code": 500,
"message": "Internal Server Error",
"details": {
"key": "internal.server.error",
"code": 500
}
}