@mongoui/skills 0.1.7 → 0.1.9

package/skills/glink-hotel-api/references/endpoint-index.md

@@ -1,130 +1,148 @@
-# Glink Endpoint Index
-
-All routes are public gateway routes. Sign the public path, not the downstream Glink path.
-
-## Static Data
-
-- `glink.queryBusinessList`
-  - `POST /openapi/v1/glink/queryBusinessList`
-  - Required body fields: `cityCode`
-- `glink.queryCountryList`
-  - `POST /openapi/v1/glink/queryCountryList`
-  - Required body fields: none
-- `glink.queryHotelPlateList`
-  - `POST /openapi/v1/glink/queryHotelPlateList`
-  - Required body fields: none
-- `glink.queryHotCityList`
-  - `POST /openapi/v1/glink/queryHotCityList`
-  - Required body fields: none
-- `glink.queryDistrictList`
-  - `POST /openapi/v1/glink/queryDistrictList`
-  - Required body fields: `cityCode`
-- `glink.queryDistrictAndBusiness`
-  - `POST /openapi/v1/glink/queryDistrictAndBusiness`
-  - Required body fields: `cityCode`
-- `glink.queryCityList`
-  - `POST /openapi/v1/glink/queryCityList`
-  - Required body fields: `countryCode`
-
-## Hotel Query
-
-- `glink.queryCityAndHotelByKeyword`
-  - `POST /openapi/v1/glink/queryCityAndHotelByKeyword`
-  - Required body fields: `keyWord`
-- `glink.getDestination`
-  - `POST /openapi/v1/glink/getDestination`
-  - Required body fields: `keyWord`
-  - Swagger example uses `keyword`; double-check the field naming against current backend behavior before coding around it.
-- `glink.getHotelSearch`
-  - `POST /openapi/v1/glink/getHotelSearch`
-  - Required body fields: none
-  - Common fields: `cityCode`, `checkInDate`, `checkOutDate`, `roomNum`, `language`
-- `glink.findHotelList`
-  - `POST /openapi/v1/glink/findHotelList`
-  - Required body fields from schema: `roomFacilityCodes`, `hotelFacilityCodes`, `checkInDate`, `checkOutDate`, `distance`
-  - Treat this as a high-friction route and inspect the real example payload before implementing.
-- `glink.queryHotelAllList`
-  - `POST /openapi/v1/glink/queryHotelAllList`
-  - Required body fields: none
-
-## Hotel Info
-
-- `glink.queryHotelIdList`
-  - `POST /openapi/v1/glink/queryHotelIdList`
-  - Required body fields: none
-  - The Open Platform Glink onboarding flow commonly uses `cityCode` to fetch the account's saleable hotel IDs for that city; verify the current swagger/code example before generating strict DTOs.
-- `glink.queryHotelInfo`
-  - `POST /openapi/v1/glink/queryHotelInfo`
-  - Required body fields: `hotelIds`
-- `glink.queryHotelIncrement`
-  - `POST /openapi/v1/glink/queryHotelIncrement`
-  - Required body fields: `startTime`, `endTime`
-  - Swagger example uses `lastUpdateTime`; inspect schema versus example before generating code.
-- `glink.queryHotelImage`
-  - `POST /openapi/v1/glink/queryHotelImage`
-  - Required body fields: `hotelIds`
-  - Swagger example uses `hotelId`; inspect schema versus example before generating code.
-- `glink.queryHotelMainInfoByHotelIds`
-  - `POST /openapi/v1/glink/queryHotelMainInfoByHotelIds`
-  - Required body fields: `language`
-
-## Product Info
-
-- `glink.queryHotelLowestPrice`
-  - `POST /openapi/v1/glink/queryHotelLowestPrice`
-  - Required body fields: `hotelIds`
-- `glink.queryProductDetail`
-  - `POST /openapi/v1/glink/queryProductDetail`
-  - Required body fields: `hotelId`, `checkInDate`, `checkOutDate`, `roomNum`
-
-## Order Info
-
-- `glink.checkBooking`
-  - `POST /openapi/v1/glink/checkBooking`
-  - Required body fields: `hotelId`, `checkInDate`, `checkOutDate`, `roomId`, `ratePlanId`, `roomNum`, `supplyCode`
-- `glink.createOrder`
-  - `POST /openapi/v1/glink/createOrder`
-  - Required body fields: `hotelId`, `checkInDate`, `checkOutDate`, `roomId`, `ratePlanId`, `roomNum`, `supplyCode`, `totalAmount`, `coOrderCode`, `priceItems`, `guestInfos`, `linkMan`, `linkPhone`, `arriveTime`, `latestArriveTime`
-- `glink.payOrder`
-  - `POST /openapi/v1/glink/payOrder`
-  - Required body fields: none
-  - Common fields: `coOrderCode`, `fcOrderCode`
-- `glink.cancelOrder`
-  - `POST /openapi/v1/glink/cancelOrder`
-  - Required body fields: none
-  - Common fields: `coOrderCode`, `fcOrderCode`, `cancelReson`
-- `glink.queryOrderDetail`
-  - `POST /openapi/v1/glink/queryOrderDetail`
-  - Required body fields: none
-  - Common fields: `coOrderCode`, `fcOrderCode`
-- Glink order operation push/callback
-  - Required by the Open Platform Glink booking flow after `payOrder`.
-  - This is an inbound callback capability rather than a normal public `/openapi/v1/glink/*` request route in the current endpoint list. Before implementing, inspect route code or product requirements for the platform callback URL, signature/auth expectations, idempotency key, and retry handling.
-- `glink.queryOrderCheckDetailInfo`
-  - `POST /openapi/v1/glink/queryOrderCheckDetailInfo`
-  - Required body fields: none
-  - Common fields: `coOrderCode`, `fcOrderCode`
-- `glink.checkoutApply`
-  - `POST /openapi/v1/glink/checkoutApply`
-  - Required body fields: `fcOrderCode`, `checkoutReason`, `checkoutRoomInfoList`
-- `glink.queryCheckoutDetail`
-  - `POST /openapi/v1/glink/queryCheckoutDetail`
-  - Required body fields: `taskOrderCode`
-  - Swagger example uses order codes instead of `taskOrderCode`; inspect the live contract before coding.
-
-## Finance
-
-- `glink.createInvoice`
-  - `POST /openapi/v1/glink/createInvoice`
-  - Business-required fields to focus on: `orderCode`, `invoiceTypeInteger`, `invoiceHeader`, `amount`, `applyId`, `invoiceTitleType`, `getMethod`
-  - Schema still marks `partnerCode` and `sign` as required, but route docs say the platform injects Glink auth fields. Do not send Glink-managed fields from the client.
-- `glink.queryCreditBalance`
-  - `POST /openapi/v1/glink/queryCreditBalance`
-  - Required body fields: none
-
-## Global Notes
-
+# Glink Endpoint Index
+
+Source of truth: current DHub / `docs/swagger/glink-api.json`.
+
+All routes below are customer-facing short interface paths. For actual gateway calls and signing, prefix them with `/openapi/v1/glink`.
+
+Customer-facing explanations should use only short interface paths such as `/search/destination`.
+
+Integration mode shortcuts:
+
+- Standard API Integration: prefer `/search/hotelIdList` -> `/hotel/detail` -> `/hotel/increment` and maintain local saleable hotel mappings.
+- Lightweight Integration Flow: prefer `/search/destination` -> `/search/hotelFilters` -> `/search/hotelList` -> `/hotel/detail`/`/hotel/images` -> `/booking/productDetails` for faster launch.
+
+## Region Static Data
+
+- `/region/countries`
+  - Method: `POST`
+  - Required body fields: none.
+  - Response `data` is an array of country objects directly; there is no `countries` wrapper.
+- `/region/cities`
+  - Method: `POST`
+  - Common body fields: `countryCode`, `language`.
+  - Response `data` is an array of province/city-group objects directly; there is no `provinces` wrapper.
+- `/region/popularCities`
+  - Method: `POST`
+  - Required body fields: none.
+  - Response `data` is an array directly; fields include `latBaidu`, `lngBaidu`, `timeZone`, and `areaType`.
+- `/region/businesses`
+  - Method: `POST`
+  - Common body fields: `cityCode`, `language`.
+- `/region/districts`
+  - Method: `POST`
+  - Common body fields: `cityCode`, `language`.
+- `/region/pois`
+  - Method: `POST`
+  - Common body fields: `cityCode`, `keyword`, `language`.
+
+## Hotel Info
+
+- `/search/hotelIdList`
+  - Method: `POST`
+  - Common body fields: `cityCode`, `pageNo`, `pageSize`.
+  - Use `pageNo >= 1` and `pageSize >= 1`; examples default to `pageNo=1`, `pageSize=1000`.
+  - Response pagination uses `totalCount`, not `total`; pagination fields may be absent.
+  - Use for saleable hotel ID bootstrap and cache refresh.
+- `/hotel/popularIdList`
+  - Method: `POST`
+  - Common body fields: `pageNo`, `pageSize`.
+- `/hotel/detail`
+  - Method: `POST`
+  - Required body fields: `hotelIds`.
+  - Current response uses `facility`, `popularFacility`, `applicableRoomTypes`, `openingDate`, `groupId`, `groupName`, `brandId`, `brandName`, `latBaidu`, `lngBaidu`, `wiredBroadband`, `wirelessBroadband`, `comment.averageScore`, and `comment.source`.
+  - Meeting images are under `hotelMeetingInfos[].meetingImages`; do not expect derived size URLs in that node.
+  - Room bed info under both `roomBeds` and `livingRoomBeds` uses object `bedInfos[]` with `bedTypeCode`, `bedName`, `bedWidth`, and `bedNum`.
+- `/hotel/increment`
+  - Method: `POST`
+  - Common body fields: `startTime`, `endTime`, `maxId`, `pageSize`.
+- `/hotel/lowestPrice`
+  - Method: `POST`
+  - Common body fields: `hotelIds`, `checkInDate`, `checkOutDate`, `checkInType`.
+- `/hotel/images`
+  - Method: `POST`
+  - Common body fields: `hotelIds` or `hotelId`; verify the current swagger example before strict DTO generation.
+- `/hotel/groupBrand`
+  - Method: `POST`
+  - Required body fields: none.
+
+## Search And Booking
+
+- `/search/destination`
+  - Method: `POST`
+  - Common body fields: `keyWord`, `cityCode`, `destinationType`, `source`.
+  - Response `data` is an array directly. Destination item fields are flat and include `destinationId`, `destinationType`, `source`, name/code fields, `hotelId`, `latGoogle`, `lngGoogle`, `latBaidu`, and `lngBaidu`.
+- `/search/hotelFilters`
+  - Method: `POST`
+  - Common body fields: `destinationId`, `language`, `lngGoogle`, `latGoogle`, `distance`.
+- `/search/hotelList`
+  - Method: `POST`
+  - Common body fields: `destinationId`, `lngGoogle`, `latGoogle`, `checkInDate`, `checkOutDate`, filters, `distance`, `currentPage`, `pageSize`.
+  - Response list items use `latBaidu` and `lngBaidu`; items may include `groupName` and `brandName`.
+- `/booking/productDetails`
+  - Method: `POST`
+  - Required body fields: `hotelId`, `checkInDate`, `checkOutDate`, `roomNum`, `numberOfAdults`.
+  - Product response removed `reminder`. `taxAndFeeDetails` and `feeItems` are objects, not arrays. `priceItems[].taxDetail` includes numeric `roomPrice`, `taxFee`, `salesTax`, and `otherTax`.
+- `/booking/availabilityCheck`
+  - Method: `POST`
+  - Required body fields: `hotelId`, `roomId`, `ratePlanId`, `checkInDate`, `checkOutDate`, `roomNum`, `supplyCode`.
+  - Response-level `breakfastNum` and `breakfastType` are outside `priceItems`. `roomTaxDetail` is an object. `priceItems[].taxDetail` contains room and tax breakdown. `roomStatus` is not exposed.
+- `/booking/createOrder`
+  - Method: `POST`
+  - Required body fields: `hotelId`, `roomId`, `ratePlanId`, `checkInDate`, `checkOutDate`, `roomNum`, `supplyCode`, `totalAmount`, `coOrderCode`, `priceItems`, `guestInfos`, `linkMan`, `linkPhone`, `arriveTime`, `latestArriveTime`.
+  - Use `guestInfos[].guestType` for guest type; do not send `guestInfos[].nationality`.
+- `/booking/payOrder`
+  - Method: `POST`
+  - Common body fields: `coOrderCode`, `fcOrderCode`.
+- `/search/creditBalance`
+  - Method: `POST`
+  - Required body fields: none; send `{}` or omit body according to the SDK/runtime caller.
+
+## Order Info
+
+- `/order/orderDetail`
+  - Method: `POST`
+  - Common body fields: `coOrderCode`, `fcOrderCode`.
+  - Response uses `roomGuestNumbers[]` for room-level adult/child counts. It may include `originalAmount`, top-level `nationality`, and `guestInfos[].guestType`.
+- `/order/cancelOrder`
+  - Method: `POST`
+  - Common body fields: `coOrderCode`, `fcOrderCode`, `cancelReason`.
+- `/order/checkInDetail`
+  - Method: `POST`
+  - Common body fields: `coOrderCode`, `fcOrderCode`.
+- `/order/invoiceRequest`
+  - Method: `POST`
+  - Business fields to focus on: `orderCode`, `invoiceTypeInteger`, `invoiceHeader`, `amount`, `applyId`, `invoiceTitleType`, `getMethod`.
+- `/order/invoiceInfo`
+  - Method: `POST`
+  - Common body fields: `coOrderCode` or `fcOrderCode`.
+- `/order/checkoutRequest`
+  - Method: `POST`
+  - Required body fields: `fcOrderCode`, `supplierRefundNumber`, `checkoutReason`, `refundType`, `checkoutRooms`.
+- `/order/checkoutDetail`
+  - Method: `POST`
+  - Common body fields: `taskOrderCode`.
+  - Response includes hotel/product context, `paymentType`, `refundDetailList[]`, and `checkoutDetailPriceItemList[].originalSalePrice`.
+
+## Callback Capabilities
+
+- `/notify/orderStatus`
+  - Method: `POST`
+  - Order status push/callback. The receiver must be idempotent.
+- `/notify/orderOperate`
+  - Method: `POST`
+  - Order operation push/callback. The receiver must be idempotent.
+- `/notify/orderCheckout`
+  - Method: `POST`
+  - Checkout status push/callback. The receiver must be idempotent.
+- `/notify/orderInvoice`
+  - Method: `POST`
+  - Invoice status push/callback. The receiver must be idempotent.
+
+## Global Notes
+
+- Current Glink swagger route count may include outbound request APIs and callback APIs; verify against `docs/swagger/glink-api.json`.
 - Most Glink routes accept plain business JSON bodies with no wrapper objects.
+- For response-shape changes and enum-like values, read `field-and-enum-notes.md` before generating DTOs or examples.
 - Platform error responses can return `401`, `403`, `404`, `500`, `502`, or `504`.
-- Common auth-related `401` codes are `APP_KEY_INVALID`, `SIGN_ERROR`, `TIMESTAMP_EXPIRED`, and `NONCE_REPLAY`.
-- Common `403` cause is `PRODUCT_FORBIDDEN`.
+- Common auth-related `401` codes are `APP_KEY_INVALID`, `SIGN_ERROR`, `TIMESTAMP_EXPIRED`, and `NONCE_REPLAY`.
+- Common `403` cause is `PRODUCT_FORBIDDEN`.

package/skills/glink-hotel-api/references/field-and-enum-notes.md

@@ -0,0 +1,161 @@
+# Glink Field And Enum Notes
+
+Source of truth: current `docs/swagger/glink-api.json` and its examples. If the public portal page is available, compare it with this file before changing SDK or customer-facing guidance.
+
+All paths below are customer-facing short paths. Prefix `/openapi/v1/glink` only for actual gateway calls and signing.
+
+## Current Response Shape Notes
+
+- `/region/countries`
+  - `data` is an array of country objects directly. There is no `countries` wrapper.
+  - Example item: `countryCode`, `countryName`, `countryId`.
+- `/region/cities`
+  - `data` is an array of province/city-group objects directly. There is no `provinces` wrapper.
+  - Example item: `countryCode`, `countryName`, `provinceCode`, `provinceName`, `citys[]`.
+  - City coordinates use `latBaidu`, `lngBaidu`, `latGoogle`, `lngGoogle`.
+- `/region/popularCities`
+  - `data` is an array directly. There is no `list` wrapper.
+  - Current fields include `cityCode`, `cityName`, `parentAreaId`, `latBaidu`, `lngBaidu`, `timeZone`, and `areaType`.
+- `/search/destination`
+  - `data` is an array directly. There is no `destinationDTOList` wrapper.
+  - Destination item is flat: `destinationId`, `destinationType`, `source`, `cityName`, `cityCode`, `destinationName`, province/country fields, `hotelId`, `latGoogle`, `lngGoogle`, `latBaidu`, `lngBaidu`.
+- `/search/hotelIdList`
+  - Request supports `pageNo` and `pageSize`; default examples use `pageNo=1`, `pageSize=1000`.
+  - Response uses `totalCount`, not `total`. Pagination fields may be absent.
+- `/search/hotelList`
+  - Hotel list coordinates use `latBaidu` and `lngBaidu`, not `latitude` and `longitude`.
+  - Items may include `groupName` and `brandName`.
+- `/hotel/detail`
+  - Hotel static details use `facility`, not `hotelFacilityNew`.
+  - Popular hotel facilities use `popularFacility`, not `hotFacility`.
+  - `popularFacility.has24HourFrontDesk` replaces `hourFrontDesk_24`.
+  - Facility room scope uses `applicableRoomTypes`, not `applicableRoomTypeIDs`.
+  - Group and brand fields use `groupId`, `groupName`, `brandId`, and `brandName`.
+  - Baidu coordinates use `latBaidu` and `lngBaidu`; Google coordinates remain `latGoogle` and `lngGoogle`.
+  - Opening date uses `openingDate`, not `praciceDate`.
+  - Room network fields are `wiredBroadband` and `wirelessBroadband`.
+  - Comment fields are `averageScore` and `source`.
+  - `allowsPet`, `petText`, meeting-level `hotelId`, and pet charge `chargeFrequency` are not part of the current public response.
+  - Meeting images use `meetingImages`; derived size URLs and `title` are not exposed there.
+  - `roomBedTypeInfos.roomBeds[].bedGroups[].bedInfos[]` is an object list with `bedTypeCode`, `bedName`, `bedWidth`, and `bedNum`, matching `livingRoomBeds`.
+- `/booking/productDetails`
+  - Product-level `reminder` is removed.
+  - `taxAndFeeDetails` is an object, not an array.
+  - `taxAndFeeDetails.feeItems` is an object, not an array.
+  - `priceItems[].taxDetail` includes `roomPrice`, `taxFee`, `salesTax`, and `otherTax`, all numeric.
+- `/booking/availabilityCheck`
+  - `breakfastNum` and `breakfastType` are at the response `data` level, not under `priceItems`.
+  - `priceItems[].taxDetail` contains `roomPrice`, `taxFee`, `salesTax`, and `otherTax`.
+  - `roomTaxDetail` is an object with `taxFee`, `salesTax`, and `otherTax`.
+  - `roomStatus` is not exposed.
+  - `payAtHotelFee` and `payAtHotelFeeCurrency` refer to hotel-local currency amounts.
+- `/booking/createOrder`
+  - `guestInfos[].guestType` replaces `guestInfos[].nationality`.
+  - `guestType` follows the dictionary item "宾客类型".
+- `/order/orderDetail`
+  - Top-level room occupancy is represented by `roomGuestNumbers[]`, with `roomNumber`, `numberOfAdults`, `numberOfChildren`, and `childrenAges`.
+  - Top-level `roomNumber`, `numberOfAdults`, `numberOfChildren`, and `childrenAges` are not part of the current response.
+  - `originalAmount` is the order original amount.
+  - Top-level `nationality` is the country or region code.
+  - `guestInfos[].guestType` replaces `guestInfos[].nationality`.
+- `/order/cancelOrder`
+  - Request field is `cancelReason`, not `cancelReson`.
+- `/order/checkoutDetail`
+  - Response includes hotel and product context such as `cityCode`, `cityName`, `hotelId`, `hotelName`, `roomId`, `roomTypeName`, `ratePlanId`, and `paymentType`.
+  - `refundDetailList[]` includes `refundChannel`, `refundTime`, `amount`, and `billNo`.
+  - `checkoutDetailPriceItemList[].originalSalePrice` is the original sale price.
+
+## Common Enum-Like Values
+
+Destination and source:
+
+- `destinationType`: `1` hotel, `2` city, `3` district, `4` business area, `5` tourist area, `6` city and surroundings, `7` sub-city area, `8` place or metro station, `9` province, `10` country, `13` other.
+- `source`: `0` Glink, `1` Google, `2` Baidu.
+
+Hotel detail:
+
+- `facility.categoryType`: `1` hotel facility, `2` room facility.
+- `facility.status`: `0` none for all rooms, `1` available for all rooms, `2` available for some rooms. When status is `2`, inspect `applicableRoomTypes`.
+- `breakfastOpenType`: `0` daily open, `1` specified dates.
+- `breakfastOpenTimes[].isOpen`: `0` closed, `1` open.
+- `parkingLocation`: `0` in hotel, `1` nearby.
+- `parkingType`: `0` private parking, `1` public parking.
+- `isReserved`: `0` reservation required, `1` no reservation required, `2` cannot reserve in advance.
+- `isChargeable`: `0` free, `1` some guests may be charged, `2` charged.
+- `parking.chargeType`: `1` per day, `2` per hour, `3` per week, `4` per stay, `5` per entry or exit.
+- `isLimitParking`: `0` no, `1` yes.
+- `isChargePark`: `0` no charging parking, `1` has charging parking.
+- `chargingPile`: comma-separated values; `0` normal charger, `1` Tesla destination charger, `2` Tesla supercharger.
+- `chargingType`: `0` private parking, `1` public parking.
+- `isLimitCharging`: `0` do not display, `1` display first-come-first-served.
+- `informType`: `0` hotel notice, `1` city notice, `2` important notice.
+- `roomInfos[].isAllowSmoking`: `1` yes, `2` no, `3` partial, `-100` unknown.
+- `roomInfos[].addBedflag`: `0` no extra bed, `1` extra bed available, `2` partially available.
+- `hotelVideoInfos[].videoType`: `1` hotel video, `2` room video.
+- Child/extra-bed `chargeManner`: `1` fixed amount, `2` percentage of room fee, `3` percentage of adult average price where applicable.
+- Child/extra-bed `chargeFrequency`: `0` per night, `1` per stay.
+- `addBedType`: `2` extra bed, `3` crib.
+- `childBreakfast.rangeType`: `0` age, `1` height in centimeters.
+- `petPolicy.isCharge`: `0` free, `1` charged.
+- `petPolicy.limitInfos.animalType`: `1` dog, `2` cat, `0` other.
+- Hotel image `imageType`: `1` room, `2` exterior, `3` lobby, `4` facility, `5` other, `6` banquet hall, `7` meeting room, `8` ticket, `9` other service.
+- Image `isMain`: `1` main image, `0` non-main image.
+
+Product, booking, and payment:
+
+- `bookType`: `0` sold out, `1` bookable, `2` partially bookable, `3` view only / not satisfying booking or stay terms.
+- `invoiceModel`: product details currently expose `1` merchant invoice; order detail may use `0` no invoice, `1` merchant invoice, `2` hotel front desk pickup.
+- `invoiceType`: `1` normal invoice, `2` special invoice in product detail. Invoice APIs use the invoice-specific values below.
+- `payAtHotelFlag`: `1` pay at hotel, `0` or other values mean not pay at hotel.
+- `cancelRestrictionType`: `0` no cancellation policy, `1` non-cancellable and non-changeable, `2` cancellation after configured day/time requires penalty, `3` after configured day/time non-cancellable and non-changeable, `4` free cancellation.
+- `windowType`: `0` no window, `1` partial window, `2` window, `3` internal window, `4` skylight.
+- `pointsLabel`: `7` points available; `null` no points.
+- `commissionLabel`: `8` GDS commission; `null` no commission.
+- `settlementLabel`: `9` agency settlement, `10` non-agency settlement.
+- `canBook`: examples use `1` for bookable after availability check.
+- `createOrder.result`: `1` booking succeeded, `2` booking failed.
+- `payStatus`: `1` payment success, `2` payment failure.
+
+Order, cancel, checkout, and invoice:
+
+- `orderStatus`: `2` processing, `3` confirmed, `4` canceled, `5` completed.
+- `cancelResult`: `1` cancellation success, `2` cancellation refused, `3` cancelling.
+- `invoiceRequest.invoiceType`: `0` electronic normal, `1` electronic special, `2` paper normal, `3` paper special.
+- `invoiceTitleType`: `0` company, `1` personal or non-company.
+- `invoiceTitleCode`: value range `1` to `6`.
+- `invoiceDeliveryMethod`: `1` email, `2` post, `3` self-pickup.
+- `invoiceInfo.invoiceStatus`: `0` pending, `1` downloaded and waiting for ticket creation, `2` ticket creation failed, `3` invoice binding failed, `4` invoiced, `5` invoicing, `6` invoiced and waiting for download, `7` invoicing failed, `8` attachment downloaded.
+- `invoicePickup.getMethod`: `1` email.
+- `invoicePickup.sendStatus`: `0` not sent, `1` sent, `2` send failed.
+- `checkoutRequest.refundType`: `0` whole-order cancellation, `1` partial cancellation.
+- `checkoutDetail.paymentType`: `0` prepaid, `1` pay at hotel.
+
+## Practical Scenarios
+
+### Standard catalog integration
+
+Use this when the partner maintains local hotel and room mappings.
+
+1. Build a saleable hotel cache with `/search/hotelIdList` using `pageNo` and `pageSize`.
+2. Fetch static details with `/hotel/detail`. Persist current field names such as `facility`, `popularFacility`, `roomInfos`, `latBaidu`, `lngBaidu`, `groupName`, and `brandName`.
+3. Refresh static changes with `/hotel/increment`, then hydrate changed IDs with `/hotel/detail`.
+4. Refresh starting prices with `/hotel/lowestPrice` for list display.
+5. Call `/booking/productDetails` only for hotels in the local saleable cache.
+6. Use `/booking/availabilityCheck` immediately before `/booking/createOrder`; repeat the check if order submission is delayed.
+
+### Lightweight destination integration
+
+Use this when the partner does not want a full static hotel sync.
+
+1. Resolve a keyword with `/search/destination`; the response is an array and `destinationType/source` identify the result type and source.
+2. Fetch filters with `/search/hotelFilters` when the UI needs filter panels.
+3. Search hotels with `/search/hotelList`; use `latBaidu/lngBaidu`, `groupName`, and `brandName` from list items for display.
+4. Hydrate selected hotels with `/hotel/detail` and `/hotel/images`.
+5. Continue with `/booking/productDetails`, `/booking/availabilityCheck`, `/booking/createOrder`, and `/booking/payOrder`.
+
+### Order aftercare
+
+- For customer cancellation or unpaid timeout, call `/order/cancelOrder` with `cancelReason`.
+- Treat `/notify/orderStatus` as the primary confirmation channel. Use `/order/orderDetail` only as compensation.
+- For partial checkout/refund scenarios, call `/order/checkoutRequest` with `refundType=1`, then query `/order/checkoutDetail` by `taskOrderCode`.
+- For invoice flows, call `/order/invoiceRequest`, then `/order/invoiceInfo` for status and pickup/download metadata.