E-tickets / E-invoice APi

Due to many partner requests we have further opened up our internal API gateway to allow our partners from the travel industry to further automate the ticket distribution process to their end clients.

With this api you can donwload

• e-tickets (PDF)
• e-tickets bundled as a zip file
• e-invoice(s) (PDF)

** documentation is subject to modifications **

Ofcourse, if you don't want to use this API you can safely download the tickets through the portal or by xs2ticket

Background

Each booking will result in one or more booking orders. Usually it is a 1-1 relation but in case you made a booking for multiple events you will get one booking with multiple booking orders. Basically, each bookingorder represents the life cycle of a ticket for a given event

In order to download the tickets there are three important steps:

1. Check if your bookingorders are completed
2. Verify the distribution channel
3. Download the etickets from our CDN through the API

Check if the bookingorder is fulfilled

fulfilled means: logistic_status == completed

Fetch all booking orders which you want to check. In order to respect our rate limit use the IN operator so you can check multiple bookings at once

Example call:

/v1/bookingorders?booking_id=in:[716e4d8a84ce416797848cf982b5695f_bkn]&logistic_status=completed

In case you have stored the bookingorder_id you can also use the bookingorder_id as a in query parameter

You will get back an json array object with booking orders which are completed. This list may be empty if no orders are completed In case of testing, please ask your account manager to complete the booking order.

Example response below (only the relevant fields are listed. More fields are present in the output).

{
  'bookingorders': [
    {
      'booking_id': '716e4d8a84ce416797848cf982b5695f_bkn',
      'bookingorder_id': '30fbd3b23f774a9daec4fb16bbd39daa_bkn',
      'logistic_status': 'completed',
      'items': [
        {
          'orderitem_id': '9183473d88e1456da1676f39f00754ff_bkd',
          'distribution_channel': 'xs2event',
          'ticket_sha': 'bef57ec7f53a6d40beb640a780a639c83bc29ac8a9816f1fc6c5c6dcd93c4721',
          'download_link': 'ticket-ehmll.pdf',
          'download_items': []
        }
      ],
      'zip_sha': 'dummysha',
      'invoices': ['12345','56789'],
    }
  ],
  'pagination': {
    'total_size': 1,
    'page_size': 1,
    'next_page': '',
    'previous_page': ''
  }
}

Important fields are:

• bookingorder_id
• orderitem_id (per item!)
• download_link (per item!)

So a bookingorder will have one item per ticket you bought. In case you bought 4 tickets, you will have 4 combinations of orderitem_id and download_link.

At the moment only e-tickets (pdfs) are supported

Distribution channels

In order to comply with the requirements of the event organiser there are 3 different types of distribution channels.

Name	Description	Available for download through XS2Event
xs2event	distribution through xs2event	yes
external	distribution of the tickets is controlled by a 3rd party system such as ticketmaster, stubhub, etc., etc.	no
external_end_client	distribution of the tickets is controlled by the event organiser and tickets will be distributed to the end client by the event organiser (such as Liverpool)	No

The distribution channel may change during the life cycle of a booking

distribution channel is mentioned in the bookingorder response as well as the category response

How to download e-tickets (pdf)

Basically there are two scenarios which we handle technically separate.

• One PDF per ticket
• Multiple PDF per ticket (Formula 1 only, for example friday, saturday and sunday)

Scenario single PDF per booking (default in 99% of the cases)

To download this pdf

/v1/etickets/download/<string:bookingorder_id>/<string:orderitem_id>/url/<string:download_link>

So based on the example response of earlier, the url will be:

/v1/etickets/download/30fbd3b23f774a9daec4fb16bbd39daa_bkn/9183473d88e1456da1676f39f00754ff_bkd/url/ticket-ehmll.pdf

This endpoint will send the file as an attachment; (Content-Disposition: attachment)

Scenario multiple PDFs per booking:

In some cases you can have multiple PDFs for each ticket you bought.

{
  'booking_id': '339676d00b46485792d2610b40a39f48_bkn',
  'bookingorder_id': 'c65853eb7cb94f96812dfe1a6380289c_bkn',
  'event_id': 'c5db17f13bca42d89e35d71bff0e1600_scc',
  'items': [
    {
      'quantity': 1,
      'ticket_id': 'ticket_id',
      'ticket_name': 'title (03/02)',
      'type_ticket': 'eticket',
      'orderitem_id': '3a4587c27c594019a835e76f566d8735_bkd',
      'distribution_channel': "xs2event",
      'download_items': [
        {
          'download_link': 'ticket-xhmyw.pdf',
          'ticket_sha': 'bef57ec7f53a6d40beb640a780a639c83bc29ac8a9816f1fc6c5c6dcd93c4721',
          'downloaditem_id': '39188e794f9d49878a056547577b0a33_dwn',
          'activated': None
        },
        {
          'download_link': 'ticket-urure.pdf',
          'ticket_sha': '9c56cc51b374c3ba189210d5b6d4bf57790d351c96c47c02190ecf1e430635ab',
          'downloaditem_id': '8454b48e82be4ec7b2edb547fa90d005_dwn',
          'activated': None
        }
      ]
    }
  ],
  'created': '2024-01-02T21:48:04',
  'distributor_id': '07e3e392c6d54b81a2e27aabb2406bf5_dst',
  'zip_sha': "12341234"

In the situation of multiple pdfs per item you need to iterate over the download_items. The download_link on item level will be left empty

The url to download the pdf will have the same structure as a single pdf per item, but we will use the download_link of each download_item.

So based on the example above, to download all PDFs you'll use these two URLS:

• /v1/etickets/download/c65853eb7cb94f96812dfe1a6380289c_bkn/3a4587c27c594019a835e76f566d8735_bkd/url/ticket-xhmyw.pdf
• /v1/etickets/download/c65853eb7cb94f96812dfe1a6380289c_bkn/3a4587c27c594019a835e76f566d8735_bkd/url/ticket-urure.pdf

How to download zip file

Each booking order response object will have a zip_sha property in case this property is filled, a zip is available in the backend. Due to the size of this zipfile, the file is served directly from a secured CDN. To retrieve a secure download link you can call:

/v1/etickets/download/zip/<string:bookingorder_id>

This endpoint will return a (plain) link to a cdn file. This link will automatically expire within a short timeframe With this link you can retrieve the actual zip file from the CDN

The zip file contains all the ticket pdfs

CRC/Integrity

For each zip file and pdf file we calculate a SHA 256 CRC string. Our advice is to always check our SHA with the SHA provided in the booking response to avoid any file corruption during download or processing

Monitoring

All access and downloads are logged. Please use the system with respect. Any abuse may result in a (temporary) suspension of your api account.

E-invoice download

To find our e-invoice numbers you can use the same call as specified under "Check if the bookingorder is fulfilled". In this call you will get back a list of bookingorders . Each bookingorder has an array labelled as "invoices". This array contains our unique invoice ids as you can find in the portal as well.

In case you want to download the e-invoice digitally from our system you can use the following call

• v1/bookingorders/c65853eb7cb94f96812dfe1a6380289c_bkn/invoice/12345

Where:

• c65853eb7cb94f96812dfe1a6380289c_bkn: bookingorder id
• 123456: invoice id you get back from the call /v1/bookingorders

Please note that there can be multiple invoices for booking order (invoice, credit invoice) and that each booking may have multiple bookingorders if you buy multiple events at once. For each bookingorder a separate invoice will be created due to tax reasons.