Versions Compared

Old Version 6

changes.mady.by.user Jakob Schlyter

Saved on

compared with

New Version Current

changes.mady.by.user Amanda Rustan

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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. If an eventResult is not provided, the result of the validation is not known and the server is requested to perform online validation. In this case, the entire MTB should always be submitted via a query parameter.

Code Block
languagebash
titleExample request
linenumberstrue
collapsetrue
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
titleExample response
linenumberstrue
collapsetrue
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.

Code Block
languagebash
titleExample request
linenumberstrue
collapsetrue
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"
    }
]
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 by the caller.

Code Block
languagebash
titleExample request
linenumberstrue
collapsetrue
curl --verbose -X GET \
     --header "X-BoB-AuthToken: REDACTED_JWT" \
     https://validation.bob.example.com/api/v1/blacklist?blacklistEntryId=0
Code Block
languagejs
titleExample response
linenumberstrue
collapsetrue
[
    {
        "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
languagebash
titleExample request
linenumberstrue
collapsetrue
curl --verbose -X GET \
     --header "X-BoB-AuthToken: REDACTED_JWT" \
     https://validation.bob.example.com/api/v1/ticklemacros
Code Block
languagejs
titleExample response
linenumberstrue
collapsetrue
[
    {
        "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
languagebash
titleExample request
linenumberstrue
collapsetrue
curl --verbose -X GET \
     --header "X-BoB-AuthToken: REDACTED_JWT" \
     https://validation.bob.example.com/api/v1/ticklemacros/2
Code Block
languagejs
titleExample response
linenumberstrue
collapsetrue
{
    "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

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

...

languagejs
titleExample response
linenumberstrue
collapsetrue

...

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.