Search, book and ticket
travel from one balance.

# Staging
https://<your-easygds-host>

# Local development
http://localhost:8020

# Every request carries your key + tenant
Authorization: Bearer <your_api_key>
X-Tenant-Id:   <your_app_id>
X-Currency:    USD

# Verify your key — list balances
curl https://<your-easygds-host>/balances \
  -H "Authorization: Bearer pk_live_8f2c…" \
  -H "X-Tenant-Id: bbf70af6-4382-…" \
  -H "X-Currency: USD"

import httpx

client = httpx.Client(
  base_url="https://<your-easygds-host>",
  headers={
    "Authorization": "Bearer pk_live_8f2c…",
    "X-Tenant-Id": "bbf70af6-4382-…",
    "X-Currency": "USD",
  },
)
r = client.get("/balances")
print(r.json()["data"])

const base = "https://<your-easygds-host>";
const headers = {
  "Authorization": "Bearer pk_live_8f2c…",
  "X-Tenant-Id": "bbf70af6-4382-…",
  "X-Currency": "USD",
};
const res = await fetch(`${base}/balances`, { headers });
const { data } = await res.json();

POST /flights/offer/offer_requests

{
  "data": {
    "slices": [{ "origin":"ADD", "destination":"DXB",
                "departure_date":"2026-08-15" }],
    "passengers": [{ "type":"adult" }],
    "cabin_class": "economy"
  }
}

{
  "data": { "offer_request": {
    "id": "9840832ab564…",
    "offers": [{
      "id": "ET445$2026-08-15…",
      "total_amount": "312.00",
      "total_currency": "USD",
      "slices": [{ "segments": [{
        "marketing_carrier": {"iata_code":"ET"},
        "marketing_carrier_flight_number": "445",
        "departing_at": "2026-08-15T08:15:00",
        "duration": "PT4H00M" }] }],
      "passengers": [{"id":"adult-0","type":"adult"}]
    }]
  }}
}

# 02 price-lock the offer → shoppingId
POST /shopping/{offerId}
{ "vertical":"flight", "searchId":"9840832ab564…" }
→ { "data": { "shoppingId": "4fe96…" } }

# 03 prebook (re-confirm the locked total)
POST /shopping/prebook        # X-Shopping-Id: 4fe96…
→ { "total_amount": "312.00", "total_currency": "USD" }

# 04 book — debits balance, issues ticket
POST /shopping/book           # X-Shopping-Id: 4fe96…
{
  "vertical": "flight",
  "contact": { "first_name":"Sara", "last_name":"Tesfaye",
                "email":"sara@acme.travel", "phone":"+251911223344" },
  "travelers": [{ "type":"adult", "title":"Ms",
                  "first_name":"Sara", "last_name":"Tesfaye" }]
}
→ { "booking_reference":"ET7F2A9", "status":"confirmed",
    "etickets":[{ "ticket_no":"0712…" }] }

HTTP/1.1 200 OK

{
  "data": { /* your result */ }
}

HTTP/1.1 402 Payment Required

{
  "errorId": "BFF-PAY-INSUFFICIENT",
  "originSystem": "BFF",
  "correlationId": "550e8400-e29b-…",
  "httpStatus": 402,
  "message": "Balance does not cover the booking",
  "context": { "available":120.0, "payable":512.4 }
}

# Inspect the envelope
{
  "errorId":    "BFF-VAL-0010",
  "originSystem": "BFF",
  "httpStatus":  400,
  "message":     "Flight book requires `contact`"
}

r = client.post("/shopping/book", json=body,
                  headers={"X-Shopping-Id": sid})
if r.is_error:
    err = r.json()
    if err["errorId"] == "BFF-PAY-INSUFFICIENT":
        top_up(err["context"]["payable"])
    else:
        log.error(err["correlationId"], err["message"])

const r = await fetch(`${base}/shopping/book`, opts);
if (!r.ok) {
  const err = await r.json();
  if (err.errorId === "BFF-PAY-INSUFFICIENT")
    await topUp(err.context.payable);
  else log.error(err.correlationId, err.message);
}

GET /shopping/payment/options

{ "data": [{
  "method_id": "offline",
  "label": "Offline / deposit (balance)",
  "type": "offline"
}]}

HTTP/1.1 402

{
  "errorId": "BFF-PAY-INSUFFICIENT",
  "context": {
    "available": 120.00,
    "payable":   512.40,
    "currency":  "USD"
  }
}

POST /flights/offer/offer_requests
{
  "data": {
    "slices": [
      {"origin":"ADD","destination":"NBO","departure_date":"2026-08-01"},
      {"origin":"NBO","destination":"JNB","departure_date":"2026-08-03"},
      {"origin":"JNB","destination":"ADD","departure_date":"2026-08-07"}
    ],
    "passengers": [{"type":"adult"}],
    "cabin_class": "business"
  }
}

# price the offer → shoppingId + fare_families[]
POST /flights/offer/offers/{offerId}/actions/price?searchId=…

# pick a branded fare (cart-scoped)
POST /shopping/flights/select-fare      # X-Shopping-Id: …
{ "upsell_id": "<from fare_families[].upsell_id>" }

# fetch + commit seats/baggage
POST /shopping/flights/ancillaries       # → { ancillaries, seats }
POST /shopping/flights/select-ancillaries
{ "segments": [{ "seats":[…], "ancillaries":[…] }] }

# 1 — search availability (destination is a place_id)
POST /hotels/search
{
  "location_id": "3168",
  "location_type": "place_id",
  "check_in_date": "2026-10-14",
  "check_out_date": "2026-10-16",
  "guests": [{"age":null}],
  "rooms": 1,
  "nationality": "et"
}
→ { "data": { "search_id":"…",
    "results":[ { "id":"2139774", … } ] } }

# 2 — rooms & rates for a hotel (pass its `id`)
GET /hotels/search/{searchId}/rooms?hotel_id=2139774

POST /bff/v2/activities/offer_request
{
  "location_id": "3168",
  "location_type": "place_id",
  "date_from": "2026-08-19",
  "date_to": "2026-08-20",
  "pax": 1
}
→ { "data": { "offer_request": {
      "id":"…", "offers":[ … ] } } }

POST /transports/search
{
  "airport_code": "LHR",
  "from_airport": true,
  "place_code": "2612",
  "place_type": "property_id",
  "pickup_date": "2026-08-19",
  "pickup_time": "14:00",
  "passengers": 1
}

# Stopover (airport_code destination)
POST /bff/v2/stopover/offer_request
{ "location_id":"AUH", "location_type":"airport_code",
  "checkin_date":"2026-09-16", "checkout_date":"2026-09-17",
  "guests":[{"age":null},{"age":null}], "rooms":1 }

# Train (railway_station codes, round trip)
POST /bff/v2/trains/offer_request
{ "departure_code":"JED", "arrival_code":"MKX",
  "from_date":"2026-09-16", "return_date":"2026-09-18",
  "round_trip":true, "passengers":1 }

# Bus (same shape as trains — separately-activatable product)
POST /bff/v2/buses/offer_request
{ "departure_code":"JED", "arrival_code":"MKX",
  "from_date":"2026-09-16", "return_date":"2026-09-18",
  "round_trip":true, "passengers":1 }

# Tour package
POST /bff/v2/tour_packages/offer_request
{ "location_id":"3168", "location_type":"place_id",
  "date_from":"2026-08-19", "pax":1 }

# Car rental
POST /bff/v2/car_rental/offer_request
{ "pickup":{"location_id":"LHR","type":"airport_code"},
  "pickup_datetime":"2026-09-10T10:00",
  "dropoff_datetime":"2026-09-12T10:00", "driver_age":35 }

# after search, you have offerId + searchId
POST /shopping/{offerId}
     { "vertical":"hotel", "searchId":"…" }   → shoppingId

# carry X-Shopping-Id from here on
POST /shopping/travelers   { "travelers":[ … ] }
POST /shopping/contact     { "contact":{ … } }
POST /shopping/prebook
POST /shopping/book        { "vertical":"hotel", "accept_tnc":true }

GET  /shopping/bookings?transaction_id=…

✓ Store keys server-side only
✓ Send X-Tenant-Id on every call
✓ Handle 402 BFF-PAY-INSUFFICIENT
✓ Carry X-Shopping-Id through checkout
✓ Read /shopping/bookings to confirm
✓ Log correlationId on every error