Chapter 7.1 — GDS Integrations (Amadeus, Sabre, Travelport)

1. Purpose

This chapter defines how travoBooks integrates with the three major Global Distribution Systems — Amadeus, Sabre, and Travelport (Galileo / Worldspan / Apollo) — for air offer search, booking creation, pricing, ticket issuance, refund/void, exchange, and post-issuance servicing. It covers the request/response patterns, credential management, error handling, latency budgets, and the abstraction layer that lets module-level code work against any GDS.

2. Why it matters

The GDS is the largest single source of air bookings industry-wide. A robust integration is the difference between a platform that issues tickets reliably and one that fails customers at the worst moment (the issuance call). This integration must handle: - Versioned schemas (XML for traditional GDS, JSON for NDC paths). - Latency variation (200ms to 30s per call). - Transient supplier outages (queue + retry without double-booking). - Strict idempotency (issuance is irreversible — never re-issue).

3. Architecture

The platform implements a supplier-abstraction layer (SupplierClient interface) with per-GDS adapters:

SupplierClient (interface)
├── AmadeusClient
│   └── handles Amadeus Soap / WSAP envelopes
├── SabreClient
│   └── handles Sabre SOAP and REST endpoints
└── TravelportClient
    └── handles uAPI XML

Module code calls SupplierClient.searchOffers(...) without knowing the underlying GDS. Per-supplier credentials and configuration are stored encrypted in supplier_credentials.

4. Amadeus integration

4.1 Authentication

• SOAP envelope with WS-Security header containing OfficeId, Originator, Password, BinarySecurityToken.
• Token obtained via Security_Authenticate and held in memory for the session.
• Re-auth on SOAP-Fault: AUT.SECURITY_TOKEN_EXPIRED.

4.2 Key endpoints used

4.3 Parsing

The platform uses a dedicated IttAMASearch class (PHP) for parsing Fare_MasterPricerTravelBoardSearch responses. The parser: - Groups recommendations by flightIndex and resolves fare-family per recommendation. - Extracts per-segment fare class, baggage allowance, fare basis code, and ATPCO category data. - Handles ensureArray normalisation (Amadeus returns single-element arrays without wrapper). - Constructs segmentUID for downstream segment-level operations.

4.4 Office hierarchy

Amadeus uses OfficeId for multi-branch agents. The platform maps partner.amadeus_office_id per branch; selected at request time.

5. Sabre integration

5.1 Authentication

• REST-based OAuth2 token from /v3/auth/token; SOAP token also supported.
• PCC (Pseudo-City Code) sent in every request header.

5.2 Key endpoints

5.3 PCC mapping

Sabre's PCC ≈ Amadeus's OfficeId concept. Per-partner per-branch PCC configured.

6. Travelport integration

uAPI-based; XML wire format; similar surface area. Per-PCC equivalent.

7. Cross-GDS canonical model

The platform stores GDS-agnostic data in canonical tables:

Supplier-specific raw payloads are stored in supplier_request_log for replay and debugging — never used as application data.

8. Issuance pattern (critical)

Ticket issuance is the most sensitive call in the platform. Strict pattern:

The key invariant: the GDS call is outside the DB transaction. If the DB commit fails after a successful GDS issuance, the platform has a real ticket without an internal record — a reconciliation hazard. Mitigation: - Pre-commit "ready to commit" record in supplier_request_log with the ticket number. - Background reconciler matches supplier_request_log ticket numbers to booking_tickets. - Orphan tickets (in log, not in tickets) raise immediate alerts.

This pattern is documented in Chapter 4.2 Ticketing & PNR.

9. Schedule changes & post-issuance servicing

GDS pushes schedule-change notifications via: - Amadeus: Queue_PlaceMessage to monitored queues; polled. - Sabre: Notifications API; webhook or queue. - Travelport: TMU subscription.

Platform: - Polls / receives the change. - Updates booking_segments.status, segments[i].new_time. - Creates a booking_alert for ops. - If automatic re-protect rule matches, attempts re-accommodation.

10. Latency budget

11. Error handling

Common GDS errors and treatments:

Distinguish retryable (transient network/timeout, session expired) from non-retryable (business reject) errors. Only retryable errors are retried, and at most twice with exponential backoff.

12. Idempotency

All issuance-class operations carry an idempotency key derived from (partner_id, booking_id, operation_type). Replay of an identical issuance request returns the previously-cached ticket number without calling the GDS again.

13. Credentials

Per-supplier credentials stored encrypted at rest (KMS envelope encryption) in supplier_credentials. Accessible only by the integration service account; never exposed to UI; never logged in plaintext.

Rotation: - Production credentials rotated every 90 days (Amadeus / Sabre / Travelport policies). - Rotation orchestrated by a runbook; no API outage.

14. Observability

Every GDS call produces: - Request log row (request, response, latency, status). - Metric: per-operation success rate, p50/p95/p99 latency. - Alert: success rate < 95% on 5-minute window. - Alert: p95 latency > target on 5-minute window.

15. Database tables touched

16. Common pitfalls

• ⚠️ GDS call inside DB transaction. Database lock held during a 30s network call → cascading lock contention.
• ⚠️ Retrying non-retryable errors. "Price changed" retried is bad UX; require explicit user re-confirm.
• ⚠️ Trusting GDS-supplied fare without re-pricing. Always re-price before issuance.
• ⚠️ Not capturing fare rules at booking time. Fare rules change; archive the version at booking.
• ⚠️ Sharing credentials across partners. Per-partner credentials only.
• 🔒 Logging request payload with credentials. Strip auth headers from logs.
• ⚠️ Ignoring schedule-change queue. Customers turn up at the airport on the wrong flight.