The Revenue Settlement and Sharing System (RSS) GE is in charge of distributing the revenues originated by the usage of a given service among the involved stakeholders. In particular, it focuses on distributing part of the revenue generated by a service between the Store Provider and the Service Provider(s) responsible for the service. With the term "service" we refer to both final applications and backend application services (typically exposed through an API). Note that, in the case of composite services, more than one service provider may have to receive a share of the revenues.
Additionally, as a supplementary functionality, expenditure limits functionality is offered in this GE. The expenditure limit API provides a mechanism through which an application provider can limit the amount of money spent by a customer using the services, along a specific time interval.
This document describes the RSS Rest API, including the Stores API, Providers API, Revenue Sharing Models API, CDRs API, and Expenditure Limits API.
This is a work in progress and is changing on a daily basis. You can check the latest available version on: https://github.com/conwetlab/wstore/tree/develop. Please send your comments to rss@conwet.com.
This specification is licensed under the FIWARE Open Specification License
Each HTTP request against the RSS API requires the inclusion of specific authentication credentials. The specific implementation of this API may support multiple authentication schemes (OAuth, Basic Auth, Token) and will be determined by the specific provider that implements the GE. Please contact the provider to determine the best way to authenticate against this API. Remember that some authentication schemes may require that the API operates using SSL over HTTP (HTTPS).
The RSS provides support for Cookie and OAuth2 authentication being OAuth2 the default in FIWARE Lab.
| HTTP Code | Type | Description |
|---|---|---|
| 200 | OK | Your request has been completed properly |
| 201 | Created | Your resource has been created. |
| 202 | Accepted | Your request has been accepted for processing. |
| 204 | No content | Your request has been processed, but a response is not available. Generally used when deleting entities |
| 400 | Bad Request | The content of your request is not correct (e.g. There is a missing field) |
| 409 | Conflict | The resource you are tring to create already exists |
| 404 | Not Found | The resource you are looking for does not exists |
| 403 | Forbidden | You have no rights to perform the request |
| 401 | Unauthorized | You are not logged in or the Authorization token you are providing is not valid |
| 500 | Internal server error | There was an internal error in the system so your request cannot be completed |
API for the management of aggregators that play the role of charging information sources. This API allows to register and retrieve aggregators information.
This API uses the following fields:
aggregatorName - Display name of the given aggregator
aggragtorId - Email used to identify the user that is authorized to send changing information (typically an admin of a Store instance)
API for the management of providers. Providers are registered in the context of an aggregator, and are the owners of the applications and services that generate the charging information. This API allows to retrieve and register providers.
This API manages the following fields:
aggregatorId - Aggregator email that identifies the charging information source (Store instance)
providerId - Id of the given provider. Note that this id only needs to be unique in the context of an aggregator, so the same providerId can be used for different providers if the aggregator is different
providerName - Display name of the given provider
API for the management of supported Algorithms. Supported algorithms are those that can be used to perform the revenue sharing. This API allows to retrieve supported algorithms
This API manages the following fields:
algorithmId - ID of the given algorithm
description - A textual description that explains how the algorithm works
API for the management of revenue sharing models. A Revenue Sharing Model specifies how the revenues must be distributed between the involved stakeholders. This API allows to retrieve, create, update, and delete revenue sharing models.
This API manages the following fields:
ownerProviderId - Provider Id of the owner of the model. This provider is the owner of the application and services whose revenues will be distributed using the Revenue Sharing Model
ownerValue - Value of the owner provider in the Revenue Sharing Model. The semantics of this field depends on the algorithm specified, for example if the algorithm is a fixed precentage, this field will contain the percetage of the revenue that belongs to the owner provider.
productClass - Id of the Revenue Sharing Model. This field represents a group of services or applications whose revenues are distributed in the same way
algorithmType - ID of the algorithm that is used in this model
aggregatorId - Id of the aggregator that represents the Store instance where the applications and services are offered, and thus, must receive part of the revenues
aggregatorValue - Value of the aggregator in the Revenue Sharing Model
stakeholders - List of providers that are stakeholders of the applications and services included in a given product class, and thus, must receive part of the revenues. For each stakeholder the following fields are included:
API for the management of CDR documents describing transactions. This API allows to register and retrieve transactions. Additionally, this API allows to launch the settlement process that aggregates the transactions and calculates the distribution of revenues.
This API manages the following fields:
cdrSource - Id of the aggregator that represent the Store instance that is generating the charging information
productClass - Product Class used to identify the revenue sharing model that will be used to distribute the revenues generated in the current transaction
correlationNumber - Correlation number of the transaction
timestamp - Timestamp of the transaction
application - Textual field with the id of the application or service that generates the transaction
transactionType - Type of transaction. This field can contain "C" for charges and "R" for refunds
event - Textual field that describes the event that generated the transaction (e.g pay-per-use)
referenceCode - Reference code that identifies the purchase in the Store instance that generates the transaction
description - Textual description of the transaction
chargedAmount - Part of the total charged amount to be distributed. The total amount charged to the customer includes also the field chargedTaxAmount
chargedTaxAmount - Part of the total charged amount that are taxes. The total amount charged to the customer includes also the field chargedAmount
currency - Currency of the transaction
customerId - Id of the customer that acquires the given service or application
appProvider - provider Id of the owner of the charged applications or services
API for the management of expenditure limits. This API allows to define a couple of limits that allow to control the maximun expenses of customers in different periods of time. This API allows to list, create, modify, and delete expenditure limits.
This API manages the following fields:
service - Service where the limits are applied
limits - List of expenditure limits. Each limit has the following fields:
Note that only a limit can be defined for a given type and a given currency.
This API allows to manage limits for both providers and users. It is important to remark that provider limits are used as the default limits applied, if the user has not defined its own limits.
API for the management of accumulated balances. Accumulated balances are the total expenses used to check the expenditure limits. This API allows to retrieve, check and update balances.
This API manages the following fields:
service - Service where the limits are applied
appProvider - Provider where limits are applied
accums - List of accumulated balances for the existing expenditure limits
type - Period of time of the balance. This field can contain perTransaction, daily, weekly, and monthly
currency - Currency of the balance
nextPeriodStartDate - Start time of the next period for the given accumulated balance
expensedAmount - Total amount accumulated
chargeType - Type of transaction. This value can contain "C" for charges and "R" for refunds
amount - Amount charged in a transaction
Headers
Authorization: Bearer YOUR_OAUTH2_TOKENHeaders
Content-Type: application/jsonBody
[
{
"aggregatorName": "WStore",
"aggregatorId": "fdelavega@conwet.com"
}
]
Headers
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH2_TOKENBody
{
"aggregatorName": "WStore",
"aggregatorId": "fdelavega@conwet.com"
}
Headers
Authorization: Bearer YOUR_OAUTH2_TOKENHeaders
Content-Type: application/jsonBody
[
{
"aggregatorId": "fdelavega@conwet.com",
"providerId": "conwet",
"providerName": "CoNWeT"
}
]
Headers
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH2_TOKENBody
{
"aggregatorId": "fdelavega@conwet.com",
"providerId": "conwet",
"providerName": "CoNWeT"
}
Headers
Authorization: Bearer YOUR_OAUTH2_TOKENHeaders
Content-Type: application/jsonBody
[
{
"algorithmId": "FIXED_PERCENTAGE",
"description": "Fixed percentage distribution of revenues"
}
]
Headers
Authorization: Bearer YOUR_OAUTH2_TOKENHeaders
Content-Type: application/jsonBody
[
{
"ownerProviderId": "fdelavega",
"ownerValue": 60,
"productClass": "orionServices",
"algorithmType": "FIXED_PERCENTAGE",
"aggregatorId": "fdelavega@conwet.com",
"aggregatorValue": 20,
"stakeholders": [
{
"stakeholderId": "aarranz",
"modelValue": 20
}
]
}
]
Headers
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH2_TOKENBody
{
"ownerProviderId": "fdelavega",
"ownerValue": 60,
"productClass": "orionServices",
"algorithmType": "FIXED_PERCENTAGE",
"aggregatorId": "fdelavega@conwet.com",
"aggregatorValue": 20,
"stakeholders": [
{
"stakeholderId": "aarranz",
"modelValue": 20
}
]
}
Headers
Authorization: Bearer YOUR_OAUTH2_TOKENHeaders
Content-Type: application/jsonBody
[
{
"cdrSource": "fdelavega@conwet.com",
"productClass": "orionServices",
"correlationNumber": 112,
"timestamp": "2015-07-15T19:00:01.000Z",
"application": "OrionStarterKit",
"transactionType": "C",
"event": "use",
"referenceCode": "555b079d8e05ac213ff15827",
"description": "Usage of OrionStarterKit Offering",
"chargedAmount": 10,
"chargedTaxAmount": 3,
"currency": "EUR",
"customerId": "amagan",
"appProvider": "fdelavega"
}
]
Headers
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH2_TOKENBody
{
"cdrSource": "fdelavega@conwet.com",
"productClass": "orionServices",
"correlationNumber": 112,
"timestamp": "2015-07-15T19:00:01.000Z",
"application": "OrionStarterKit",
"transactionType": "C",
"event": "use",
"referenceCode": "555b079d8e05ac213ff15827",
"description": "Usage of OrionStarterKit Offering",
"chargedAmount": 10,
"chargedTaxAmount": 3,
"currency": "EUR",
"customerId": "amagan",
"appProvider": "fdelavega"
}
Headers
Authorization: Bearer YOUR_OAUTH2_TOKENHeaders
Authorization: Bearer YOUR_OAUTH2_TOKENHeaders
Content-Type: application/jsonBody
{
"service": "fiware",
"limits": [
{
"type": "perTransaction",
"currency": "EUR",
"maxAmount": 100,
},
{
"type": "weekly",
"currency": "GBP",
"maxAmount": 500
},
{
"type":"daily",
"currency": "EUR",
"maxAmount": 200
},
{
"type":"monthly",
"currency": "EUR",
"maxAmount": 5000
},
{
"type":"monthly",
"currency": "GBP",
"maxAmount": 3000
}
]
}
Headers
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH2_TOKENBody
{
"service": "fiware",
"limits": [
{
"type": "perTransaction",
"currency": "EUR",
"maxAmount": 100,
},
{
"type": "weekly",
"currency": "GBP",
"maxAmount": 500
},
{
"type":"daily",
"currency": "EUR",
"maxAmount": 200
},
{
"type":"monthly",
"currency": "EUR",
"maxAmount": 5000
},
{
"type":"monthly",
"currency": "GBP",
"maxAmount": 3000
}
]
}
Headers
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH2_TOKENHeaders
Authorization: Bearer YOUR_OAUTH2_TOKENHeaders
Content-Type: application/jsonBody
{
"service": "fiware",
"limits": [
{
"type": "perTransaction",
"currency": "EUR",
"maxAmount": 100,
},
{
"type": "weekly",
"currency": "GBP",
"maxAmount": 500
},
{
"type":"daily",
"currency": "EUR",
"maxAmount": 200
},
{
"type":"monthly",
"currency": "EUR",
"maxAmount": 5000
},
{
"type":"monthly",
"currency": "GBP",
"maxAmount": 3000
}
]
}
Headers
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH2_TOKENBody
{
"service": "fiware",
"limits": [
{
"type": "perTransaction",
"currency": "EUR",
"maxAmount": 100,
},
{
"type": "weekly",
"currency": "GBP",
"maxAmount": 500
},
{
"type":"daily",
"currency": "EUR",
"maxAmount": 200
},
{
"type":"monthly",
"currency": "EUR",
"maxAmount": 5000
},
{
"type":"monthly",
"currency": "GBP",
"maxAmount": 3000
}
]
}
Headers
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH2_TOKENHeaders
Authorization: Bearer YOUR_OAUTH2_TOKENHeaders
Content-Type: application/jsonBody
{
"service": "fiware",
"appProvider": "conwet",
"accums": [
{
"type": "weekly",
"currency": "EUR",
"nextPeriodStartDate": "2015-07-15T19:00:01.000Z",
"expensedAmount": 140
},
{
"type": "weekly",
"currency": "GBP",
"nextPeriodStartDate": "2015-07-15T19:00:01.000Z",
"expensedAmount": 100
}
]
}
Headers
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH2_TOKENBody
{
"service": "fiware",
"appProvider": "conwet",
"chargeType": "C",
"currency": "EUR",
"amount": 50
}
Headers
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH2_TOKENBody
{
"service": "fiware",
"appProvider": "conwet",
"chargeType": "C",
"currency": "EUR",
"amount": 50
}
Headers
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH2_TOKENBody
{
"service": "fiware",
"appProvider": "conwet",
"currency": "EUR",
"type": "weekly"
}
The editors would like to express their gratitude to the following people who actively contributed to this specification: Aitor Magán and Álvaro Arranz García.