Documentation

Description

Ticket Distribution is a service that can be used to show travel information of a ticket for both NOD and ID-based tickets. This makes it easier for clients to show relevant information to customers by using just one service, instead of having to go directly to NOD or ID-Based ticketing. It contains information like the origin and destination stops where the ticket is valid, the validity times, possible supplement products, seat reservations.

Additionally, Ticket Distribution has a few services to make it easier to manipulate tickets in their respective ticketing systems. These services can differ between NOD and ID-Based tickets as specified below.

Services for NOD

Distribute

Tickets can be distributed to NOD using the /v1/ticket-distribution-groups/distribute endpoint.

Update Validity

The validity times of the ticket in NOD can be updated using the /v1/ticket-distribution-groups/update-validities endpoint.

Services for ID-Based tickets

Update Validity

The validity times of ID-based tickets can be updated using the /v1/ticket-distribution-groups/update-validities endpoint.

Transferring tickets to another customer

An ID-based ticket can be transferred to another customer account. This is done by using the /v1/ticket-distribution-groups/transfer-distribution-holder endpoint as found in the API spec. However, there are limitations. Not all products are transferable and a ticket cannot be transferred if the journey has already started.

Domain types

TicketDistributionGroup

Group of TicketDistributions. This always corresponds to an orderLine.

  • 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.

    TicketDistribution

    A TicketDistribution corresponds to a main product on an OrderLine and represents a single ticket. A TicketDistribution contains relevant travel information which can be used to show information about the ticket to the customer. Examples of such information are:

  • The names and ids of the stops/zones the ticket is valid for.

  • Information about the product and userProfile such as the name and id.

  • The times the ticket is valid.

  • Supplement products that are valid for the ticket, such as a bike or a dog.

  • Seat reservations, information about the seat number and carriage number.

  • In case of ID-based tickets the customer account and fareContract to which the ticket belongs.

    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.

  • It is possible to send the PDF directly to the end-user via email by using the /v1/pdf-tickets/{orderId}/send endpoint.

    • There is support for sending the PDF with a custom template, which allows clients to use their own branding and design. This configuration is done by the Entur team, so please contact us if you want to use this feature. Things that can be customized are:
      • The logo
      • The header color
      • The footer text, this can be used for example to add a disclaimer or other information that is relevant to the end-user such as a phone number to call in case of questions.

Workflow

After an order is created

After the Order is CONFIRMED, Ticket Distribution automatically creates TicketDistributions and TicketDistributionGroups. The following kafka events are produced:

  • TicketDistributionGroupCreated for each TicketDistributionGroup created.
  • TicketDistributionAdded for each TicketDistribution added to a TicketDistributionGroup.
  • AllTicketDistributionGroupsForOrderVersionGenerated when all TicketDistributionGroups for an order version are generated. This notifies that ticket-distribution has completed processing the Order.

The statuses of the generated TicketDistributions will differ based on the fulfillmentMethod.

  • For NOD tickets, the status will be CREATED. The client needs to call the /v1/ticket-distribution-groups/distribute endpoint to distribute the tickets to NOD.
  • For ID-based tickets, the status will be DISTRIBUTED and the client does not need to do anything further. The tickets are already available in the ID-based ticketing system.

After an order is updated which results in a new version of said Order

If an order is updated, for example the product has changed or the validity has changed. Ticket Distribution will automatically update the TicketDistributions and TicketDistributionGroups. The following kafka events are produced:

  • TicketDistributionCancelled for each TicketDistribution that is no longer valid. The status of these TicketDistributions will be CANCELLED.
  • TicketDistributionAdded for each new TicketDistribution added to a TicketDistributionGroup. For NOD tickets, the status will be CREATED, and for ID-based tickets, the status will be DISTRIBUTED.
  • TicketDistributionGroupCreated for each new TicketDistributionGroup created. (Corresponds to a new OrderLine being added to an Order)
  • AllTicketDistributionGroupsForOrderVersionGenerated when all TicketDistributionGroups for an order version are generated. This notifies that ticket-distribution has completed processing the Order.

After an orderLine is cancelled

If an orderLine is cancelled, Ticket Distribution will automatically cancel the TicketDistributions. The following kafka events are produced:

  • TicketDistributionCancelled for each TicketDistribution that is no longer valid. The status of these TicketDistributions will be CANCELLED.

A change is done that does not result in a new version of the Order

If a change is done that does not affect the Order version, for example a change of seats, a change of the validity time or a transfer, Ticket Distribution will automatically update the TicketDistributions and TicketDistributionGroups. The following kafka events are produced:

  • TicketDistributionCancelled for each TicketDistribution that is no longer valid. The status of these TicketDistributions will be CANCELLED.
  • TicketDistributionAdded for each new TicketDistribution added to a TicketDistributionGroup. For NOD tickets, the status will be CREATED, and for ID-based tickets, the status will be DISTRIBUTED.

PDF Ticketing

Ticket Distribution can also be used to generate and/or send PDF tickets to the end-user. If a PDF ticket is requested by the user, the client should send a request to the /v1/pdf-tickets/{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.

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.

- It is not necessary to use the `/{orderId}/createOrGet` endpoint first. These two endpoints are for different workflows - one is for receiving the PDF which the client can use as pleased, the other is for sending directly to the customer.

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).

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 by TicketDistribution:

  • TicketDistributionActivated
    • NOT IN USE
  • TicketDistributionAdded
    • A TicketDistribution has been added to a TicketDistributionGroup.
  • TicketDistributionCancelled
    • A TicketDistribution has been cancelled, this can happen if the OrderLine is cancelled or if the Order is updated and the TicketDistribution is no longer valid.
  • TicketDistributionCancelledExternally (NOD ONLY)
    • A TicketDistribution has been cancelled externally, this can happen if the ticket is cancelled directly in NOD.
  • TicketDistributionDistributed
    • A TicketDistribution has been distributed to the respective ticketing system, this can be either NOD or ID-based ticketing.
  • TicketDistributionExpired (NOD ONLY)
    • NOD has expired the ticket.
  • TicketDistributionFailed (NOD ONLY)
    • An error has occurred in NOD, the TicketDistribution is no longer valid, and a new TicketDistribution has been created which can be used to retry the distribution.
  • TicketDistributionGroupCreated
    • A TicketDistributionGroup has been created, this corresponds to an OrderLine and happens automatically when an Order is confirmed
  • TicketDistributionPickedUp (NOD ONLY)
    • The QR Code has been picked up from NOD and cannot be picked up again. This is used to prevent double usage of the QR Code.

AllTicketDistributionGroupsForOrderVersionCompletedEvents

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

  • AllTicketDistributionGroupsForOrderVersionGenerated
    • This event is produced when all TicketDistributionGroups for an order version are generated. This notifies that ticket-distribution has completed processing the Order.
  • AllTicketDistributionGroupsForOrderVersionDistributed
    • This event is produced when all TicketDistributions for an order version are distributed.

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

AllTicketDistributionGroupsForOrderVersionCompletedEvents

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

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

Contact Entur if you want to subscribe to these queues.

Ticket Distribution API Reference

See the API reference on the Swagger Petstore

l