Frontend API Guide: Import Preview + Bundle Pricing Flow

Change summary for frontend migration: docs/frontend-api-change-impact.md

This document lists the APIs required by frontend for:

• pre-import checks (locations, hotels, transfers)
• full itinerary import in one call
• bundle pricing/category behavior

Base Notes

• All names are tenant-scoped.
• Transfer name uniqueness is tenant-wise and case-insensitive.
• Hotel inventory checks are based on category + location.

---

1) Location APIs

1.1 Check Cities by Name (bulk exact check)

• Method: POST
• Endpoint: /v1/location/check-cities-by-name
• Purpose: Check if provided city names exist uniquely. Returns only names with exactly one match.

Request

{
  "cityNames": ["Gangtok", "Darjeeling", "Pelling"]
}

Response

{
  "message": "SUC_CITY_NAME_CHECKED",
  "data": {
    "Gangtok": { "id": 101, "name": "Gangtok", "stateName": "Sikkim" },
    "Darjeeling": {
      "id": 102,
      "name": "Darjeeling",
      "stateName": "West Bengal"
    }
  }
}

1.2 Search Cities by Name (ILIKE)

• Method: GET
• Endpoint: /v1/location/cities/search?name=<text>
• Purpose: Search city suggestions by name.

Response

{
  "message": "SUC_CITIES_FETCHED",
  "data": [
    { "id": 101, "name": "Gangtok", "state": { "id": 11, "name": "Sikkim" } }
  ]
}

1.3 Search States by Name (ILIKE)

• Method: GET
• Endpoint: /v1/location/states/search?name=<text>
• Purpose: State search returning only state id/name.

Response

{
  "message": "SUC_STATES_FETCHED",
  "data": [{ "id": 11, "name": "Sikkim" }]
}

1.4 Create City / Location

• Method: POST
• Endpoint: /v1/location/city
• Purpose: Create city under a state (country auto-derived from state).

Request

{
  "name": "Lachung",
  "stateId": 11,
  "latitude": 27.6892,
  "longitude": 88.742
}

Response

{
  "message": "SUC_CITY_CREATED",
  "data": {
    "id": 501,
    "name": "Lachung",
    "stateId": 11,
    "countryId": 1,
    "latitude": 27.6892,
    "longitude": 88.742
  }
}

---

2) Hotel Inventory APIs

2.1 Check Hotel Inventory (bulk)

• Method: POST
• Endpoint: /v1/hotel/check-inventory
• Purpose: For each input object:
  1. return all matched hotels from priorityHotelNames within category + location
  2. if no priority match, fallback to first hotel by category + location

Request

{
  "items": [
    {
      "category": "standard",
      "locationId": 101,
      "priorityHotelNames": ["Maple Residency", "Delight The Fortuna"]
    },
    {
      "category": "premium",
      "locationId": 101
    }
  ]
}

Response

{
  "message": "SUC_HOTEL_INVENTORY_CHECKED",
  "data": [
    {
      "inputIndex": 0,
      "matched": true,
      "matchType": "priority_name",
      "hotel": {
        "id": 9001,
        "name": "Maple Residency",
        "cityId": 101,
        "category": "standard",
        "address": "MG Road",
        "description": "Sample standard hotel",
        "starRating": 4,
        "checkInTime": "14:00:00",
        "checkOutTime": "11:00:00",
        "roomType": "Suite"
      },
      "hotels": [
        {
          "id": 9001,
          "name": "Maple Residency",
          "cityId": 101,
          "category": "standard",
          "address": "MG Road",
          "description": "Sample standard hotel",
          "starRating": 4,
          "checkInTime": "14:00:00",
          "checkOutTime": "11:00:00",
          "roomType": "Suite"
        },
        {
          "id": 9003,
          "name": "Delight The Fortuna",
          "cityId": 101,
          "category": "standard",
          "address": "Central Avenue",
          "description": "Sample standard hotel",
          "starRating": 4,
          "checkInTime": "13:00:00",
          "checkOutTime": "10:00:00",
          "roomType": "Deluxe"
        }
      ]
    },
    {
      "inputIndex": 1,
      "matched": true,
      "matchType": "fallback_category_location",
      "hotel": {
        "id": 9007,
        "name": "Lemon Tree",
        "cityId": 101,
        "category": "premium",
        "address": "Hill View",
        "description": "Sample premium hotel",
        "starRating": 5,
        "checkInTime": "14:00:00",
        "checkOutTime": "11:00:00",
        "roomType": "Suite"
      },
      "hotels": [
        {
          "id": 9007,
          "name": "Lemon Tree",
          "cityId": 101,
          "category": "premium",
          "address": "Hill View",
          "description": "Sample premium hotel",
          "starRating": 5,
          "checkInTime": "14:00:00",
          "checkOutTime": "11:00:00",
          "roomType": "Suite"
        }
      ]
    }
  ]
}

2.2 Search Hotel Inventory

• Method: GET
• Endpoint: /v1/hotel/search-inventory?name=<text>&category=<category>&locationId=<id>
• Purpose: Name search constrained by category + location.

Response

{
  "message": "SUC_HOTELS_FETCHED",
  "data": [
    {
      "id": 9001,
      "name": "Maple Residency",
      "cityId": 101,
      "category": "standard",
      "address": "MG Road",
      "description": "Sample standard hotel",
      "starRating": 4,
      "checkInTime": "14:00:00",
      "checkOutTime": "11:00:00",
      "roomType": "Suite"
    }
  ]
}

2.3 Create Hotel Inventory

• Method: POST
• Endpoint: /v1/hotel/inventory
• Purpose: Create hotel in inventory with minimal required fields and optional extended hotel metadata.
• Content-Type: multipart/form-data

Request

{
  "name": "Delight The Fortuna",
  "cityId": 101,
  "category": "standard",
  "address": "MG Road, Gangtok",
  "description": "Comfort stay near city center",
  "starRating": 4.5,
  "checkInTime": "14:00:00",
  "checkOutTime": "11:00:00",
  "roomType": 4,
  "mediaLinks": [
    "https://cdn.example.com/hotels/delight-1.jpg",
    "https://cdn.example.com/hotels/delight-2.jpg"
  ]
}

Required fields:

• name
• cityId
• category

Optional fields:

• address
• description
• starRating
• checkInTime
• checkOutTime
• roomType
• mediaLinks (array of image/video URLs to map as hotel media)
• mediaFile[] (bulk photo upload files; backend uploads to storage and stores generated file names in hotel.hotel_media.file_name)

Response

{
  "message": "SUC_HOTEL_CREATED",
  "data": {
    "id": 9010,
    "name": "Delight The Fortuna",
    "cityId": 101,
    "category": "standard",
    "address": "MG Road, Gangtok",
    "description": null,
    "starRating": null,
    "checkInTime": null,
    "checkOutTime": null,
    "roomType": null,
    "media": [
      {
        "id": 30001,
        "fileType": 1,
        "link": "https://cdn.example.com/hotels/delight-1.jpg"
      }
    ]
  }
}

---

3) Transfer Inventory APIs

3.1 Check Transfer by Name

• Method: POST
• Endpoint: /v1/transfer/check-by-name
• Purpose: Exact transfer-name check in tenant inventory (bulk).

Request

{
  "items": [{ "name": "Wagon R / Similar" }, { "name": "Innova / Similar" }]
}

Response

{
  "message": "SUC_TRANSFER_CHECKED",
  "data": [
    {
      "requestedName": "Wagon R / Similar",
      "matched": true,
      "transfer": {
        "id": 3001,
        "vehicleName": "Wagon R / Similar",
        "vehicleType": "Car",
        "seater": 3,
        "description": "Airport and local transfers",
        "notes": "Night surcharge excluded",
        "isActive": true,
        "createdAt": "2026-03-20T10:10:10.000Z",
        "updatedAt": "2026-03-20T10:10:10.000Z"
      }
    },
    {
      "requestedName": "Innova / Similar",
      "matched": false,
      "transfer": null
    }
  ]
}

3.2 Search Transfer by Name

• Method: GET
• Endpoint: /v1/transfer/search?name=<text>
• Purpose: Transfer suggestions by name.

Response

{
  "message": "SUC_TRANSFERS_FETCHED",
  "data": [
    {
      "id": 3002,
      "vehicleName": "Innova / Xylo / Similar",
      "vehicleType": "Car",
      "seater": 6,
      "description": "Airport and local transfers",
      "notes": "Night surcharge excluded",
      "isActive": true,
      "createdAt": "2026-03-20T10:10:10.000Z",
      "updatedAt": "2026-03-20T10:10:10.000Z"
    }
  ]
}

3.3 Create Transfer Inventory

• Method: POST
• Endpoint: /v1/transfer/inventory
• Purpose: Create a transfer in inventory with required fields, optional metadata, and bulk media upload.
• Content-Type: multipart/form-data

Request

{
  "vehicleType": "Car",
  "vehicleName": "Innova / Xylo / Similar",
  "seater": 6,
  "description": "Airport and local transfers",
  "notes": "Night surcharge excluded"
}

Required fields:

• vehicleType
• vehicleName

Optional fields:

• seater
• description
• notes
• mediaFile[] (bulk photo upload files; backend uploads to storage and stores generated file names in transfer.transfer_media.file_name)

Response

{
  "message": "SUC_TRANSFER_CREATED",
  "data": {
    "id": 3010,
    "vehicleName": "Innova / Xylo / Similar",
    "vehicleType": "Car",
    "seater": 6,
    "description": "Airport and local transfers",
    "notes": null,
    "isActive": true,
    "media": [
      {
        "id": 40001,
        "fileType": 1,
        "link": "https://cdn.example.com/transfers/innova-1.jpg"
      }
    ],
    "createdAt": "2026-03-20T10:10:10.000Z",
    "updatedAt": "2026-03-20T10:10:10.000Z"
  }
}

3.4 Activity create API (full + media upload)

• Method: POST
• Endpoint: /v1/activity
• Purpose: Create activity with required base fields and optional metadata/details/tags/media.
• Content-Type: multipart/form-data

Notes:

• Activity endpoint already supports bulk mediaFile[] upload.
• Uploaded files are stored in activity media and file names are saved to activity.activity_media.file_name.

---

4) Full Import API

4.1 Import Full Itinerary in One Call

• Method: POST
• Endpoint: /v1/itinerary/import-itinerary-full
• Purpose: Create itinerary + map existing hotel/transfer inventory IDs + upsert bundle pricing.

Request (shape)

{
  "itinerary": { "...": "CreateItineraryDto" },
  "transferIds": [3010, 3011],
  "hotelIds": [901, 905],
  "hotelDayMappings": [
    { "hotelId": 901, "dayOrder": 1 },
    { "hotelId": 905, "dayOrder": 2 }
  ],
  "activities": [
    {
      "dayOrder": 1,
      "title": "Gangtok local sightseeing",
      "startTime": "2026-03-20 10:00:00",
      "duration": 120,
      "description": "MG Road and nearby viewpoints"
    },
    {
      "dayOrder": 2,
      "title": "Tsomgo Lake excursion",
      "startTime": "2026-03-21 09:30:00"
    }
  ],
  "bundlePricing": [
    {
      "category": "standard",
      "plan": "CP",
      "extraBedPrice": 4050,
      "childWithoutBedPrice": 2100,
      "dinnerSupplementPrice": 1950,
      "vehiclePricing": [
        {
          "transferId": 3001,
          "capacityMin": 1,
          "capacityMax": 3,
          "pricePerPerson": 15100
        },
        {
          "transferId": 3002,
          "capacityMin": 1,
          "capacityMax": 3,
          "pricePerPerson": 18400
        },
        {
          "transferId": 3002,
          "capacityMin": 4,
          "capacityMax": 6,
          "pricePerPerson": 12350
        }
      ]
    }
  ]
}

Notes:

• hotelIds and transferIds must be existing inventory IDs.
• activities are created first, then mapped day-wise using dayOrder.
• activities[].startTime is mandatory.
• activities[].duration is optional (minutes).
• hotelIds are mapped itinerary-wise by category + location.
• hotelDayMappings controls explicit day-wise hotel mapping.
• hotel-to-day mapping validates that day city/location matches hotel city.
• if hotelDayMappings is omitted, backend falls back to location-based day mapping (maps hotel to all matching city/location days) for backward compatibility.
• transferIds are mapped itinerary-wise only.
• Use transfer APIs (check-by-name / search / inventory) to fetch full transfer objects and pick IDs for import payload.
• vehiclePricing[].transferId is required for bundle pricing rows.
• vehiclePricing is preferred over capacityPricing.
• capacityPricing is kept as a backward-compatible fallback shape.
• This supports same capacity bucket with different per-person prices by vehicle model.

Response

{
  "message": "SUC_ITN_IMPORTED",
  "data": {
    "id": 948,
    "name": "THE LAST SHANGRI-LA"
  }
}

---

5) Existing APIs Still Reusable

• GET /v1/location/cities?search=<text>
• GET /v1/location/states?search=<text>
• POST /v1/hotel (full create)
• POST /v1/transfer (full create)

For import-preview UX, prefer the new lightweight check/search endpoints documented above.

---

6) Category Alignment + Publish Rules

• tripType, hotel category, and bundle pricing category all use HotelCategoryEnum values: 1=LUXURY, 2=PREMIUM, 3=SUPER_DELUXE, 4=DELUXE, 5=STANDARD.
• For legacy records, old BASIC trip-type behavior is treated as STANDARD in compatibility handling.
• Category swapping affects hotel bundle selection only; transfer pricing is category-agnostic (same slabs regardless of selected category).
• For hotel_transfer and hotel_only, availableCategories in the price-details response always returns all five values [1,2,3,4,5]. Use categoryPerPersonPrices to find which categories have pricing rows.

6.1 B2C default display order

• hotel_transfer: selected/default category hotel bundle + primary transfer vehicle slab.
• hotel_only: selected/default category hotel bundle.
• transfer_only: primary transfer pricing slabs.
• activities_only: adultPrice by default.

6.2 Publish pre-validation matrix

Validation runs only when publishing (not unpublishing). Checked in validatePublishReadiness() (src/modules/itinerary/utils/publish-validation.util.ts).

• hotel_transfer (has both hotels and transfers):
  • tripType / effective category must be set (ERR_ITN_PUBLISH_CATEGORY_REQUIRED)
  • bundle pricing row must exist for that category (ERR_ITN_PUBLISH_HOTEL_PRICING_MISSING)
  • for every priced category, a hotel must be mapped to the itinerary (ERR_ITN_PUBLISH_HOTEL_MAPPING_MISSING_FOR_PRICED_CATEGORY)
  • a primary transfer must be mapped (ERR_ITN_PUBLISH_PRIMARY_TRANSFER_REQUIRED)
  • transfer pricing (capacity slab rows) must exist (ERR_ITN_PUBLISH_TRANSFER_PRICING_MISSING)
• hotel_only (has hotels, no transfers):
  • tripType / effective category must be set (ERR_ITN_PUBLISH_CATEGORY_REQUIRED)
  • bundle pricing row must exist for that category (ERR_ITN_PUBLISH_HOTEL_PRICING_MISSING)
  • for every priced category, a hotel must be mapped to the itinerary (ERR_ITN_PUBLISH_HOTEL_MAPPING_MISSING_FOR_PRICED_CATEGORY)
• transfer_only (no hotels, has transfers):
  • a primary transfer must be mapped (ERR_ITN_PUBLISH_PRIMARY_TRANSFER_REQUIRED)
  • transfer pricing (capacity slab rows) must exist (ERR_ITN_PUBLISH_TRANSFER_PRICING_MISSING)
• activities_only (no hotels, no transfers, has activities):
  • adultPrice must be set in travelerDetails (ERR_ITN_PUBLISH_ACTIVITY_ADULT_PRICE_REQUIRED)