BoB Ticket API

Overview

Version information

Version : v1

URI scheme

Host : schemas.mobileticket.se
BasePath : /api/v1
Schemes : HTTPS

Paths

Issue tickets

POST /ticket

Description

Issue tickets from supplied manifest. The manifest should come from the
product server for a matching participant id. Manifests from an unknown
participants, expired manifest or with an illegal signature will be
rejected.

Parameters

Type	Name	Description	Schema
Header	X-BoB-AuthToken required	JWT authentication token	string
Body	manifestCall required	Manifest to issue tickets from	manifestCall

Responses

HTTP Code	Description	Schema
201	Successful operation, return identifiers for issued tickets Headers : location (string) : URL of created ticket bundle.	ticketIssueResponse
400	Manifest is invalid or from unknown participant	No Content
401	Unauthorised	No Content

Produces

```
application/json
```

Tags

ticket

Get issued tickets

GET /ticket

Description

Get all issued tickets that meets the requirements specified by the
parameters. Which parameters you can filter on are described below.

Parameters

Type	Name	Description	Schema
Header	X-BoB-AuthToken required	JWT authentication token	string
Query	active optional	Filter on active tickets	boolean
Query	pid optional	Filter on participant ID requesting the ticket	integer (int64)
Query	refundable optional	Filter on refundable tickets	boolean
Query	refunded optional	Filter on refunded tickets	boolean
Query	requestId optional	Filter on request ID	string
Query	travellerId required	Filter on travellers ID	string

Responses

HTTP Code	Description	Schema
200	Successful operation, return list of tickets. If filter doesn't produce any matches an empty array will be returned.	< ticket > array
401	Unauthorised	No Content

Produces

```
application/json
```

Tags

ticket

Example

Request

curl --verbose -X GET \
     --header "Content-Type: application/json" \
     --header "X-BoB-AuthToken: eyJhbGciOiJFUz.eyJib2JBdXRoWiI6ICJ" \
     https://ticket.bob.example.com/api/v1/ticket?refundable=true&travellerId=trav123

Response 200

[ {
  "ticketId" : "91864",
  "issuedAt" : "20170203T123400Z",
  "ticketPayload" : "",
  "mtb" : "FBWlE0RDFTOFU0NEtZSDA2U",
  "ticketHolder" : {
    "travellerId" : "trav123",
    "travellerName" : "Per Busson"
  },
  "activeStatus" : true,
  "recoverStatus" : {
    "recovered" : false,
  },
  "refundStatus" : {
    "refunded" : false,
  },
  "refundableStatus" : {
    "refundable" : true,
    "refundableAmount" : {
      "amount" : 100.0,
      "currency" : "SEK",
      "vatAmount" : 6.0,
      "vatPercent" : 6.0
    }
  }
} ]

Get ticket data and information

GET /ticket/{ticketId}

Description

Get data and information about ticket with specified ticket identifier,
issued by this server.

Parameters

Type	Name	Description	Schema
Header	X-BoB-AuthToken required	JWT authentication token	string
Path	ticketId required	Ticket identifier	string

Responses

HTTP Code	Description	Schema
200	Successful operation	ticket
401	Unauthorised	No Content
404	Ticket not found	No Content

Produces

```
application/json
```

Tags

ticket

Get ticket active status

GET /ticket/{ticketId}/active

Description

Get active status for ticket with specified ticket identifier.

Parameters

Type	Name	Description	Schema
Header	X-BoB-AuthToken required	JWT authentication token	string
Path	ticketId required	Ticket id	string

Responses

HTTP Code	Description	Schema
200	Successful operation	ticketActiveStatus
401	Unauthorised	No Content
404	Ticket not found	No Content

Produces

```
application/json
```

Tags

ticket

Freeze or thaw ticket

PUT /ticket/{ticketId}/active

Description

Freeze or thaw ticket with specified ticket identifier.

Parameters

Type	Name	Description	Schema
Header	X-BoB-AuthToken required	JWT authentication token	string
Path	ticketId required	Ticket identifier	string
Body	activeStatus required	Set to true to thaw ticket, false to freeze. A ticket must be active to be able to use it.	ticketActiveStatus

Responses

HTTP Code	Description	Schema
200	Successful operation, ticket is now inactive	No Content
401	Unauthorised	No Content
404	Ticket not found	No Content

Produces

```
application/json
```

Tags

ticket

Get ticket events

GET /ticket/{ticketId}/event

Description

Get all ticket events for specified ticket identifier. If no
events are available an empty list will be returned.

Parameters

Type	Name	Description	Schema
Header	X-BoB-AuthToken required	JWT authentication token	string
Path	ticketId required	Ticket identifier	string

Responses

HTTP Code	Description	Schema
200	Successful operation, list of all events for specified ticket identifier.	< ticketEventResult > array
401	Unauthorised	No Content
404	Ticket not found	No Content

Produces

```
application/json
```

Tags

ticket

Get ticket event

GET /ticket/{ticketId}/event/{eventId}

Description

Get ticket event specified with event identifier and ticket identifier.
Note! this is the server event identifier and not the local event identfier.

Parameters

Type	Name	Description	Schema
Header	X-BoB-AuthToken required	JWT authentication token	string
Path	eventId required	Event identifier	string
Path	ticketId required	Ticket identifier	string

Responses

HTTP Code	Description	Schema
200	Successful operation	ticketEventResult
401	Unauthorised	No Content
404	Ticket and event combination not found	No Content

Produces

```
application/json
```

Tags

ticket

Get ticket recover status

GET /ticket/{ticketId}/recoverStatus

Parameters

Type	Name	Description	Schema
Header	X-BoB-AuthToken required	JWT authentication token	string
Path	ticketId required	Ticket identifier	string

Responses

HTTP Code	Description	Schema
200	successful operation	recoverStatus
401	Unauthorised	No Content
404	Ticket not found	No Content

Produces

```
application/json
```

Tags

ticket

Recover ticket

PUT /ticket/{ticketId}/recoverStatus

Description

Recover ticket specified with ticket identifier.

Parameters

Type	Name	Description	Schema
Header	X-BoB-AuthToken required	JWT authentication token	string
Path	ticketId required	Ticket id	string

Responses

HTTP Code	Description	Schema
200	Successful operation, ticket recovered	No Content
400	Ticket could not be recovered	No Content
401	Unauthorised	No Content
404	Ticket not found	No Content

Produces

```
application/json
```

Tags

ticket

Get ticket recoverable status

GET /ticket/{ticketId}/recoverableStatus

Description

Get information if ticket specified with ticket identifier is
recoverable. If ticket is refundable also supply information
about recoverable amount and VAT.

Parameters

Type	Name	Description	Schema
Header	X-BoB-AuthToken required	JWT authentication token	string
Path	ticketId required	Ticket identifier	string

Responses

HTTP Code	Description	Schema
200	successful operation	recoverableStatus
401	Unauthorised	No Content
404	Ticket not found	No Content

Produces

```
application/json
```

Tags

ticket

Get ticket refund status

GET /ticket/{ticketId}/refundStatus

Description

Get information if ticket specified with ticket identifier has
been refunded or not. If ticket was refunded also supply information
about refunded amount and VAT.

Parameters

Type	Name	Description	Schema
Header	X-BoB-AuthToken required	JWT authentication token	string
Path	ticketId required	Ticket id	string

Responses

HTTP Code	Description	Schema
200	Successful operation	refundStatus
401	Unauthorised	No Content
404	Ticket not found	No Content

Produces

```
application/json
```

Tags

ticket

Refund ticket

PUT /ticket/{ticketId}/refundStatus

Description

Refund ticket specified with ticket identifier.

Parameters

Type	Name	Description	Schema
Header	X-BoB-AuthToken required	JWT authentication token	string
Path	ticketId required	Ticket id	string

Responses

HTTP Code	Description	Schema
200	Successful operation, ticket was refunded	No Content
400	Ticket could not be refunded	No Content
401	Unauthorised	No Content
404	Ticket not found	No Content

Produces

```
application/json
```

Tags

ticket

Get ticket refundable status

GET /ticket/{ticketId}/refundableStatus

Description

Get information if ticket specified with ticket identifier is
refundable. If ticket is refundable also supply information
about refundable amount and VAT.

Parameters

Type	Name	Description	Schema
Header	X-BoB-AuthToken required	JWT authentication token	string
Path	ticketId required	Ticket id	string

Responses

HTTP Code	Description	Schema
200	successful operation	refundableStatus
401	Unauthorised	No Content
404	Ticket not found	No Content

Produces

```
application/json
```

Tags

ticket

Revoke ticket

PUT /ticket/{ticketId}/revoke

Description

Set the ticket specified with ticket identifier in revoked state.
When a ticket is in revoked state it can.

Parameters

Type	Name	Description	Schema
Header	X-BoB-AuthToken required	JWT authentication token	string
Path	ticketId required	Ticket identifier	string

Responses

HTTP Code	Description	Schema
200	Successful operation, ticket in revoved state.	No Content
401	Unauthorised	No Content
404	Ticket not found	No Content

Produces

```
application/json
```

Tags

ticket

Create new ticket bundle

POST /ticketbundle

Description

Create a new ticket bundle containing that is a subset of another ticket bundle.
The tickets are specified in the request payload as a list of ticket identfiers.

Parameters

Type	Name	Description	Schema
Header	X-BoB-AuthToken required	JWT authentication token	string
Body	ticketBundleRequest required	List of ticket identifiers of tickets to be included in ticket bundle	ticketBundleRequest

Responses

HTTP Code	Description	Schema
201	Successful operation Headers : location (string) : URL of created ticket bundle.	ticketBundle
400	All the ticket didn't come from the same ticket bundle	No Content
401	Unauthorised	No Content

Produces

```
application/json
```

Tags

ticket

Get ticket bundle

GET /ticketbundle/{ticketBundleId}

Description

Get ticket bundle specified by the ticket bundle identifier

Parameters

Type	Name	Description	Schema
Header	X-BoB-AuthToken required	JWT authentication token	string
Path	ticketBundleId required	Ticket bundle id	string

Responses

HTTP Code	Description	Schema
200	Successful operation	ticketBundle
401	Unauthorised	No Content
404	Ticket bundle not found	No Content

Produces

```
application/json
```

Tags

ticket

Definitions

deviceReference

Device Reference, unique reference for device that creates device signed tickets

Name	Description	Schema
did required	Device identifier	string (base64url)
pid required	Participant identifier	integer (int64)

fare

Fare information, amount, currency and VAT

Name	Description	Schema
amount required	Fare cost excluding VAT	number (float)
currency required	Currency code (ISO 4217)	string
vatAmount required	VAT amount	number (float)
vatPercent required	VAT percent	number (float)

geoPosition

Geographical position (WGS84 decimal)

Name	Description	Schema
alt optional	Altitude	number (double)
lat required	Latitude	number (double)
long required	Longitude	number (double)

manifestCall

Manifest with parameter to be used for issuing tickets

Name	Description	Schema
bookingId optional	Booking identifier from Booking API	string
issueMtb optional	Set to true to return MTB when tickets are issued	boolean
manifestMtbTemplate required	Signed manifest with MTB template	string (base64url)
recoverTicketId optional	ID of ticket in recover state to be recovered in operation	string
requestId optional	Request identifier allocated by manifest requestor	string
startOfValidity optional	Request start of validity set in the future (must be within the validity time of the manifest). Time stamp in ISO 8601 format.	string (date-time)
ticketHolder optional	Traveller to register as ticket holder	ticketHolder

mtbReference

MTB reference

Name	Description	Schema
issuerSignature required	MTB issuer signature	string (base64url)
pid required	Participant identifier	integer (int64)

recoverStatus

Recover status

Name	Description	Schema
recovered required	True if ticket is in recovered state	boolean
recoveredAmount optional	Fare recovered	fare

recoverableStatus

Tells if ticket is recoverable and amount recoverable

Name	Description	Schema
recoverable required	Is ticket recoverable	boolean
recoverableAmount optional	Recovereable fare	fare

refundStatus

Refund status

Name	Description	Schema
refunded required	True if ticket is in refunded state	boolean
refundedAmount optional	Fare refunded	fare

refundableStatus

Tells if ticket is refundable and amount refundable

Name	Description	Schema
refundable required	Is ticket refundable	boolean
refundableAmount optional	Refundable fare	fare

ticket

Ticket data and status

Name	Description	Schema
activeStatus optional	Ticket active status	ticketActiveStatus
issuedAt required	Time stamp in ISO 8601 format	string (date-time)
mtb optional	Signed MTB container	string (base64url)
recoverStatus optional	Ticket recover status	recoverStatus
refundStatus optional	Ticket refund status	refundStatus
refundableStatus optional	Ticket refundable status	refundableStatus
ticketHolder optional	Ticket holder	ticketHolder
ticketId required	Unique identifier for ticket	string
ticketPayload required	Ticket payload as base64url encoded JSON	string (base64url)

ticketActiveStatus

True if ticket is active and ready to use, otherwise false.

Type : boolean

ticketBundle

A group of tickets. All tickets must come from the same manifest
used to issue the tickets.

Name	Description	Schema
manifestId optional	Unique manifest identifier for issued tickets	string
mtb required	Signed MTB container	string (base64url)
settlementId optional	Unique settlement identifier for tickets in bundle	string
ticketBundleId required	Unique ticket bundle identifier	string
ticketIds optional	Array of identifiers to tickets in bundle	< string > array

ticketBundleRequest

List of ticket identifiers of tickets to be included in ticket bundle

Name	Description	Schema
ticketIds required	List ticket identifiers	< string > array

ticketEvent

Ticket event data from inspection or validator device

Name	Description	Schema
deviceReference optional	Device Reference, unique reference for device that creates device signed tickets	deviceReference
eventId optional	Event identifier (allocated at event creation)	string
eventReason optional	Reason for failure/success	string
eventResult optional	0 = success 1 = other failure 2 = failed spatial constraints 3 = failed time constraints 4 = failed device header conditions 5 = failed issuer signature validation 6 = failed device signature validation 7 = failed blacklist check 8 = failed passback check 9 = failed fraud check	integer
eventType optional	Type of event, inspection or validation	enum (inspection, validation)
geo optional	Geographical position (WGS84 decimal)	geoPosition
localEventId optional	Event identifier (allocated at validation/inspection)	string
modeOfTransport optional	Mode of transport. Ex. bus, train or tram.	string
mtbReference optional	MTB reference	mtbReference
operatingDayDate optional	Date of the operating day	string (date)
service optional	Service information	service
stopArea optional	Stop area information	stopArea
ticketId required	Unique identifier for ticket	string
time required	Time stamp in ISO 8601 format	string (date-time)
validator optional		validator
zone optional	Zone information	zone

service

Name	Description	Schema
blockId optional	Block identifier	string
pid required	Participant identifier associated with service, trip and block	integer (int64)
serviceId required	Service identifier	string
tripId optional	Trip identifier	string

stopArea

Name	Description	Schema
nextStopAreaId optional	Identifier for next stop area	string
pid required	Participant identifier associated with stop area	integer (int64)
stopAreaId required	Identifier for current stop area	string

validator

Name	Description	Schema
location optional	Where is validator mounted (vehicle, platform, camel)	string
sublocation optional	More specific location information (e.g., door)	string
validatorId optional	What validator originated the event	string

zone

Name	Description	Schema
pid required	Participant identifier associated with zone	integer (int64)
zoneId required	Zone identifier	string

ticketEventResult

The result of a ticket inspection or validation operation registration

Name	Description	Schema
ticketEvent optional		ticketEvent
ticketEventInspectMessage optional	Message to be presented to inspector when registering an inspection event	string
ticketEventPassengerMessage optional	Message to be presented to passenger when registering an inspection or validation event.	string
ticketEventStatus optional	Status code for inspection or validation event. This is normally the same as the exp	integer (int32)
ticketMetadata optional		ticketMetadata

ticketHolder

Ticket holders name and identifier

Name	Description	Schema
travellerId required	Unique traveller identifier	string
travellerName optional	Display name of traveller	string

ticketIssueResponse

Name	Description	Schema
settlementId required	Unique settlement identifier for issued tickets	string
ticketBundle optional		ticketBundle
ticketIds required	Array of identifiers to issued tickets	< string > array

ticketMetadata

Metadata associated with a ticket

Name	Description	Schema
relativeValidityStart optional	Start of ticket validity period in ISO 8601 format	string (date-time)
ticketEventIds optional	List of all event identifiers associated with this ticket	< string > array
travellerPhotoURL optional	URL to photo of traveller	string

BoB Ticket API

Table of contents

Overview

Version information

URI scheme

Paths

Issue tickets

Description

Parameters

Responses

Produces

Tags

Get issued tickets

Description

Parameters

Responses

Produces

Tags

Example

Get ticket data and information

Description

Parameters

Responses

Produces

Tags

Get ticket active status

Description

Parameters

Responses

Produces

Tags

Freeze or thaw ticket

Description

Parameters

Responses

Produces

Tags

Get ticket events

Description

Parameters

Responses

Produces

Tags

Get ticket event

Description

Parameters

Responses

Produces

Tags

Get ticket recover status

Parameters

Responses

Produces

Tags

Recover ticket

Description

Parameters

Responses

Produces

Tags

Get ticket recoverable status

Description

Parameters

Responses

Produces

Tags

Get ticket refund status

Description

Parameters

Responses

Produces

Tags

Refund ticket

Description

Parameters

Responses

Produces

Tags

Get ticket refundable status

Description