Booking

The following APIs let a third-party system sell admission tickets for a merchant's products. A product is an admission (ticket) in e-guma that has been explicitly released for third-party sale by the merchant and assigned to the API key's user.

This article gives an overview of the typical booking flow and lists the endpoints you will use. For details on each endpoint, follow the links in the sections below.

Prerequisites

Before you can call any endpoint:

• The merchant must have created an API key for the integration user and given you its value.
• The admissions (products) you want to sell must have the Third party integrations sales channel enabled and the API key's user must be listed on them.

Booking flow

The typical flow for selling a ticket looks like this:

1. Discover products. Call the List of Products API to get the set of products that are available for sale for this API key, together with their person categories and whether they are sold on a per-day or per-slot basis.
2. Fetch availabilities. For the product the customer picked, call the List of Availabilities API with a date range to get the bookable days or time slots, the price per category, quantity constraints and the cut-off time.
3. (Optional) Reserve the tickets. If some time will pass between the customer's choice and the payment, call the Reserve Tickets API to place a 60-minute hold on the selected availability. This avoids overselling during the checkout.
4. Book the tickets. Once the sale is confirmed on your side (payment captured, etc.), call the Book Tickets API to create the order and issue the tickets. Bookings require an Idempotency-Key header; see the Idempotency article.
5. (If needed) Cancel. Reservations that are no longer needed can be released before they expire with the Cancel Reservation API. Confirmed bookings can be cancelled with the Cancel Booking API as long as the start date is still in the future and no ticket has been checked in.

sequenceDiagram
  participant Client as Third-party system
  participant API as e-guma API

  Client->>API: GET /ticketing/products.json
  API-->>Client: Products + categories

  Client->>API: GET /ticketing/products/{id}/availabilities.json
  API-->>Client: Availabilities + prices

  opt Reservation
    Client->>API: POST /ticketing/reservation.json
    API-->>Client: reservation_id (valid 60 min)
  end

  Client->>API: POST /ticketing/booking.json (Idempotency-Key)
  API-->>Client: booking_id + tickets

  opt Cancellation
    Client->>API: POST /ticketing/cancel-booking.json
    API-->>Client: cancelled_tickets
  end

Endpoints at a glance

Working with IDs and dates

The APIs are designed so that IDs and date values flow directly from one call to the next:

• The id returned by the List of Products API is the product_id expected by the availabilities, reservation and booking endpoints.
• The starts_at returned by the List of Availabilities API is the starts_at expected by the reservation and booking endpoints. For day products the time portion is always 00:00:00; for time products it carries the real slot time.
• The category_id returned by the List of Products API is the category_id expected in the items of reservations and bookings.
• The booking_id returned by the Book Tickets API is what you pass to the Cancel Booking API.

Idempotency, errors and retries

• Write endpoints that require it use an idempotency key, which lets you retry safely without creating duplicates. See the Idempotency article.
• All endpoints return standard HTTP status codes. Error responses have the shape { "error_code": "...", "message": "..." }. Do not parse message for logic; branch on error_code and the HTTP status code.
• Authentication failures return 401 unauthorized. Access to a product that is not enabled for this API key returns 403 forbidden or 404 not_found depending on the cause. Validation problems return 400 validation_error.