= BoB.Ticket.API


[[_overview]]
== Overview

=== Version information
[%hardbreaks]
__Version__ : v1


=== URI scheme
[%hardbreaks]
__Host__ : schemas.mobileticket.se
__BasePath__ : /api/v1
__Schemes__ : HTTPS




[[_paths]]
== Paths

[[_issuetickets]]
=== Issue tickets from manifest
....
POST /ticket
....


==== Parameters

[options="header", cols=".^2,.^3,.^9,.^4"]
|===
|Type|Name|Description|Schema
|**Header**|**X-BoB-AuthToken** +
__required__|JWT authentication token|string
|**Body**|**manifestCall** +
__required__|Manifest to issue tickets from|<<_manifestcall,manifestCall>>
|===


==== Responses

[options="header", cols=".^2,.^14,.^4"]
|===
|HTTP Code|Description|Schema
|**201**|successful operation +
**Headers** :  +
`location` (string) : URL of created ticket bundle (optional).|<<_ticketissueresponse,ticketIssueResponse>>
|===


==== Produces

* `application/json`


==== Tags

* ticket


[[_getalltickets]]
=== Get issued tickets
....
GET /ticket
....


==== Description
Get all issued tickets that meets the requirements specified
by the parameters.


==== Parameters

[options="header", cols=".^2,.^3,.^9,.^4"]
|===
|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

[options="header", cols=".^2,.^14,.^4"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation|< <<_ticket,ticket>> > array
|===


==== Produces

* `application/json`


==== Tags

* ticket


[[_getticket]]
=== Get ticket by ticket id
....
GET /ticket/{ticketId}
....


==== Parameters

[options="header", cols=".^2,.^3,.^9,.^4"]
|===
|Type|Name|Description|Schema
|**Header**|**X-BoB-AuthToken** +
__required__|JWT authentication token|string
|**Path**|**ticketId** +
__required__|ticket id|string
|===


==== Responses

[options="header", cols=".^2,.^14,.^4"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation|< <<_ticket,ticket>> > array
|===


==== Produces

* `application/json`


==== Tags

* ticket


[[_getticketactivestatus]]
=== Get ticket active status by ticket id
....
GET /ticket/{ticketId}/active
....


==== Parameters

[options="header", cols=".^2,.^3,.^9,.^4"]
|===
|Type|Name|Description|Schema
|**Header**|**X-BoB-AuthToken** +
__required__|JWT authentication token|string
|**Path**|**ticketId** +
__required__|ticket id|string
|===


==== Responses

[options="header", cols=".^2,.^14,.^4"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation|<<_ticketactivestatus,ticketActiveStatus>>
|===


==== Produces

* `application/json`


==== Tags

* ticket


[[_setticketactivestatus]]
=== Freeze or thaw ticket by ticket id
....
PUT /ticket/{ticketId}/active
....


==== Parameters

[options="header", cols=".^2,.^3,.^9,.^4"]
|===
|Type|Name|Description|Schema
|**Header**|**X-BoB-AuthToken** +
__required__|JWT authentication token|string
|**Path**|**ticketId** +
__required__|ticket id|string
|**Body**|**activeStatus** +
__required__||<<_ticketactivestatus,ticketActiveStatus>>
|===


==== Responses

[options="header", cols=".^2,.^14,.^4"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation|No Content
|===


==== Produces

* `application/json`


==== Tags

* ticket


[[_ticketevents]]
=== Get ticket events by Ticket ID
....
GET /ticket/{ticketId}/event
....


==== Parameters

[options="header", cols=".^2,.^3,.^9,.^4"]
|===
|Type|Name|Description|Schema
|**Header**|**X-BoB-AuthToken** +
__required__|JWT authentication token|string
|**Path**|**ticketId** +
__required__|Ticket Identifier|string
|===


==== Responses

[options="header", cols=".^2,.^14,.^4"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation|< <<_ticketeventresult,ticketEventResult>> > array
|**401**|unauthorised|No Content
|**404**|ticket not found|No Content
|===


==== Produces

* `application/json`


==== Tags

* ticket


[[_ticketevent]]
=== Get ticket event by Ticket ID and Event ID
....
GET /ticket/{ticketId}/event/{eventId}
....


==== Parameters

[options="header", cols=".^2,.^3,.^9,.^4"]
|===
|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

[options="header", cols=".^2,.^14,.^4"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation|<<_ticketeventresult,ticketEventResult>>
|**401**|unauthorised|No Content
|**404**|ticket/event not found|No Content
|===


==== Produces

* `application/json`


==== Tags

* ticket


[[_getticketrecoverstatus]]
=== Get ticket recover status by ticket id
....
GET /ticket/{ticketId}/recoverStatus
....


==== Parameters

[options="header", cols=".^2,.^3,.^9,.^4"]
|===
|Type|Name|Description|Schema
|**Header**|**X-BoB-AuthToken** +
__required__|JWT authentication token|string
|**Path**|**ticketId** +
__required__|ticket id|string
|===


==== Responses

[options="header", cols=".^2,.^14,.^4"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation|<<_recoverstatus,recoverStatus>>
|===


==== Produces

* `application/json`


==== Tags

* ticket


[[_setticketrecoverstatus]]
=== Recover ticket by ticket id
....
PUT /ticket/{ticketId}/recoverStatus
....


==== Parameters

[options="header", cols=".^2,.^3,.^9,.^4"]
|===
|Type|Name|Description|Schema
|**Header**|**X-BoB-AuthToken** +
__required__|JWT authentication token|string
|**Path**|**ticketId** +
__required__|ticket id|string
|===


==== Responses

[options="header", cols=".^2,.^14,.^4"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation|No Content
|===


==== Produces

* `application/json`


==== Tags

* ticket


[[_getticketrecoverablestatus]]
=== Get ticket recoverable status by ticket id
....
GET /ticket/{ticketId}/recoverableStatus
....


==== Parameters

[options="header", cols=".^2,.^3,.^9,.^4"]
|===
|Type|Name|Description|Schema
|**Header**|**X-BoB-AuthToken** +
__required__|JWT authentication token|string
|**Path**|**ticketId** +
__required__|ticket id|string
|===


==== Responses

[options="header", cols=".^2,.^14,.^4"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation|<<_recoverablestatus,recoverableStatus>>
|===


==== Produces

* `application/json`


==== Tags

* ticket


[[_getticketrefundstatus]]
=== Get ticket refund status by ticket id
....
GET /ticket/{ticketId}/refundStatus
....


==== Parameters

[options="header", cols=".^2,.^3,.^9,.^4"]
|===
|Type|Name|Description|Schema
|**Header**|**X-BoB-AuthToken** +
__required__|JWT authentication token|string
|**Path**|**ticketId** +
__required__|ticket id|string
|===


==== Responses

[options="header", cols=".^2,.^14,.^4"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation|<<_refundstatus,refundStatus>>
|===


==== Produces

* `application/json`


==== Tags

* ticket


[[_setticketrefundstatus]]
=== Refund ticket by ticket id
....
PUT /ticket/{ticketId}/refundStatus
....


==== Parameters

[options="header", cols=".^2,.^3,.^9,.^4"]
|===
|Type|Name|Description|Schema
|**Header**|**X-BoB-AuthToken** +
__required__|JWT authentication token|string
|**Path**|**ticketId** +
__required__|ticket id|string
|===


==== Responses

[options="header", cols=".^2,.^14,.^4"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation|No Content
|===


==== Produces

* `application/json`


==== Tags

* ticket


[[_getticketrefundablestatus]]
=== Get ticket refundable status by ticket id
....
GET /ticket/{ticketId}/refundableStatus
....


==== Parameters

[options="header", cols=".^2,.^3,.^9,.^4"]
|===
|Type|Name|Description|Schema
|**Header**|**X-BoB-AuthToken** +
__required__|JWT authentication token|string
|**Path**|**ticketId** +
__required__|ticket id|string
|===


==== Responses

[options="header", cols=".^2,.^14,.^4"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation|<<_refundablestatus,refundableStatus>>
|===


==== Produces

* `application/json`


==== Tags

* ticket


[[_setticketrevokestatus]]
=== Revoke ticket by ticket id
....
PUT /ticket/{ticketId}/revoke
....


==== Parameters

[options="header", cols=".^2,.^3,.^9,.^4"]
|===
|Type|Name|Description|Schema
|**Header**|**X-BoB-AuthToken** +
__required__|JWT authentication token|string
|**Path**|**ticketId** +
__required__|ticket id|string
|===


==== Responses

[options="header", cols=".^2,.^14,.^4"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation|No Content
|===


==== Produces

* `application/json`


==== Tags

* ticket


[[_createticketbundle]]
=== Create new ticket bundle from ticketId
....
POST /ticketbundle
....


==== Parameters

[options="header", cols=".^2,.^3,.^9,.^4"]
|===
|Type|Name|Description|Schema
|**Header**|**X-BoB-AuthToken** +
__required__|JWT authentication token|string
|**Body**|**ticketBundleRequest** +
__required__||<<_ticketbundlerequest,ticketBundleRequest>>
|===


==== Responses

[options="header", cols=".^2,.^14,.^4"]
|===
|HTTP Code|Description|Schema
|**201**|successful operation +
**Headers** :  +
`location` (string) : URL of created ticket bundle.|<<_ticketbundle,ticketBundle>>
|===


==== Produces

* `application/json`


==== Tags

* ticket


[[_getticketbundle]]
=== Get ticket bundle by ticket bundle id
....
GET /ticketbundle/{ticketBundleId}
....


==== Parameters

[options="header", cols=".^2,.^3,.^9,.^4"]
|===
|Type|Name|Description|Schema
|**Header**|**X-BoB-AuthToken** +
__required__|JWT authentication token|string
|**Path**|**ticketBundleId** +
__required__|ticket bundle id|string
|===


==== Responses

[options="header", cols=".^2,.^14,.^4"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation|<<_ticketbundle,ticketBundle>>
|===


==== Produces

* `application/json`


==== Tags

* ticket




[[_definitions]]
== Definitions

[[_devicereference]]
=== deviceReference
Device Reference


[options="header", cols=".^3,.^4"]
|===
|Name|Schema
|**did** +
__required__|string (base64url)
|**pid** +
__required__|integer (int64)
|===


[[_fare]]
=== fare

[options="header", cols=".^3,.^11,.^4"]
|===
|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]]
=== geoPosition
Geopos (WGS84 decimal)


[options="header", cols=".^3,.^4"]
|===
|Name|Schema
|**alt** +
__optional__|number (double)
|**lat** +
__required__|number (double)
|**long** +
__required__|number (double)
|===


[[_manifestcall]]
=== manifestCall

[options="header", cols=".^3,.^11,.^4"]
|===
|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__||<<_ticketholder,ticketHolder>>
|===


[[_mtbreference]]
=== mtbReference
MTB Reference


[options="header", cols=".^3,.^11,.^4"]
|===
|Name|Description|Schema
|**issuerSignature** +
__required__|MTB Issuer Signature|string (base64url)
|**pid** +
__required__||integer (int64)
|===


[[_recoverstatus]]
=== recoverStatus

[options="header", cols=".^3,.^11,.^4"]
|===
|Name|Description|Schema
|**recovered** +
__required__|Set if ticket is in recover state|boolean
|**recoveredAmount** +
__required__||<<_fare,fare>>
|===


[[_recoverablestatus]]
=== recoverableStatus

[options="header", cols=".^3,.^4"]
|===
|Name|Schema
|**recoverable** +
__required__|boolean
|**recoverableAmount** +
__required__|<<_fare,fare>>
|===


[[_refundstatus]]
=== refundStatus

[options="header", cols=".^3,.^4"]
|===
|Name|Schema
|**refunded** +
__required__|boolean
|**refundedAmount** +
__required__|<<_fare,fare>>
|===


[[_refundablestatus]]
=== refundableStatus

[options="header", cols=".^3,.^4"]
|===
|Name|Schema
|**refundable** +
__required__|boolean
|**refundableAmount** +
__required__|<<_fare,fare>>
|===


[[_ticket]]
=== ticket

[options="header", cols=".^3,.^11,.^4"]
|===
|Name|Description|Schema
|**activeStatus** +
__optional__||<<_ticketactivestatus,ticketActiveStatus>>
|**issuedAt** +
__required__|Time stamp in ISO 8601 format|string (date-time)
|**mtb** +
__optional__|Signed MTB container|string (base64url)
|**recoverStatus** +
__optional__||<<_recoverstatus,recoverStatus>>
|**refundStatus** +
__optional__||<<_refundstatus,refundStatus>>
|**refundableStatus** +
__optional__||<<_refundablestatus,refundableStatus>>
|**ticketHolder** +
__optional__||<<_ticketholder,ticketHolder>>
|**ticketId** +
__required__||string
|**ticketPayload** +
__required__|Ticket payload as base64url encoded JSON|string (base64url)
|===


[[_ticketactivestatus]]
=== ticketActiveStatus
Set to true to thaw ticket, false to freeze

__Type__ : boolean


[[_ticketbundle]]
=== ticketBundle

[options="header", cols=".^3,.^11,.^4"]
|===
|Name|Description|Schema
|**manifestId** +
__optional__||string
|**mtb** +
__required__|Signed MTB container|string (base64url)
|**settlementId** +
__optional__||string
|**ticketBundleId** +
__required__||string
|**ticketIds** +
__optional__||< string > array
|===


[[_ticketbundlerequest]]
=== ticketBundleRequest

[options="header", cols=".^3,.^4"]
|===
|Name|Schema
|**ticketIds** +
__required__|< string > array
|===


[[_ticketevent]]
=== ticketEvent

[options="header", cols=".^3,.^11,.^4"]
|===
|Name|Description|Schema
|**deviceReference** +
__optional__||<<_devicereference,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__||<<_geoposition,geoPosition>>
|**localEventId** +
__optional__|Event identifier (allocated at validation/inspection)|string
|**modeOfTransport** +
__optional__||string
|**mtbReference** +
__optional__||<<_mtbreference,mtbReference>>
|**operatingDayDate** +
__optional__|Date of the operating day|string (date)
|**service** +
__optional__||<<_ticketevent_service,service>>
|**stopArea** +
__optional__||<<_ticketevent_stoparea,stopArea>>
|**ticketId** +
__required__||string
|**time** +
__required__|Time stamp in ISO 8601 format|string (date-time)
|**validator** +
__optional__||<<_ticketevent_validator,validator>>
|**zone** +
__optional__||<<_ticketevent_zone,zone>>
|===

[[_ticketevent_service]]
**service**

[options="header", cols=".^3,.^4"]
|===
|Name|Schema
|**blockId** +
__optional__|string
|**pid** +
__required__|integer (int64)
|**serviceId** +
__required__|string
|**tripId** +
__optional__|string
|===

[[_ticketevent_stoparea]]
**stopArea**

[options="header", cols=".^3,.^4"]
|===
|Name|Schema
|**nextStopAreaId** +
__optional__|string
|**pid** +
__required__|integer (int64)
|**stopAreaId** +
__required__|string
|===

[[_ticketevent_validator]]
**validator**

[options="header", cols=".^3,.^11,.^4"]
|===
|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
|===

[[_ticketevent_zone]]
**zone**

[options="header", cols=".^3,.^4"]
|===
|Name|Schema
|**pid** +
__required__|integer (int64)
|**zoneId** +
__required__|string
|===


[[_ticketeventresult]]
=== ticketEventResult

[options="header", cols=".^3,.^4"]
|===
|Name|Schema
|**ticketEvent** +
__optional__|<<_ticketevent,ticketEvent>>
|**ticketEventInspectMessage** +
__optional__|string
|**ticketEventPassengerMessage** +
__optional__|string
|**ticketEventStatus** +
__optional__|integer (int32)
|**ticketMetadata** +
__optional__|<<_ticketmetadata,ticketMetadata>>
|===


[[_ticketholder]]
=== ticketHolder

[options="header", cols=".^3,.^4"]
|===
|Name|Schema
|**travellerId** +
__required__|string
|**travellerName** +
__optional__|string
|===


[[_ticketissueresponse]]
=== ticketIssueResponse

[options="header", cols=".^3,.^4"]
|===
|Name|Schema
|**settlementId** +
__required__|string
|**ticketBundle** +
__optional__|<<_ticketbundle,ticketBundle>>
|**ticketIds** +
__required__|< string > array
|===


[[_ticketmetadata]]
=== ticketMetadata

[options="header", cols=".^3,.^4"]
|===
|Name|Schema
|**relativeValidityStart** +
__optional__|string
|**ticketEventIds** +
__optional__|< string > array
|**travellerPhotoURL** +
__optional__|string
|===





