Reading bookings

A booking is a trip. It holds one or more hotel services, the passengers, the money and an audit trail. Read it with getBookings when a webhook arrives, when you reconcile, or whenever your back office needs the current state.

Fetch the whole tripCopy Anchor Link

Returns BookedTripVO, the whole trip for every service type. The only query parameter is lang. Spec Any valid token works, so a back-office process can keep its own cached token instead of using a booking-flow token. See the Get booking reference.

curl -s --compressed \
  "$NAVA_BASE_URL/booking/getBookings/$NAVA_MICROSITE_ID/TST-1464?lang=EN" \
  -H "auth-token: $TOKEN" \
  -H "Accept-Encoding: gzip" \
  | jq '{bookingReference, status, hotels: [.hotelservice[] | {bookingReference, status, hotelName}]}'

{
  "auditData": { "authToken": "[REDACTED]", "traceId": "D4AE54C6-…" },
  "bookingReference": "TST-1464",
  "status": "BOOKED",
  "tripType": "ONLY_HOTEL",
  "distribution": [
    {
      "id": "TST-1464-0",
      "person": [
        { "id": "TST-1464-0-0", "name": "Ana", "lastName": "Ruiz", "requestedAge": 34 },
        { "id": "TST-1464-0-1", "name": "Luis", "lastName": "Ruiz", "requestedAge": 36 }
      ]
    }
  ],
  "agencyBookingReference": "ORDER-8812",
  "hotelservice": [
    {
      "id": "TST-1464-0",
      "bookingReference": "FAKE-1775464987",
      "status": "BOOKED",
      "hotelId": "MASTER-1782232",
      "hotelName": "Cristine Bedfor Mahón",
      "category": "S4",
      "pricebreakdown": {
        "totalPrice": {
          "microsite": { "amount": 134.05, "currency": "EUR" },
          "operator": { "amount": 134.05, "currency": "EUR" }
        }
      }
    }
  ],
  "manualServices": { "hotel": [] }
}

How to read the response codes:

• A 404 means the reference doesn't exist in that microsite. It is not an outage. 5xx, 429 and timeouts are retryable. A 401 or 403 gets one re-authentication, then an alert. Verified
• Look a booking up with its own microsite first. We have seen a mismatched micrositeId in the path ignored and the booking resolved through another microsite of the same operator. The platform has signalled that it will close this, so on a 404 fall back to your other microsites explicitly, and map all of them to one canonical key downstream. Verified

Where things liveCopy Anchor Link

The trip also carries customBookingReference, creationDate, lastUpdateDate, startDate, endDate, nightsCount, adultCount, childCount, infantCount, user, payment, bookedNotes[], notes, invoices[], salesChannel, language, sourceMarket, voucherUrl and pdfs[]. Spec

Hotel servicesCopy Anchor Link

Each hotelservice[] entry is a BookedHotelServiceVO. The fields come from the spec; the notes come from production use. Spec

Service names and remarks can embed raw HTML; we have seen it in production. Strip it and cap lengths before you store text in fixed-length fields. Verified

Cancellation datesCopy Anchor Link

Booked hotels have no service-level currentCancellationType. Read the policy steps in cancelPolicy[] instead. Verified

PassengersCopy Anchor Link

• Passengers live in the booking-level distribution[], one entry per room, each { id, person[] }.
• Person ids follow <bookingReference>-<roomIndex>-<personIndex>, for example TST-1464-0-1. Every real passenger we have seen in production carried an id, so use person.id as the passenger identity. Verified
• name is the first name and lastName the surname. Join them for display. Some payloads use firstName or fullName instead, so accept those too. Verified
• The trip's lead contact is also in contactPerson (a PersonVO).

Manually added hotelsCopy Anchor Link

A hotel that an agent entered by hand, without booking it through a supplier, is not in hotelservice[]. It is in manualServices.hotel[]. manualServices has other keys too, such as other[] and accountingAdjustment[], and they can carry money. Verified

Other trip fieldsCopy Anchor Link

• historical[] holds { dateTime, message } entries: the platform's human-readable audit trail. It is the best source for "what changed" notes. It grows over time, so leave it out of change detection.
• originalBookingAgency is a plain string (an agency name), both in the spec and on real bookings. It is not an agency object, so don't model it as one. Spec Verified
• Your order id, sent as externalReference at Book, comes back here as agencyBookingReference. There is no externalReference field in getBookings. Tested Booking detail returns it as externalReference; call it with hotelservice[].id as the accommodationBookingReference (the supplier's hotelservice[].bookingReference is accepted too). Tested
• customBookingReference is the number of the trip reference, zero-padded: 00001464 for TST-1464. Tested

Cancel-and-rebook leaves two servicesCopy Anchor Link

When an agent cancels a room and rebooks it, hotelservice[] holds two services at the same hotel and dates, with different bookingReferences. Verified

Both are real, and the trip total stays correct. This is not a duplicate: never dedupe services by hotel and dates.

The money modelCopy Anchor Link

pricebreakdown on the trip (PriceBreakdownVO) and on each service (ServicePriceBreakdownVO) express every amount as a MoneyAmountVO: the same amount in the microsite's currency (microsite) and in the operator's currency (operator). Spec

{
  "microsite": { "amount": 134.05, "currency": "EUR" },
  "operator": { "amount": 134.05, "currency": "EUR" }
}

totalPrice is not totalOperatorRevenue. The difference is agency commission and fees.

What production teachesCopy Anchor Link

Supplier currencies leak into the cost legs. We have seen customer totals in one currency while providerNetPrice.currency and netProvider.microsite carried the supplier's own currency (EUR, SAR, QAR and others). A sync that validates the currency of the total only will still fail on a cost line. Either support every currency or read the .operator legs. Verified

{
  "totalPrice": {
    "microsite": { "amount": 536.2, "currency": "EUR" },
    "operator": { "amount": 536.2, "currency": "EUR" }
  },
  "netProvider": {
    "microsite": { "amount": 1650.0, "currency": "QAR" },
    "operator": { "amount": 412.5, "currency": "EUR" }
  },
  "providerNetPrice": { "amount": 1650.0, "currency": "QAR" }
}

Use the .operator legs for single-currency accounting. We recommend totalOperatorRevenue.operator for the sale and netProvider.operator for the cost, because the platform has already converted them. The customer totalPrice is then informational. Whichever legs you pick, pick them deliberately and write the choice down. Verified

The trip total can exceed the sum of the hotel services. Booking-level fees (agency, microsite, payment and operator fees, taxes) and non-hotel or manual services mean pricebreakdown.totalPrice is often higher than the sum of hotelservice[].pricebreakdown.totalPrice. We have seen this on a meaningful share of bookings. Reconcile the difference explicitly instead of expecting equality. Verified

Amounts change after booking, down to 0. originalpricebreakdown keeps the amounts at booking time; pricebreakdown follows repricing. We have seen an RQ service cancelled and repriced to 0 within an hour, and PRICE_ERROR both as a passing state and as a stored one. Your downstream system must accept a service going to 0. Verified

Design a downstream syncCopy Anchor Link

The pattern for an ERP, accounting or CRM sync: webhook, queue, getBookings, normalise hotelservice[], idempotent upsert. Add an hourly reference-sequence sweep for lost webhooks and microsites without one.

IdentitiesCopy Anchor Link

Keep the fallback formula stable across code versions. Changing it re-keys existing records and creates duplicates. Verified

RulesCopy Anchor Link

• Detect changes with a hash of the normalised booking. Leave out volatile fields such as historical[] and auditData, so audit-trail growth alone doesn't count as a change.
• Upsert idempotently by the keys above. A crash between two writes must be safe to replay.
• Keep CANCELED lines. Map them to zero or neutralised lines instead of deleting them, so accounting keeps the history.
• Let statuses settle. A non-final status is often followed by a later change. Don't zero a value on first sight; alert when a non-final status lingers for days while it still carries value. Verified
• Redact auditData.authToken before you store raw payloads. It echoes a live token.
• Strip HTML and cap lengths in names and remarks before you store them.

import { createHash } from 'node:crypto';

// Sorted keys, so the same data always gives the same hash.
function stableStringify(value: unknown): string {
  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
  if (value && typeof value === 'object') {
    const obj = value as Record<string, unknown>;
    return `{${Object.keys(obj).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(',')}}`;
  }
  return JSON.stringify(value);
}

// Audit-trail growth alone is not a change.
export function changeHash(trip: any): string {
  const { historical, auditData, ...rest } = trip;
  return createHash('sha256').update(stableStringify(rest)).digest('hex');
}

// Never change this formula once records exist: it would re-key them.
export function serviceKey(s: any, index: number): string {
  if (s.bookingReference) return s.bookingReference;
  const basis = ['hotelservice', index, s.hotelName, s.startDate, s.endDate, s.supplierId].join('|');
  return 'fallback-' + createHash('sha256').update(basis).digest('hex').slice(0, 32);
}

export async function upsertTrip(canonicalMicrositeId: string, trip: any) {
  const bookingKey = `${canonicalMicrositeId}:${trip.bookingReference}`;
  const hash = changeHash(trip);
  if ((await db.lastHash(bookingKey)) === hash) return; // nothing but the audit trail moved

  await db.upsertBooking(bookingKey, { status: trip.status, raw: trip }); // authToken already redacted
  for (const [i, s] of (trip.hotelservice ?? []).entries()) {
    await db.upsertServiceLine(bookingKey, serviceKey(s, i), {
      status: s.status, // CANCELED lines stay: zero or neutralise them, never delete
      sale: s.pricebreakdown?.totalOperatorRevenue?.operator,
      cost: s.pricebreakdown?.netProvider?.operator,
    });
  }
  for (const room of trip.distribution ?? []) {
    for (const p of room.person ?? room.persons ?? []) {
      await db.upsertPassenger(bookingKey, p.id, { firstName: p.name ?? p.firstName, lastName: p.lastName });
    }
  }
  await db.saveHash(bookingKey, hash); // last, so a crash before this line replays the whole sync
}

db stands for your own storage layer. The sketch reads hotel services and passengers only: add manualServices and the other service arrays if your accounting needs them.

RelatedCopy Anchor Link

• Webhooks: when to fetch, and the sweep for lost webhooks.
• Get booking: the getBookings reference.
• Booking detail: the per-hotel view that returns externalReference.
• Booking statuses: what each service status means.
• Cancellations: policies, fees and refunds.