Upgrading to V3

Authentication

The Tour operator API authenticates using an API key for an Agency. Access to multiple administrations is realized by associating channels with the Agency. For the App API, you will need an App to be able to connect. Furthermore, organizations need to install your App, resulting in a Subscription. Each subscription will provide you with an API key or OAuth2 token that can be used to fetch metadata that is part of the organization

Channel Access

In the App API, there are two ways in which channels can be associated to a Subscription:

• Manually
  • Manual selection is enabled when no channel|write permission is configured
  • On installation of the App, the organization user can specify per administration which channel can be used for fetching prices and availability.
• Via the App
  • channel|write permission is required
  • Channels can be created via the API. In this case, the App itself should manage the channels it is using for fetching prices and availability.

Fetching prices & availability

The App API has introduced a 'Channel' namespace for fetching prices and availability. These API calls require you to specify a channel_id, which must be the ID of a channel that has been associated with your App.

Previewing & creating Reservations

Reservations must be created via the Channel namespace, requiring you to pass a channel_id. The Tour operator API only knows the concept of a Reservation, while the App API also introduces the concept of an Booking and a Customer. Where originally you would be able to specify customer and booking data on the Reservation itself, you will now need to split these. The attribute names are mostly the same though. Please see the Booking & Reservations guide for examples.

• after_payment_return_url is now part of the Booking
• coupon_codes and pending_vouchers are now part of the Booking and must be specified as redeemable_codes

A Reservation preview can be created in exactly the same way as creating a Reservation, but it uses a different API endpoint.

Available add-ons (discount cards / primary packages / extras)

Available add-ons can be fetched by including the optional relationships available_discount_cards, available_primary_packages and available_extras when fetching (previewing) a Reservation. The included resources will contain the price of the add-on when it is added to the Reservation.

In the Tour operator API, extras needed to be ordered by using the chosen_extras attribute. In the App API, this is handled via the extra_order_items relationship. To add an extra, you need to specify an ExtraOrderItem that has a relationship to an Extra.

Options

Options are very similar to Reservations, that's why there is no special endpoint anymore for creating Options. To create an Option, you should just create a Reservation in which the attribute option_validity is specified.

The 'All Reservations' Endpoint

The Tour operator API has an experimental endpoint to retrieve all reservations of an administration. The App API just exposes this outside of the Channel namespace in GET reservations. You will need the reservation|read permission to use this. Note that you will also need the booking|read and customer|read permissions to be able to read personal details.