Mobilitybox Ticketing Tariff Settings General Idea
Tariff Settings were introduced with Ticketing API V4. This chapter explains how you can manage tariff settings of a coupon with the Mobilitybox API.
Tariff Settings are used to store different tariff-bound information.
Tariff Settings Schema
When a ticket of a product requires some tariff settings to be created, the attribute tariff_settings_schema
of the product will contain a JSON Schema describing the required settings to be set.
Example:
{
"tariff_settings_schema": {
"type": "object",
"allOf": [
{
"type": "object",
"required": [
"tariffzones"
],
"properties": {
"tariffzones": {
"$ref": "#/definitions/tariffzones"
}
},
"additionalProperties": false
}
],
"$schema": "http://json-schema.org/draft-04/schema#",
"definitions": {
"tariffzones": {
"type": "array",
"items": {
"type": "string",
"pattern": "^(mobilitybox-area-)?.{36}$"
},
"title": "VRS Tarif Zonen Preisstufe 4",
"maxItems": 4,
"minItems": 4,
"uniqueItems": true
}
}
}
}
A coupon will have two new attributes called tariff_settings
and tariff_settings_valid
.
The tariff_settings
attribute will return the currently saved tariff_settings for this coupon (can be null
).
The tariff_settings_valid
attribute will show, if the given tariff_settings
pass the validation of the tariff_settings_schema
of the ordered product
API Add Tariff Settings
For an additional API description checkout the Ticketing API Documentation.
Before a coupon, with required tariff settings, can be activated, you have to add these information. There are two ways for adding tariff settings to a coupon.
Add before activation
To add tariff settings before the activation you have to call the POST /ticketing/coupons/{id}/tariff_settings.json
endpoint.
The passed data has to be a JSON Object that passes the tariff_settings_schema validation present inside the ordered product. You can't add additional information.
You can call this API multiple times and the saved tariff_settings for the coupon will update. It will merge the existing data with the new paramateres.
It will return the updated coupon data.
// body
{
"tariff_settings": {
//...
}
}
ATTENTION: you can't modify the tariff settings after a coupon was activated.
Add while activating
Additionally to the adding endpoint there is the option to add the tariff settings while activating the coupon and add the data to the body of the POST /ticketing/coupons/{id}/activate.json
endpoint.
The data given here will be merged like on the other endpoint with the existing tariff settings data saved for the coupon.
// body
{
"identification_medium": {
//...
},
"tariff_settings": {
//...
}
}
API Remove Tariff Settings
To remove tariff settings before the activation you have to call the DELETE /ticketing/coupons/{id}/tariff_settings.json
endpoint.
You can either pass a list of string for which keys of the tariff settings you want to delete or pass nothing and set the complete tariff settings to null
// body
{
"tariff_settings_keys": ["key1", "key2"]
}
ATTENTION: you can't modify the tariff settings after a coupon was activated.
Tariffzones
One tariff setting is the tariffzones list. When you want to create a multi tariffzone ticket you need to define which tariff zones the ticket should be valid for.
You have to add a list of Mobilitybox Area Ids (["mobilitybox-area-uuid", "mobilitybox-area-uuid2", ...]
).
ATTENTION: Current there is no Validation if the given tariff zones will create a valid ticket. The responsibility to pass a valid set of tariff zones is on your site!