Overview

BoB Validation API provides the validation services as well as reporting of already performed validations. Online validation requires validation events to be submitted one by one (via validateTicket). Post-validation reporting of tickets validated offline may be submitted one by one (via validateTicket) or in batch (via reportValidations).

validateTicket

Validate ticket by Ticket ID and return a reference to a ticket event.

Online validation

If an eventResult is not provided, the result of the validation is not known and the server is requested to perform validation. In this case, the entire MTB must be submitted via a query parameter.

Offline validation

If an eventResult is provided, the result of the validation is known and the server does not have to perform validation. In this case, the entire MTB does not need to be submitted via a query parameter.

Code Block

language	bash
title	Example request
linenumbers	true
collapse	true

curl --verbose -X POST --data @- \
     --header "Content-Type: application/json" \
     --header "X-BoB-AuthToken: REDACTED_JWT" \
     https://validation.bob.example.com/api/v1/validation/57e53ddd731adf5bf07d2c12 <<JSON
{
    "ticketEvent": {
         "time": "2016-11-07T13:49:33.638462Z",
         "eventType": "validation",
         "localEventId": "b920d3e2-b1a4-4157-8bfd-c36c2de1fedb",
         "ticketId": "57e53ddd731adf5bf07d2c12",
         "eventResult": 0,
         "mtbReference": {
             "pid": 1,
             "issuerSignature": "tYo2V_Sg9hYNXt9bJ7cyD3L7bUev35uMA2bZ2ykHuWh8NRQD2TbI6C7uWed4ia3Bm2lEa4d3pYVJfUAef39dKA"
         },
         "modeOfTransport": "bus",
         "service": {
             "pid": 1,
             "serviceId": "40",
             "tripId": "42",
             "blockId": "1"
         },
         "zone": {
             "pid": 1,
             "zoneId": "802"
         },
         "validator": {
              "validatorId": "42",
              "location": "1337",
              "sublocation": "door2"
         }
    }
}
JSON

Code Block

title	Example response
linenumbers	true
collapse	true

Location: https://ticketing.bob.example.com/api/v1/ticket/57e53ddd731adf5bf07d2c12/event/1

reportValidations

Already performed validations may be submitted in batch via reportValidations. The entire batch must accepted/rejected – there's no status reporting on individual events. Online validation is not supported.

Code Block

language	bash
title	Example request
linenumbers	true
collapse	true

curl --verbose -X POST --data @- \
     --header "Content-Type: application/json" \
     --header "X-BoB-AuthToken: REDACTED_JWT" \
     https://validation.bob.example.com/api/v1/validation <<JSON
[
    {
        "time": "2016-11-07T13:49:33.638462Z"
        "eventType": "validation",
        "eventResult": 7,
        "localEventId": "b920d3e2-b1a4-4157-8bfd-c36c2de1fedb",
        "ticketId": "57e53ddd731adf5bf07d2c12"
    },
    {
        "time": "2016-11-07T13:49:33.638463Z"
        "eventType": "validation",
        "eventResult": 0,
        "localEventId": "b920d3e2-b1a4-4157-8bfd-c36c2de1feff",
        "ticketId": "57e53ddd731adf5bf07d2c13"
    }
]
JSON

getBlacklist

The current ticket/token/traveller blacklist is provided via the getBlacklist call. Only blacklist entries added since the provided blacklistEntryId will be returned. There's no guarantee that the entries will be provided in consecutive order nor that no blacklistEntryId will be skipped.

Blacklist entries may contain an expire property. Expired entries may be discarded/ignored by the caller.

Code Block

language	bash
title	Example request
linenumbers	true
collapse	true

curl --verbose -X GET \
     --header "X-BoB-AuthToken: REDACTED_JWT" \
     https://validation.bob.example.com/api/v1/blacklist?blacklistEntryId=0

Code Block

language	js
title	Example response
linenumbers	true
collapse	true

[
    {
        "blacklistEntryId": 1,
        "ticketId": "58A0FE79-7A7D-4CF8-BF12-5A01E92C3618",
        "expire": "19730614T000000Z"
    },
    {
        "blacklistEntryId": 2,
        "travellerId": "95054657-F282-43DF-805E-38B039F93856"
    },
    {
        "blacklistEntryId": 3,
        "tokenId": "FB476809-1A70-4046-B337-06422DC3602A"
    }
]

getAllTickleMacrosets

All currently in use TICKLE macro sets are provided via the getAllTickleMacrosets call. There's no expire mechanism and validators are expected to update macros periodically.

Code Block

language	bash
title	Example request
linenumbers	true
collapse	true

curl --verbose -X GET \
     --header "X-BoB-AuthToken: REDACTED_JWT" \
     https://validation.bob.example.com/api/v1/ticklemacros

Code Block

language	js
title	Example response
linenumbers	true
collapse	true

[
    {
        "pid": 1,
        "serial": 1,
        "macros": [
            {
                "condition": "@R/2016W016/P1W/P2D",
                "name": "#weekends"
            },
            {
                "condition": "@R/20160101T1800/P1D/PT6H",
                "name": "#evenings"
            }
        ]
    },
    {
        "pid": 1,
        "serial": 2,
        "macros": [
            {
                "condition": "@20160101 | @20160106 | @20160325 | @20160326 | @20160327 | @20160328 | @20160501 | @20160505 | @20160514 | @20160515 | @20160606 | @20160624 | @20160625 | @20161105 | @20161224 | @20161225 | @20161226 | @20161231",
                "name": "#holidays"
            },
            {
                "condition": "@R/2016W016/P1W/P2D",
                "name": "#weekends"
            },
            {
                "condition": "@R5/2016W071/P1D",
                "name": "#winterSportsHoliday"
            },
            {
                "condition": "#weekends | #winterSportsHoliday | #holidays",
                "name": "#schoolHolidays"
            },
            {
                "condition": "@R/20160101T1800/P1D/PT6H",
                "name": "#evenings"
            }
        ]
    }
]

getTickleMacroset

A single TICKLE macro sets is provided via the getTickleMacroset call.

Code Block

language	bash
title	Example request
linenumbers	true
collapse	true

curl --verbose -X GET \
     --header "X-BoB-AuthToken: REDACTED_JWT" \
     https://validation.bob.example.com/api/v1/ticklemacros/2

Code Block

language	js
title	Example response
linenumbers	true
collapse	true

{
    "pid": 1,
    "serial": 2,
    "macros": [
        {
            "condition": "@20160101 | @20160106 | @20160325 | @20160326 | @20160327 | @20160328 | @20160501 | @20160505 | @20160514 | @20160515 | @20160606 | @20160624 | @20160625 | @20161105 | @20161224 | @20161225 | @20161226 | @20161231",
            "name": "#holidays"
        },
        {
            "condition": "@R/2016W016/P1W/P2D",
            "name": "#weekends"
        },
        {
            "condition": "@R5/2016W071/P1D",
            "name": "#winterSportsHoliday"
        },
        {
            "condition": "#weekends | #winterSportsHoliday | #holidays",
            "name": "#schoolHolidays"
        },
        {
            "condition": "@R/20160101T1800/P1D/PT6H",
            "name": "#evenings"
        }
    ]
}

fraudcheck

The fraudcheck call results in a velocity calculated as follows:

The caller provides a reference to a MTB, a time and geographical position
The callee looks up the time and geographical position of the last ticket event for the given MTB
The callee returns the calculated velocity given the time/geopos

The response must only be given once per validation event and client. Velocity less than km/h or distances less than 1 km shall render 0 km/h.

The resulting velocity is used to determine possible fraud. If the velocity is higher than any available mode of transportation, the ticket has most likely been copied and presented at different locations.

Code Block

language	bash
title	Example request
linenumbers	true
collapse	true

curl --verbose -X POST --data @- \
     --header "Content-Type: application/json" \
     --header "X-BoB-AuthToken: REDACTED_JWT" \
     https://validation.bob.example.com/api/v1/fraudcheck <<JSON
{
    "time": "20161224T140000Z",
    "geoPosition": {
        "lat": 57.770351,
        "lon": 12.255959
    },
    "mtbReference": {
        "pid": 1,
        "issuerSignature": "tYo2V_Sg9hYNXt9bJ7cyD3L7bUev35uMA2bZ2ykHuWh8NRQD2TbI6C7uWed4ia3Bm2lEa4d3pYVJfUAef39dKA"
    }
}
JSON

...

language	js
title	Example response
linenumbers	true
collapse	true

...

Version information

For Validation API there are three versions:

Version 1 is included in major profile 2017-1

Version 2 is included in major profile 2019-1

Version 3 is included in major profile 2020-1

See BoB major release profiles for a more detailed description of these profiles.

Versions Compared

Old Version 9

New Version Current

Key

Overview

validateTicket

Online validation

Offline validation

reportValidations

getBlacklist

getAllTickleMacrosets

getTickleMacroset

fraudcheck

Version information

Page Comparison

Versions Compared

Old Version 9

New Version Current

Key

Overview

validateTicket

Online validation

Offline validation

reportValidations

getBlacklist

getAllTickleMacrosets

getTickleMacroset

fraudcheck

Version information