Documentation

Description

Ticket Distribution creates digital tickets and places them in NOD (National Order Database) for pickup by apps, as well as creating PDF tickets both for download and for emailing to end-users.

Domain types

  • TicketDistribution: Data that forms the basis for a ticket which is sent to NOD and consequently picked up by a client.
  • TicketDistributionGroup: Group of tickets. This always corresponds to an orderLine - and a PDF ticket (if created).
    • There can be more than one TicketDistribution in each group, and there can be more than one TicketDistributionGroup connected to an order.
    • For example, an OrderLine with more than one leg might have more than one TicketDistribution, but only one TicketDistributionGroup.
  • PdfTicket: Printable PDF of a ticket, represents at least one TicketDistribution, and always one TicketDistributionGroup.
    • For example, that same OrderLine with more than one leg will have just one PDF, but that PDF might have several different TicketDistributions connected to it, so there could be several sheets with individual QR codes.

Workflow

  1. After payment is registered for an order, and the order receives the status CONFIRMED, Ticket Distribution automatically creates TicketDistributions and TicketDistributionGroups.
    • There is a /{orderId}/generate endpoint, but a client should only use this endpoint if there is no TicketDistributionGroup available on the search endpoint even after a long delay.
    • It is not possible to generate TicketDistributions for an order that is not CONFIRMED. If an order is paid, but still not CONFIRMED after a long delay, this is possibly a bug in the Order API and has nothing to do with Ticket Distribution.
  2. If a client wants to know when a TicketDistributionGroup is created for an order, use the search endpoint with the orderId and orderVersion parameters. This might take a few seconds at times.
  3. If a PDF ticket is requested by the user, the client should send a request to the /{orderId}/createOrGet endpoint.
    • This does not require the TicketDistributionGroup to be manually created before calling the endpoint. The endpoint will, in fact, wait for the TicketDistributionGroup to be automatically created before generating the PDF.
  4. If the end-user requested the PDF tickets to be sent via email, use the /{orderId}/send endpoint to send the PDFs to the specified email address.
    • The client needs the TicketDistributionIds from the search endpoints for this request, so it has to wait until the TicketDistributionGroups are generated.
    • It is not necessary to use the /{orderId}/createOrGet endpoint first. These two endpoints are for different workflows - one is for downloading the PDF, the other is for sending.
  5. If an Order is later credited or changed so that the tickets are no longer valid, the TicketDistributions will be cancelled, and new ones created if necessary.
    • Note that PDF tickets still exist - though they will no longer give the end-user a right to travel.
    • The client is responsible for verifying that a PDF ticket has not been changed or cancelled. This can be done by checking the Ticket Distribution status (see below).

Checking TicketDistribution status

NOD is limited in its ability to show the validity of a ticket due to architectural constraints. Therefore, it is highly recommended to check validity through this service as well as NOD. The simplest way to do this is to check the ticket-distributions/{ticketDistributionId}/status endpoint, but if you don't have the ticketDistributionId you can use the ticket-distribution-groups endpoint to search instead.

TicketDistribution as a Kafka-producer

TicketDistribution produce TicketDistributionGroupEvents. The Avro-schema for TicketDistributionEvents can be found in the ticket-distribution-repo: src/main/avro/TicketDistributionGroupEvent.avsc

Event-types

TicketDistributionGroupEvents

The following types of TicketDistributionGroupEvents are produced and emitted by TicketDistribution:

  • TicketDistributionActivated
  • TicketDistributionAdded
  • TicketDistributionCancelled
  • TicketDistributionCancelledExternally
  • TicketDistributionDistributed
  • TicketDistributionExpired
  • TicketDistributionFailed
  • TicketDistributionGroupCreated
  • TicketDistributionPickedUp

AllTicketDistributionGroupsForOrderVersionCompletedEvents

The following types of AllTicketDistributionGroupsForOrderVersionCompletedEvents are produced and emitted by TicketDistribution. Note that these are only emitted once all TicketDistributionGroups for an orderVersion are processed.

  • AllTicketDistributionGroupsForOrderVersionGenerated
  • AllTicketDistributionGroupsForOrderVersionDistributed (not yet implemented)

Queues

TicketDistributionGroupEvents

There is one queue per environment, and the queues are named as following:

  • ticket-distribution-group-events-dev
  • ticket-distribution-group-events-staging
  • ticket-distribution-group-events-productions

AllTicketDistributionGroupsForOrderVersionCompletedEvents

There is one queue per environment, and the queues are named as following:

  • all-ticket-distribution-groups-for-order-version-completed-dev
  • all-ticket-distribution-groups-for-order-version-completed-staging
  • all-ticket-distribution-groups-for-order-version-completed-productions

Ticket Distribution API Reference

See the API reference on the Swagger Petstore

l