diff --git a/src/event-topics/travel/v4.travel-book-events.md b/src/event-topics/travel/v4.travel-book-events.md new file mode 100644 index 0000000000..035803ca8e --- /dev/null +++ b/src/event-topics/travel/v4.travel-book-events.md @@ -0,0 +1,304 @@ +--- +title: Concur Travel Booking Events +layout: reference +--- + +{% include prerelease.html %} + +## Overview + + +This page will host the documentation for the travel booking information related events that are publicly available on the `public.concur.travel.book` topic in the Event Subscription Service (ESS). +Subscribers to this topic will receive events when travel bookings are performed within SAP Concur. + +To subscribe to these events follow the steps described on the [Event Subscription Service v4](/api-reference/ess/v4.event-subscription.html) page. + +## Limitations +Access to this documentation does not provide access to the subscription. + +## Scope Usage + +Scopes required to interact with this topic: + +Name | Description +----------------------------|------------ +`events.topic.read` | Read events. +`travel.trips.booking.read` | Read booking data. + +## Events + +The topic `public.concur.travel.book` contains events for air and hotel bookings at the moment they are completed. + +## Schema + +### Schema for Booking Event + +Name |Type |Format |Description +---------------|--------|----------------------------------------------|----------- +`id` |`string`|`GUID` |Uniquely identifies the published event. +`correlationId`|`string`|`GUID` |Uniquely identifies the booking request to aid in workflow tracing and troubleshooting. +`eventType` |`string`|- |Identifies the booking event type. Supported values: `travelBookingCompleted`. +`topic` |`string`|- |Topic for subscription. Supported values: `public.concur.travel.book`. +`timeStamp` |`string`|`YYYY-MM-DDTHH:MM:SS.fZ` |Booking event time in UTC. +`facts` |`object`|[Booking Facts](#schema-booking-facts) |Facts for the booking event. +`route` |`string`|- |Routes traffic through the service call tree. Supported values: `stable`. + +### Schema for Booking Facts + +Name |Type |Format |Description +-------------------|---------|------------------------------------------------|----------- +`companyId` |`string` |`GUID` |Uniquely identifies the company of the traveler. +`userId` |`string` |`GUID` |Uniquely identifies the user performing the booking. Note: If the travel is booked by a delegate, this will be the traveler's ID. In cases where a profiled user is booking on behalf of a nonprofiled guest, this will be the user performing the booking. +`delegateUserId` |`string` |`GUID` |Uniquely identifies the delegate user performing this action, if applicable. +`type` |`string` |- |Type of the event. Supported values: `concur.travel.trip.Booking.Completed.v1`. +`version` |`string` |- |Semantic version of the event schema. Example: `1.2.0`. +`trip` |`object` |[TripDetails](#schema-trip-details) |Details about the trip the booking belongs to. +`bookings` |`array` |[BookingDetails](#schema-booking-details) |List of bookings added to the trip. + +### Schema for Booking Details + +Name | Type | Format | Description +----------|----------|--------------------------------------------------------------------------------------------------------|------------ +`id` | `string` | `GUID` | Uniquely identifies the air booking. +`type` | `string` | - | Type of the booking. Supported values: `Air`, `Hotel`. +`details` | `object` | [AirBookingDetails](#schema-air-booking-details), [HotelBookingDetails](#schema-hotel-booking-details) | Details about the booking. The object's type depends on the value of the `type` field. For example, if `type` is `Air`, then `details` will be of type `AirBookingDetails`. + +### Schema for Air Booking Details + +Name |Type |Format |Description +--------------|-------|------------------------------------------------|----------- +`journeys` |`array`|[AirJourneyDetails](#schema-air-journey-details)|List of air journey details. A journey is a portion of a passenger's itinerary between origin and destination. There would be one journey for one-way, two journeys for round trip, and (n+1) journeys for a multi-city trip, where n stands for the number of stopovers. Each journey contains one or more segments. + +### Schema for Air Journey Details + +Name |Type |Format | Description +|----------------------|---------|------------------------------------------------|------------ +|`origin` |`string` |- |IATA airport code of the airport of initial departure. +|`destination` |`string` |- |IATA airport code of the last airport in the journey. +|`departureDateTime` |`string` |`YYYY-MM-DDTHH:MM:SS.f` |Date and time traveler will depart from the point of departure, local time (without offset). +|`departureDateTimeUtc`|`string` |`YYYY-MM-DDTHH:MM:SS.fZ` |Date and time traveler will depart from the point of departure, UTC time. +|`arrivalDateTime` |`string` |`YYYY-MM-DDTHH:MM:SS.f` |Date and time traveler will arrive at the point of arrival, local time (without offset). +|`arrivalDateTimeUtc` |`string` |`YYYY-MM-DDTHH:MM:SS.fZ` |Date and time traveler will arrive at the point of arrival, UTC time. +|`international` |`boolean`|- |Whether the journey is international or not. True for international (crosses a country), False for domestic (within the country). +|`index` |`integer`|- |Zero-based index, representing the order of the journey withing the booking, that the passenger will take to get from booking origin to booking destination(s). +|`segments` |`array` |[AirSegmentDetails](#schema-air-segment-details)|List of air segment details. Segment refers to the portion of a passenger's itinerary that represents a single flight. Technical stops are ignored. + +### Schema for Air Segment Details + +Name |Type |Format |Description +|-----------------------|---------|---------------------------------|------------ +|`origin` |`string` |- |IATA airport code of the point of departure. +|`destination` |`string` |- |IATA airport code of the point of arrival. +|`departureDateTime` |`string` |`YYYY-MM-DDTHH:MM:SS.f` |Date traveler will depart from the point of departure, local time (without offset). +|`departureDateTimeUtc` |`string` |`YYYY-MM-DDTHH:MM:SS.fZ` |Date and time traveler will depart from the point of departure, UTC time. +|`arrivalDateTime` |`string` |`YYYY-MM-DDTHH:MM:SS.f` |Date and time traveler will arrive at the point of arrival, local time (without offset). +|`arrivalDateTimeUtc` |`string` |`YYYY-MM-DDTHH:MM:SS.fZ` |Date and time traveler will arrive at the point of arrival, UTC time. +|`marketingFlightNumber`|`string` |- |The flight number assigned by the airline that sells the ticket. +|`marketingCarrier` |`object` |[AirCarrier](#schema-air-carrier)|Air carrier of the flight segment. +|`international` |`boolean`|- |Whether the segment is international or not. True for international (crosses a country), False for domestic (within the country). +|`index` |`integer`|- |Zero-based index, representing the order of the segment withing the journey. + +### Schema for Air Carrier + +Name |Type |Format| Description +|----------|--------|------|------------ +|`iataCode`|`string`| - |IATA airline carrier code. Example: AA, VA, LH +|`name` |`string`| - |Name of the air carrier. + +### Schema for Hotel Booking Details + +Name |Type |Format |Description +---------------------|--------|-------------------------------------|----------- +`hotel` |`object`|[HotelDetails](#schema-hotel-details)|Details about the hotel. +`checkInDateTime` |`string`|`YYYY-MM-DDTHH:MM:SS.fZ` |Date and time representing the time of check-in in local time (without offset). +`checkOutDateTime` |`string`|`YYYY-MM-DDTHH:MM:SS.fZ` |Date and time representing the time of check-out in local time (without offset). +`checkInDateTimeUtc` |`string`|`YYYY-MM-DDTHH:MM:SS.fZ` |Date and time representing the time of check-in in UTC time. +`checkOutDateTimeUtc`|`string`|`YYYY-MM-DDTHH:MM:SS.fZ` |Date and time representing the time of check-out in UTC time. + +### Schema for Hotel Details + +Name |Type |Format |Description +----------|--------|-----------------------------------------|----------- +`name` |`string`|- |Name of the hotel. +`address` |`object`|[AddressDetails](#schema-address-details)|Details about the hotel address. + +### Schema for Hotel Address Details + +Name | Type | Format | Description +-------------------------|----------|------------------------------------------|------------ +`address1` | `string` | - | Address line 1. +`address2` | `string` | - | Address line 2. +`administrativeAreaName` | `string` | - | Represents the state or federal land or province the hotel is located in. +`postalCode` | `string` | - | Postal code of the hotel. Between 3 and 10 alphanumeric characters, spaces, and hyphens, which covers most international postal code formats. +`localityName` | `string` | - | Name of the city, town, village, or other locality the address is located in. +`countryCode` | `string` | ISO 3166-1 alpha-2 | Two letter code representing the country the hotel is located in. Uses ISO 3166-1 alpha-2 standard. Example: BR. +`geoCoords` | `object` | [GeoLocation](#schema-hotel-geolocation) | Geographic coordinates of the hotel + +### Schema for Hotel Address GeoLocation + +Name | Type | Format | Description +-------|----------|---------|------------ +`lat` | `number` | `float` | Latitude of the location. +`long` | `number` | `float` | Longitude of the location. + +### Schema for Trip Details + +Name|Type |Format|Description +----|--------|------|----------- +`id`|`string`|`GUID`|Uniquely identifies the trip. + +## Sample Events + +### Sample Air Booking Event + +Sample roundtrip air booking + +```json +{ + "id": "51519e89-2c1d-47ec-bd93-7c4ace9c57e6", + "correlationId": "b2fd900a-5935-46fc-8d29-599de9864e21", + "topic": "concur.travel.book", + "eventType": "travelBookingCompleted", + "timeStamp": "2025-04-01T11:01:01.000Z", + "route": "stable", + "facts": { + "userId": "b7d12989-0489-471a-81cd-175f8b78afa5", + "companyId": "ab83bc5f-f66e-4ce0-9dcc-7dbf0195e061", + "delegateUserId": "e5315ec2-5033-4197-b15b-4cec00b838f6", + "type": "concur.travel.trip.Booking.Completed.v1", + "version": "1.0.0", + "trip": { + "id": "8585c3ca-62bd-4585-8f18-f85e331fa7fa" + }, + "bookings": [ + { + "id": "5040b878-da00-47c7-8676-e0f6c67885b5", + "type": "Air", + "details": { + "journeys": [ + { + "origin": "EWR", + "destination": "LAX", + "departureDateTime": "2025-07-01T00:00:00-03:00", + "departureDateTimeUtc": "2025-07-01T05:00:00Z", + "arrivalDateTime": "2025-07-01T16:00:00-03:00", + "arrivalDateTimeUtc": "2025-07-01T21:00:00Z", + "international": false, + "index": 0, + "segments": [ + { + "origin": "EWR", + "destination": "DEN", + "departureDateTime": "2025-07-01T00:00:00-03:00", + "departureDateTimeUtc": "2025-07-01T05:00:00Z", + "arrivalDateTime": "2025-07-01T03:00:00-03:00", + "arrivalDateTimeUtc": "2025-07-01T08:00:00Z", + "marketingFlightNumber": "1111", + "marketingCarrier": { + "iataCode": "AA", + "name": "American Airlines" + }, + "international": false, + "index": 0 + }, + { + "origin": "DEN", + "destination": "LAX", + "departureDateTime": "2025-07-01T05:00:00-03:00", + "departureDateTimeUtc": "2025-07-01T10:00:00Z", + "arrivalDateTime": "2025-07-01T16:00:00-03:00", + "arrivalDateTimeUtc": "2025-07-01T21:00:00Z", + "marketingFlightNumber": "2222", + "marketingCarrier": { + "iataCode": "SW", + "name": "SouthWest Airlines" + }, + "international": false, + "index": 1 + } + ] + }, + { + "origin": "LAX", + "destination": "EWR", + "departureDateTime": "2025-07-07T00:00:00-03:00", + "departureDateTimeUtc": "2025-07-07T05:00:00Z", + "arrivalDateTime": "2025-07-07T16:00:00-03:00", + "arrivalDateTimeUtc": "2025-07-07T21:00:00Z", + "international": false, + "index": 1, + "segments": [ + { + "origin": "LAX", + "destination": "EWR", + "departureDateTime": "2025-07-07T00:00:00-03:00", + "departureDateTimeUtc": "2025-07-07T05:00:00Z", + "arrivalDateTime": "2025-07-07T16:00:00-03:00", + "arrivalDateTimeUtc": "2025-07-07T21:00:00Z", + "marketingFlightNumber": "3333", + "marketingCarrier": { + "iataCode": "DL", + "name": "Delta Airlines" + }, + "international": false, + "index": 0 + } + ] + } + ] + } + } + ] + } +} +``` + +### Sample Hotel Booking Event + +```json +{ + "id": "51519e89-2c1d-47ec-bd93-7c4ace9c57e6", + "correlationId": "b2fd900a-5935-46fc-8d29-599de9864e21", + "eventType": "travelBookingCompleted", + "topic": "concur.travel.book", + "timeStamp": "2025-04-01T11:01:01.000Z", + "route": "stable", + "facts": { + "companyId": "ab83bc5f-f66e-4ce0-9dcc-7dbf0195e061", + "userId": "b7d12989-0489-471a-81cd-175f8b78afa5", + "delegateUserId": "e5315ec2-5033-4197-b15b-4cec00b838f6", + "type": "concur.travel.trip.Booking.Completed.v1", + "version": "1.0.0", + "trip": { + "id": "8585c3ca-62bd-4585-8f18-f85e331fa7fa" + }, + "bookings": [ + { + "id": "5040b878-da00-47c7-8676-e0f6c67885b5", + "type": "Hotel", + "details": { + "hotel": { + "name": "The Ritz-Carlton New York, Central Park", + "address": { + "address1": "50 Central Park S", + "address2": "", + "administrativeAreaName": "NY", + "postalCode": "10019", + "localityName": "New York", + "countryCode": "US", + "geoCoords": { + "lat": 40.755630, + "long": -73.977580 + } + } + }, + "checkInDateTime": "2025-04-02T15:00:00", + "checkInDateTimeUtc": "2025-04-02T20:00:00Z", + "checkOutDateTime": "2025-04-05T16:00:00", + "checkOutDateTimeUtc": "2025-04-05T21:00:00Z" + } + } + ] + } +} +``` \ No newline at end of file