= 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 |===