TravelCaster API - Flights - ImportBooking operation

Back to Flights home.

The ImportBooking operation imports a booking into the TravelCaster system from its record locator and office ID, making it available to the standard API, back-office and reporting flows.

It covers both cases with a single endpoint: a PNR created outside of the TravelCaster booking flow (directly with a GDS or provider), and a booking that already exists in TravelCaster and is being imported (consolidated). You do not need to know beforehand which of the two you are dealing with.

This operation is only available via the JSON gateway. It is not exposed through the XML or WebService endpoints.

The operation works in two steps: a DISPLAY call previews the import, and a SAVE call confirms it. See The DISPLAY/SAVE flow below.

To call this operation you will need a valid token, obtained previously with the GetAccessToken operation. If your token is no longer valid, you will receive a 1210 error. See the Transaction Codes page for more information.

Request

JSON

http://endpoint/api/version/FlightService.json/ImportBooking [POST]

body - FlightBookingImportRequest (JSON)

returns: FlightImportRetrieveResponse

Structure of the FlightBookingImportRequest object

FlightBookingImportRequest
 |_ Token (string - mandatory)
 |_ TransactionID (string)
 |
 |_ Operation (string - mandatory - DISPLAY or SAVE)
 |_ BookingNumber (string - mandatory - GDS or provider record locator)
 |_ OfficeID (string - mandatory - office/queue ID associated with the record locator)
 |
 |_ Buyer (BuyerInformation - mandatory on SAVE, see notes)
    |_ FirstName (string - mandatory on SAVE)
    |_ LastName (string - mandatory on SAVE)
    |_ Email (string - mandatory on SAVE)
    |_ Telephone (string - optional)
    |_ StreetAddress (string - optional)
    |_ City (string - optional)
    |_ ZipCode (string - optional)
    |_ State (string - optional)
    |_ Country (string - optional)
    |_ Document (string - optional)

Structure of the FlightImportRetrieveResponse object

FlightImportRetrieveResponse extends FlightRetrieveResponse (see the RetrieveBooking operation for the full base structure: BookingNumber, BookingStatus, PaymentStatus, BookingFare, Passengers, Buyer, FormOfPayment, etc.), adding three fields that are only populated for Operation = DISPLAY:

FlightImportRetrieveResponse
 |_ Token (string)
 |_ TransactionID (string)
 |_ TransactionCode (string)
 |_ TransactionMessage (string)
 |
 |_ ...all FlightRetrieveResponse fields (see RetrieveBooking)...
 |
 |_ Warnings (string[] - DISPLAY only)
 |_ Informations (string[] - DISPLAY only)
 |_ AllowedCardPayments (AllowedCardPayment[] - DISPLAY only)
    |_ CardType (string)
    |_ Description (string)
    |_ Surcharge (decimal)
    |_ Installments (string, comma-separated)
    |_ LimitBIN (string, comma-separated)
    |_ AuthRequirementType (string, null/ANY/AUTH/CVV)

Both DISPLAY and SAVE return the same response type.

On a DISPLAY call, nothing is persisted yet, so the base FlightRetrieveResponse fields describe a preview built from the provider data - see BookingStatus/PaymentStatus on DISPLAY below - and Warnings/Informations/AllowedCardPayments carry the DISPLAY-only data.

On a successful SAVE call, only the base FlightRetrieveResponse fields are populated (Warnings/Informations/AllowedCardPayments are null), reflecting the imported booking exactly as RetrieveBooking would return it.

Notes

BookingNumber and OfficeID

These two fields identify the booking to be imported. BookingNumber is the GDS or provider record locator of the PNR, and it is the identifier of the booking in TravelCaster.

The booking does not need to exist in TravelCaster beforehand - both a PNR made outside TravelCaster and a booking already present in TravelCaster can be imported through this operation. When the booking does already exist, it must belong to your API user; otherwise the request is rejected with 2400.

The DISPLAY/SAVE flow

Operation is mandatory and accepts two values (the value is case-insensitive):

  • DISPLAY — previews the import. Nothing is stored: the operation retrieves the PNR from the provider, calculates the applicable service amount, commission policy and allowed card payments, and returns a preview of the booking (with Warnings/Informations/AllowedCardPayments) so you can show it to your user before committing.
  • SAVE — performs the import.

A SAVE is only accepted after a successful DISPLAY for the same record locator, office ID and API user, otherwise the call is rejected with 2503. The rules are:

  • The DISPLAY result is valid for a limited time (20 minutes by default). After that, a SAVE requires a new DISPLAY.
  • The DISPLAY is single use: a successful SAVE consumes it. Importing the same PNR again requires a new DISPLAY.
  • If the DISPLAY itself fails, the call returns the code reported by the underlying import service (1000 if none is provided) with the reason in TransactionMessage.

Missing mandatory parameters are rejected with 2500; an invalid Operation value with 2501.

BookingStatus/PaymentStatus on DISPLAY

The PNR being previewed by a DISPLAY call is not yet imported into TravelCaster, so BookingStatus and PaymentStatus are returned as New (0) — meaning "this is the status the booking would have if you SAVE now", not a persisted state. Once SAVE completes, these reflect the booking's real, persisted status.

DISPLAY-only fields

Warnings, Informations and AllowedCardPayments are populated only for Operation = DISPLAY; null for SAVE.

  • AllowedCardPayments — the card payment methods allowed for the booking. Not returned when no card policy is configured for your account.
  • Warnings — non-blocking messages detected while previewing the import, for example:
    • Import is not allowed if booking has more than 1 stored fare per passenger type
    • DOCS Missing in PNR
    • DOCS is mandatory
  • Informations — lower-severity, informational messages detected while previewing the import (non-blocking).

Warnings do not prevent the SAVE call by themselves, but they describe conditions that may make the import fail or produce an incomplete booking, so review them before confirming.

Buyer information

Buyer is required on SAVE, with FirstName, LastName and Email always supplied. If the object is missing or a required field is empty, the request is rejected with 2504.

The remaining buyer fields (Telephone, StreetAddress, City, ZipCode, State, Country, Document) are optional and are stored with the booking when provided.

Buyer is not needed on DISPLAY — a preview does not persist anything — and is ignored if sent.

Payment information

Payments are not accepted at import time. The booking is imported with a CASH form of payment. Register the actual payments afterwards with the UpdateBookingPayments operation.

Response

The response does not return a TravelCaster booking number — the record locator used in the request acts as the identifier. To retrieve the imported booking later, use the RetrieveBooking operation with the record locator as the BookingNumber.

  • TransactionCode: null — the operation succeeded. For DISPLAY, read the preview (BookingFare/Passengers/etc.) plus Warnings/Informations/AllowedCardPayments; for SAVE, the imported booking is returned in full.
  • TransactionCode: not null — the operation failed. See TransactionCode and TransactionMessage for details.

Timeout

The operation calls an internal management service with a 180-second timeout. Set your client timeout to at least 185 seconds for this operation.

Transaction codes

Code Description
1000 Unspecified error — see TransactionMessage
1210 Session expired — obtain a new token via GetAccessToken
2400 Permission denied (the booking already exists in TravelCaster and does not belong to your API user)
2500 Missing mandatory parameters — see TransactionMessage for the list of failing fields
2501 Invalid Operation (expecting DISPLAY/SAVE)
2503 A DISPLAY must be performed before SAVE for this booking
2504 Buyer information is missing or incomplete (SAVE only)

Back to Flights home.

See change history for this file
Loading...