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!