Version : v1
Host : schemas.mobileticket.se
BasePath : /api/v1
Schemes : HTTPS
POST /ticket |
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.
Type | Name | Description | Schema |
---|---|---|---|
Header | X-BoB-AuthToken | JWT authentication token | string |
Body | manifestCall | Manifest to issue tickets from |
HTTP Code | Description | Schema | |
---|---|---|---|
201 | Successful operation, return identifiers for issued tickets
(string) : URL of created ticket bundle. | ||
400 | Manifest is invalid or from unknown participant | No Content | |
401 | Unauthorised | No Content |
application/json |
GET /ticket |
Get all issued tickets that meets the requirements specified by the
parameters. Which parameters you can filter on are described below.
Type | Name | Description | Schema |
---|---|---|---|
Header | X-BoB-AuthToken | JWT authentication token | string |
Query | active | Filter on active tickets | boolean |
Query | pid | Filter on participant ID requesting the ticket | integer (int64) |
Query | refundable | Filter on refundable tickets | boolean |
Query | refunded | Filter on refunded tickets | boolean |
Query | requestId | Filter on request ID | string |
Query | travellerId | Filter on travellers ID | string |
HTTP Code | Description | Schema |
---|---|---|
200 | Successful operation, return list of tickets. If filter doesn't | < ticket > array |
401 | Unauthorised | No Content |
application/json |
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 |
[ { "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/{ticketId} |
Get data and information about ticket with specified ticket identifier,
issued by this server.
Type | Name | Description | Schema |
---|---|---|---|
Header | X-BoB-AuthToken | JWT authentication token | string |
Path | ticketId | Ticket identifier | string |
HTTP Code | Description | Schema |
---|---|---|
200 | Successful operation | |
401 | Unauthorised | No Content |
404 | Ticket not found | No Content |
application/json |
GET /ticket/{ticketId}/active |
Get active status for ticket with specified ticket identifier.
Type | Name | Description | Schema |
---|---|---|---|
Header | X-BoB-AuthToken | JWT authentication token | string |
Path | ticketId | Ticket id | string |
HTTP Code | Description | Schema |
---|---|---|
200 | Successful operation | |
401 | Unauthorised | No Content |
404 | Ticket not found | No Content |
application/json |
PUT /ticket/{ticketId}/active |
Freeze or thaw ticket with specified ticket identifier.
Type | Name | Description | Schema |
---|---|---|---|
Header | X-BoB-AuthToken | JWT authentication token | string |
Path | ticketId | Ticket identifier | string |
Body | activeStatus | Set to true to thaw ticket, false to freeze. A ticket must be active to be able |
HTTP Code | Description | Schema |
---|---|---|
200 | Successful operation, ticket is now inactive | No Content |
401 | Unauthorised | No Content |
404 | Ticket not found | No Content |
application/json |
GET /ticket/{ticketId}/event |
Get all ticket events for specified ticket identifier. If no
events are available an empty list will be returned.
Type | Name | Description | Schema |
---|---|---|---|
Header | X-BoB-AuthToken | JWT authentication token | string |
Path | ticketId | Ticket identifier | string |
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 |
application/json |
GET /ticket/{ticketId}/event/{eventId} |
Get ticket event specified with event identifier and ticket identifier.
Note! this is the server event identifier and not the local event identfier.
Type | Name | Description | Schema |
---|---|---|---|
Header | X-BoB-AuthToken | JWT authentication token | string |
Path | eventId | Event identifier | string |
Path | ticketId | Ticket identifier | string |
HTTP Code | Description | Schema |
---|---|---|
200 | Successful operation | |
401 | Unauthorised | No Content |
404 | Ticket and event combination not found | No Content |
application/json |
GET /ticket/{ticketId}/recoverStatus |
Type | Name | Description | Schema |
---|---|---|---|
Header | X-BoB-AuthToken | JWT authentication token | string |
Path | ticketId | Ticket identifier | string |
HTTP Code | Description | Schema |
---|---|---|
200 | successful operation | |
401 | Unauthorised | No Content |
404 | Ticket not found | No Content |
application/json |
PUT /ticket/{ticketId}/recoverStatus |
Recover ticket specified with ticket identifier.
Type | Name | Description | Schema |
---|---|---|---|
Header | X-BoB-AuthToken | JWT authentication token | string |
Path | ticketId | Ticket id | string |
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 |
application/json |
GET /ticket/{ticketId}/recoverableStatus |
Get information if ticket specified with ticket identifier is
recoverable. If ticket is refundable also supply information
about recoverable amount and VAT.
Type | Name | Description | Schema |
---|---|---|---|
Header | X-BoB-AuthToken | JWT authentication token | string |
Path | ticketId | Ticket identifier | string |
HTTP Code | Description | Schema |
---|---|---|
200 | successful operation | |
401 | Unauthorised | No Content |
404 | Ticket not found | No Content |
application/json |
GET /ticket/{ticketId}/refundStatus |
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.
Type | Name | Description | Schema |
---|---|---|---|
Header | X-BoB-AuthToken | JWT authentication token | string |
Path | ticketId | Ticket id | string |
HTTP Code | Description | Schema |
---|---|---|
200 | Successful operation | |
401 | Unauthorised | No Content |
404 | Ticket not found | No Content |
application/json |
PUT /ticket/{ticketId}/refundStatus |
Refund ticket specified with ticket identifier.
Type | Name | Description | Schema |
---|---|---|---|
Header | X-BoB-AuthToken | JWT authentication token | string |
Path | ticketId | Ticket id | string |
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 |
application/json |
GET /ticket/{ticketId}/refundableStatus |
Get information if ticket specified with ticket identifier is
refundable. If ticket is refundable also supply information
about refundable amount and VAT.
Type | Name | Description | Schema |
---|---|---|---|
Header | X-BoB-AuthToken | JWT authentication token | string |
Path | ticketId | Ticket id | string |
HTTP Code | Description | Schema |
---|---|---|
200 | successful operation | |
401 | Unauthorised | No Content |
404 | Ticket not found | No Content |
application/json |
PUT /ticket/{ticketId}/revoke |
Set the ticket specified with ticket identifier in revoked state.
When a ticket is in revoked state it can.
Type | Name | Description | Schema |
---|---|---|---|
Header | X-BoB-AuthToken | JWT authentication token | string |
Path | ticketId | Ticket identifier | string |
HTTP Code | Description | Schema |
---|---|---|
200 | Successful operation, ticket in revoved state. | No Content |
401 | Unauthorised | No Content |
404 | Ticket not found | No Content |
application/json |
POST /ticketbundle |
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.
Type | Name | Description | Schema |
---|---|---|---|
Header | X-BoB-AuthToken | JWT authentication token | string |
Body | ticketBundleRequest | List of ticket identifiers of tickets to be included in ticket bundle |
HTTP Code | Description | Schema | |
---|---|---|---|
201 | Successful operation
(string) : URL of created ticket bundle. | ||
400 | All the ticket didn't come from the same ticket bundle | No Content | |
401 | Unauthorised | No Content |
application/json |
GET /ticketbundle/{ticketBundleId} |
Get ticket bundle specified by the ticket bundle identifier
Type | Name | Description | Schema |
---|---|---|---|
Header | X-BoB-AuthToken | JWT authentication token | string |
Path | ticketBundleId | Ticket bundle id | string |
HTTP Code | Description | Schema |
---|---|---|
200 | Successful operation | |
401 | Unauthorised | No Content |
404 | Ticket bundle not found | No Content |
application/json |
Device Reference, unique reference for device that creates device signed tickets
Name | Description | Schema |
---|---|---|
did | Device identifier | string (base64url) |
pid | Participant identifier | integer (int64) |
Fare information, amount, currency and VAT
Name | Description | Schema |
---|---|---|
amount | Fare cost excluding VAT | number (float) |
currency | Currency code (ISO 4217) | string |
vatAmount | VAT amount | number (float) |
vatPercent | VAT percent | number (float) |
Geographical position (WGS84 decimal)
Name | Description | Schema |
---|---|---|
alt | Altitude | number (double) |
lat | Latitude | number (double) |
long | Longitude | number (double) |
Manifest with parameter to be used for issuing tickets
Name | Description | Schema |
---|---|---|
bookingId | Booking identifier from Booking API | string |
issueMtb | Set to true to return MTB when tickets are issued | boolean |
manifestMtbTemplate | Signed manifest with MTB template | string (base64url) |
recoverTicketId | ID of ticket in recover state to be recovered in operation | string |
requestId | Request identifier allocated by manifest requestor | string |
startOfValidity | 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 | Traveller to register as ticket holder |
MTB reference
Name | Description | Schema |
---|---|---|
issuerSignature | MTB issuer signature | string (base64url) |
pid | Participant identifier | integer (int64) |
Recover status
Name | Description | Schema |
---|---|---|
recovered | True if ticket is in recovered state | boolean |
recoveredAmount | Fare recovered |
Tells if ticket is recoverable and amount recoverable
Name | Description | Schema |
---|---|---|
recoverable | Is ticket recoverable | boolean |
recoverableAmount | Recovereable fare |
Refund status
Name | Description | Schema |
---|---|---|
refunded | True if ticket is in refunded state | boolean |
refundedAmount | Fare refunded |
Tells if ticket is refundable and amount refundable
Name | Description | Schema |
---|---|---|
refundable | Is ticket refundable | boolean |
refundableAmount | Refundable fare |
Ticket data and status
Name | Description | Schema |
---|---|---|
activeStatus | Ticket active status | |
issuedAt | Time stamp in ISO 8601 format | string (date-time) |
mtb | Signed MTB container | string (base64url) |
recoverStatus | Ticket recover status | |
refundStatus | Ticket refund status | |
refundableStatus | Ticket refundable status | |
ticketHolder | Ticket holder | |
ticketId | Unique identifier for ticket | string |
ticketPayload | Ticket payload as base64url encoded JSON | string (base64url) |
True if ticket is active and ready to use, otherwise false.
Type : boolean
A group of tickets. All tickets must come from the same manifest
used to issue the tickets.
Name | Description | Schema |
---|---|---|
manifestId | Unique manifest identifier for issued tickets | string |
mtb | Signed MTB container | string (base64url) |
settlementId | Unique settlement identifier for tickets in bundle | string |
ticketBundleId | Unique ticket bundle identifier | string |
ticketIds | Array of identifiers to tickets in bundle | < string > array |
List of ticket identifiers of tickets to be included in ticket bundle
Name | Description | Schema |
---|---|---|
ticketIds | List ticket identifiers | < string > array |
Ticket event data from inspection or validator device
Name | Description | Schema |
---|---|---|
deviceReference | Device Reference, unique reference for device that creates device signed tickets | |
eventId | Event identifier (allocated at event creation) | string |
eventReason | Reason for failure/success | string |
eventResult | 0 = success | integer |
eventType | Type of event, inspection or validation | enum (inspection, validation) |
geo | Geographical position (WGS84 decimal) | |
localEventId | Event identifier (allocated at validation/inspection) | string |
modeOfTransport | Mode of transport. Ex. bus, train or tram. | string |
mtbReference | MTB reference | |
operatingDayDate | Date of the operating day | string (date) |
service | Service information | |
stopArea | Stop area information | |
ticketId | Unique identifier for ticket | string |
time | Time stamp in ISO 8601 format | string (date-time) |
validator | ||
zone | Zone information |
service
Name | Description | Schema |
---|---|---|
blockId | Block identifier | string |
pid | Participant identifier associated with service, trip and block | integer (int64) |
serviceId | Service identifier | string |
tripId | Trip identifier | string |
stopArea
Name | Description | Schema |
---|---|---|
nextStopAreaId | Identifier for next stop area | string |
pid | Participant identifier associated with stop area | integer (int64) |
stopAreaId | Identifier for current stop area | string |
validator
Name | Description | Schema |
---|---|---|
location | Where is validator mounted (vehicle, platform, camel) | string |
sublocation | More specific location information (e.g., door) | string |
validatorId | What validator originated the event | string |
zone
Name | Description | Schema |
---|---|---|
pid | Participant identifier associated with zone | integer (int64) |
zoneId | Zone identifier | string |
The result of a ticket inspection or validation operation registration
Name | Description | Schema |
---|---|---|
ticketEvent | ||
ticketEventInspectMessage | Message to be presented to inspector when registering an inspection event | string |
ticketEventPassengerMessage | Message to be presented to passenger when registering an inspection | string |
ticketEventStatus | Status code for inspection or validation event. This is normally the same | integer (int32) |
ticketMetadata |
Ticket holders name and identifier
Name | Description | Schema |
---|---|---|
travellerId | Unique traveller identifier | string |
travellerName | Display name of traveller | string |
Name | Description | Schema |
---|---|---|
settlementId | Unique settlement identifier for issued tickets | string |
ticketBundle | ||
ticketIds | Array of identifiers to issued tickets | < string > array |
Metadata associated with a ticket
Name | Description | Schema |
---|---|---|
relativeValidityStart | Start of ticket validity period in ISO 8601 format | string (date-time) |
ticketEventIds | List of all event identifiers associated with this ticket | < string > array |
travellerPhotoURL | URL to photo of traveller | string |