@mongoui/skills 0.1.8 → 0.2.0

package/skills/glink-hotel-api/references/api-workflows.md

@@ -1,158 +1,168 @@
-# Glink API Workflows
-
-Source of truth:
-
-- Current Open Platform route and payload source: `docs/swagger/glink-api.json`.
-- Customer-facing explanations should use only our short interface paths, such as `/search/destination`, `/booking/createOrder`, and `/order/orderDetail`.
-
-## Standard API Integration
-
-Use this mode when the integrator will maintain a local saleable hotel catalog, hotel-room mapping, and daily price refresh jobs.
-
-Mandatory interfaces:
-
-| No. | Interface | Method | Path |
-| --- | --- | --- | --- |
-| 1 | Available Hotel ID List | POST | `/search/hotelIdList` |
-| 2 | Query Hotel Basic Information | POST | `/hotel/detail` |
-| 3 | Hotel Real-Time Product Query | POST | `/booking/productDetails` |
-| 4 | Trial Booking / Availability Check | POST | `/booking/availabilityCheck` |
-| 5 | Create Order | POST | `/booking/createOrder` |
-| 6 | Order Payment | POST | `/booking/payOrder` |
-| 7 | Cancel Order | POST | `/order/cancelOrder` |
-| 8 | Order Detail Query | POST | `/order/orderDetail` |
-
-## Static Data
-
-Use these calls to build hotel search prerequisites:
-
-- `/region/countries`
-- `/region/cities`
-- `/region/popularCities`
-- `/region/districts`
-- `/region/pois`
-- `/region/businesses`
-- `/hotel/groupBrand`
-
-These APIs usually feed country/city selection, district filters, POI filters, business area filters, and brand filters.
-
-For Standard API Integration, build local hotel and room mapping in this order:
-
-1. `/search/hotelIdList`
-   - Fetch the account's saleable hotel ID list and cache it locally.
-2. `/hotel/detail`
-   - Fetch hotel and room static data for the cached hotel IDs. Persist only the fields needed for local hotel and room mapping.
-3. `/hotel/increment`
-   - Periodically fetch changed hotel IDs, including added, updated, or deleted hotels.
-4. `/hotel/detail`
-   - Rehydrate changed hotel IDs and decide whether local mappings should be updated or disconnected.
-5. `/hotel/lowestPrice`
-   - Refresh mapped-hotel starting prices daily, normally after 05:00.
-
-## Lightweight Integration Flow
-
-Use this mode when the user wants a faster launch with less up-front static sync and a destination-driven hotel discovery path.
-
-Mandatory interfaces:
-
-| No. | Interface | Method | Path |
-| --- | --- | --- | --- |
-| 1 | Destination Query | POST | `/search/destination` |
-| 2 | Get Hotel Filter Conditions | POST | `/search/hotelFilters` |
-| 3 | Query Hotel List by Destination | POST | `/search/hotelList` |
-| 4 | Query Hotel Basic Information | POST | `/hotel/detail` |
-| 5 | Query Hotel Basic Information Increment | POST | `/hotel/increment` |
-| 6 | Query Hotel Images | POST | `/hotel/images` |
-| 7 | Hotel Real-Time Product Query | POST | `/booking/productDetails` |
-| 8 | Trial Booking / Availability Check | POST | `/booking/availabilityCheck` |
-| 9 | Create Order | POST | `/booking/createOrder` |
-| 10 | Order Payment | POST | `/booking/payOrder` |
-| 11 | Cancel Order | POST | `/order/cancelOrder` |
-| 12 | Order Detail Query | POST | `/order/orderDetail` |
-| 13 | Order Status Push | POST | `/notify/orderStatus` |
-
-Recommended sequence:
-
-1. `/search/destination`
-   - Resolve the destination keyword into an Open Platform destination ID.
-2. `/search/hotelFilters`
-   - Fetch filter conditions when the UI needs hotel filters.
-3. `/search/hotelList`
-   - Search destination-based hotel results using the destination ID, stay dates, and optional filters.
-4. `/hotel/detail` and optionally `/hotel/images`
-   - Read richer hotel details and media for client display after the hotel list returns candidates.
-5. `/hotel/lowestPrice`
-   - Optional but useful for list-page price reference when the experience needs a stable starting-price display.
-6. `/booking/productDetails`
-   - Query real-time sellable products for a selected hotel on the hotel detail or booking path.
-7. `/booking/availabilityCheck`
-   - Run trial booking with the actual room count before final booking.
-8. `/booking/createOrder`
-   - Create the order after trial booking succeeds. If the booking step is delayed, run `/booking/availabilityCheck` again first.
-9. `/booking/payOrder`
-   - Notify payment status after local payment succeeds or when the platform decides the order should be confirmed.
-
-Lightweight mode still benefits from small local caches:
-
-- Cache destination lookup results from `/search/destination` when the same searches are repeated often.
-- Keep the current hotel IDs from `/search/hotelList` or prior detail-page flows long enough to avoid wasteful duplicate quote traffic.
-- Treat order push/callback as primary even in lightweight mode.
-
-## Booking Flow
-
-Use this sequence for both Standard API Integration and Lightweight Integration Flow:
-
-1. `/booking/productDetails`
-   - Identify the exact sellable room and rate.
-2. `/booking/availabilityCheck`
-   - Perform pre-booking validation with the actual room count. Use this before showing or entering the final order submission path.
-3. `/booking/createOrder`
-   - Submit the order with guest, contact, amount, and price item details. When the local order has been created and is ready to submit, call `/booking/availabilityCheck` again first if there is any delay or state change risk.
-4. `/booking/payOrder`
-   - Notify payment after local customer payment succeeds, or after the platform has decided the order should be confirmed.
-5. `/notify/orderStatus`
-   - Treat the push/callback as the primary confirmation result channel. The receiver must be idempotent.
-6. `/order/orderDetail`
-   - Use as low-frequency compensation only before final confirmation or cancellation. Do not keep polling confirmed or canceled orders.
-
-Key order identifiers:
-
-- `coOrderCode`: customer platform order number.
-- `fcOrderCode`: FCG order number when available.
-
-Prefer carrying both once they appear, because several aftercare APIs accept one or both.
-
-## Order Aftercare
-
-Use these calls after booking:
-
-- `/order/cancelOrder`
-  - Cancel an order when policy permits, when the customer asks to cancel, or when the local unpaid timeout is reached, such as 30 minutes. If cancellation returns success, update the local order and do not continue polling for another push.
-- `/notify/orderStatus`
-  - Required for order confirmation progress after `/booking/payOrder`; implement idempotency.
-- `/order/checkInDetail`
-  - Read extended order or check-in related detail.
-- `/order/checkoutRequest`
-  - Submit a checkout or refund-like aftercare request for an order.
-- `/order/checkoutDetail`
-  - Query the checkout task by `taskOrderCode`.
-
-## Finance
-
-Use these calls for financial follow-up:
-
-- `/order/invoiceRequest`
-  - Submit invoice information using business fields only.
-- `/order/invoiceInfo`
-  - Query invoice status and invoice metadata after an invoice request.
-- `/search/creditBalance`
-  - Read remaining credit balance.
-
-## Business Handling Rules
-
-- Do not treat HTTP `200` as enough; inspect `code`.
-- Use only our short interface paths in customer-facing docs and workflows.
-- Preserve FCG order identifiers from earlier responses instead of recomputing them.
-- Keep local saleable hotel ID cache and hotel/room mappings current before pricing and booking.
-- Avoid integration quota waste: skip `/booking/productDetails` for hotels not in the saleable hotel cache.
-- Push/callback is primary for order confirmation; `/order/orderDetail` is only a compensation path and should not be frequent.
+# Glink API Workflows
+
+Source of truth:
+
+- Current Open Platform route and payload source: `docs/swagger/glink-api.json`.
+- Customer-facing explanations should use only our short interface paths, such as `/search/destination`, `/booking/createOrder`, and `/order/orderDetail`.
+
+## Standard API Integration
+
+Use this mode when the integrator will maintain a local saleable hotel catalog, hotel-room mapping, and daily price refresh jobs.
+
+Mandatory interfaces:
+
+| No. | Interface | Method | Path |
+| --- | --- | --- | --- |
+| 1 | Available Hotel ID List | POST | `/search/hotelIdList` |
+| 2 | Query Hotel Basic Information | POST | `/hotel/detail` |
+| 3 | Hotel Real-Time Product Query | POST | `/booking/productDetails` |
+| 4 | Trial Booking / Availability Check | POST | `/booking/availabilityCheck` |
+| 5 | Create Order | POST | `/booking/createOrder` |
+| 6 | Order Payment | POST | `/booking/payOrder` |
+| 7 | Cancel Order | POST | `/order/cancelOrder` |
+| 8 | Order Detail Query | POST | `/order/orderDetail` |
+
+## Static Data
+
+Use these calls to build hotel search prerequisites:
+
+- `/region/countries`
+- `/region/cities`
+- `/region/popularCities`
+- `/region/districts`
+- `/region/pois`
+- `/region/businesses`
+- `/hotel/groupBrand`
+
+These APIs usually feed country/city selection, district filters, POI filters, business area filters, and brand filters.
+
+For Standard API Integration, build local hotel and room mapping in this order:
+
+1. `/search/hotelIdList`
+   - Fetch the account's saleable hotel ID list and cache it locally.
+   - Use `pageNo` and `pageSize` for pagination; current examples default to `pageNo=1` and `pageSize=1000`.
+   - Read `totalCount` for the total count when returned.
+2. `/hotel/detail`
+   - Fetch hotel and room static data for the cached hotel IDs. Persist only the fields needed for local hotel and room mapping.
+   - Current static fields use `facility`, `popularFacility`, `roomInfos`, `latBaidu`, `lngBaidu`, `groupName`, and `brandName`.
+   - Room bed structures expose object `bedInfos[]` for both bedroom and living room beds.
+3. `/hotel/increment`
+   - Periodically fetch changed hotel IDs, including added, updated, or deleted hotels.
+4. `/hotel/detail`
+   - Rehydrate changed hotel IDs and decide whether local mappings should be updated or disconnected.
+5. `/hotel/lowestPrice`
+   - Refresh mapped-hotel starting prices daily, normally after 05:00.
+
+## Lightweight Integration Flow
+
+Use this mode when the user wants a faster launch with less up-front static sync and a destination-driven hotel discovery path.
+
+Mandatory interfaces:
+
+| No. | Interface | Method | Path |
+| --- | --- | --- | --- |
+| 1 | Destination Query | POST | `/search/destination` |
+| 2 | Get Hotel Filter Conditions | POST | `/search/hotelFilters` |
+| 3 | Query Hotel List by Destination | POST | `/search/hotelList` |
+| 4 | Query Hotel Basic Information | POST | `/hotel/detail` |
+| 5 | Query Hotel Basic Information Increment | POST | `/hotel/increment` |
+| 6 | Query Hotel Images | POST | `/hotel/images` |
+| 7 | Hotel Real-Time Product Query | POST | `/booking/productDetails` |
+| 8 | Trial Booking / Availability Check | POST | `/booking/availabilityCheck` |
+| 9 | Create Order | POST | `/booking/createOrder` |
+| 10 | Order Payment | POST | `/booking/payOrder` |
+| 11 | Cancel Order | POST | `/order/cancelOrder` |
+| 12 | Order Detail Query | POST | `/order/orderDetail` |
+| 13 | Order Status Push | POST | `/notify/orderStatus` |
+
+Recommended sequence:
+
+1. `/search/destination`
+   - Resolve the destination keyword into an Open Platform destination ID.
+   - The response `data` is an array of flat destination objects. Use `destinationType` and `source` to decide whether the match is a hotel, city, district, business area, Google/Baidu result, or another type.
+2. `/search/hotelFilters`
+   - Fetch filter conditions when the UI needs hotel filters.
+3. `/search/hotelList`
+   - Search destination-based hotel results using the destination ID, stay dates, and optional filters.
+   - List items use `latBaidu` and `lngBaidu`; `groupName` and `brandName` can be displayed when present.
+4. `/hotel/detail` and optionally `/hotel/images`
+   - Read richer hotel details and media for client display after the hotel list returns candidates.
+5. `/hotel/lowestPrice`
+   - Optional but useful for list-page price reference when the experience needs a stable starting-price display.
+6. `/booking/productDetails`
+   - Query real-time sellable products for a selected hotel on the hotel detail or booking path.
+7. `/booking/availabilityCheck`
+   - Run trial booking with the actual room count before final booking.
+8. `/booking/createOrder`
+   - Create the order after trial booking succeeds. If the booking step is delayed, run `/booking/availabilityCheck` again first.
+9. `/booking/payOrder`
+   - Notify payment status after local payment succeeds or when the platform decides the order should be confirmed.
+
+Lightweight mode still benefits from small local caches:
+
+- Cache destination lookup results from `/search/destination` when the same searches are repeated often.
+- Keep the current hotel IDs from `/search/hotelList` or prior detail-page flows long enough to avoid wasteful duplicate quote traffic.
+- Treat order push/callback as primary even in lightweight mode.
+
+## Booking Flow
+
+Use this sequence for both Standard API Integration and Lightweight Integration Flow:
+
+1. `/booking/productDetails`
+   - Identify the exact sellable room and rate.
+2. `/booking/availabilityCheck`
+   - Perform pre-booking validation with the actual room count. Use this before showing or entering the final order submission path.
+   - Use response-level `breakfastNum` and `breakfastType`. Tax breakdown is under `priceItems[].taxDetail` and `roomTaxDetail`.
+3. `/booking/createOrder`
+   - Submit the order with guest, contact, amount, and price item details. When the local order has been created and is ready to submit, call `/booking/availabilityCheck` again first if there is any delay or state change risk.
+   - Use `guestInfos[].guestType` for the guest type dictionary. Do not send the old nested `guestInfos[].nationality` field.
+4. `/booking/payOrder`
+   - Notify payment after local customer payment succeeds, or after the platform has decided the order should be confirmed.
+5. `/notify/orderStatus`
+   - Treat the push/callback as the primary confirmation result channel. The receiver must be idempotent.
+6. `/order/orderDetail`
+   - Use as low-frequency compensation only before final confirmation or cancellation. Do not keep polling confirmed or canceled orders.
+
+Key order identifiers:
+
+- `coOrderCode`: customer platform order number.
+- `fcOrderCode`: FCG order number when available.
+
+Prefer carrying both once they appear, because several aftercare APIs accept one or both.
+
+## Order Aftercare
+
+Use these calls after booking:
+
+- `/order/cancelOrder`
+  - Cancel an order when policy permits, when the customer asks to cancel, or when the local unpaid timeout is reached, such as 30 minutes. Send `cancelReason` when there is a customer or platform reason to record. If cancellation returns success, update the local order and do not continue polling for another push.
+- `/notify/orderStatus`
+  - Required for order confirmation progress after `/booking/payOrder`; implement idempotency.
+- `/order/checkInDetail`
+  - Read extended order or check-in related detail.
+- `/order/checkoutRequest`
+  - Submit a checkout or refund-like aftercare request for an order.
+- `/order/checkoutDetail`
+  - Query the checkout task by `taskOrderCode`.
+  - Use `paymentType` to distinguish prepaid and pay-at-hotel orders. Read `refundDetailList[]` for refund channel/time/amount/bill data and `checkoutDetailPriceItemList[].originalSalePrice` for original daily sale price.
+
+## Finance
+
+Use these calls for financial follow-up:
+
+- `/order/invoiceRequest`
+  - Submit invoice information using business fields only.
+- `/order/invoiceInfo`
+  - Query invoice status and invoice metadata after an invoice request.
+- `/search/creditBalance`
+  - Read remaining credit balance.
+
+## Business Handling Rules
+
+- Do not treat HTTP `200` as enough; inspect `code`.
+- Use only our short interface paths in customer-facing docs and workflows.
+- Preserve FCG order identifiers from earlier responses instead of recomputing them.
+- In `/order/orderDetail`, use `roomGuestNumbers[]` for room-level adult and child counts. Use `originalAmount` for order original amount, and top-level `nationality` as country or region code.
+- Keep local saleable hotel ID cache and hotel/room mappings current before pricing and booking.
+- Avoid integration quota waste: skip `/booking/productDetails` for hotels not in the saleable hotel cache.
+- Push/callback is primary for order confirmation; `/order/orderDetail` is only a compensation path and should not be frequent.

package/skills/glink-hotel-api/references/auth-and-credentials.md

@@ -1,144 +1,144 @@
-# Glink Auth And Credentials
-
-## Required Headers
-
-Send these headers on every Glink open-platform request:
-
-- `X-OP-App-Key`
-- `X-OP-Timestamp`
-- `X-OP-Nonce`
-- `X-OP-Sign`
-
-Optional headers that can help tracing or idempotency:
-
-- `X-OP-Client-Request-Id`
-- `X-Trace-Id`
-- `X-Idempotency-Key`
-
-`X-OP-App-Key` is the issued `open_app_id`.
-
-## Signature Algorithm
-
-Build the canonical string in this exact order, separated by newline characters:
-
-```text
-METHOD
-PATH
-CANONICAL_QUERY
-BODY_SHA256
-TIMESTAMP
-NONCE
-APP_KEY
-```
-
-Rules:
-
-- Uppercase `METHOD`.
-- Use the exact runtime public request path. Customer-facing docs use short paths like `/region/businesses`; for actual signing, prefix with `/openapi/v1/glink`, for example `/openapi/v1/glink/region/businesses`.
-- Sort query parameters by key and then value before joining them as `k=v&k2=v2`.
-- Hash the raw request body bytes with SHA256 and use the lowercase hex digest.
-- Use the request timestamp exactly as sent in `X-OP-Timestamp`.
-- Use the request nonce exactly as sent in `X-OP-Nonce`.
-- Use the same `open_app_id` that is sent in `X-OP-App-Key`.
-- Sign the canonical string with the plain `open_app_secret` using HMAC-SHA256, then output lowercase hex.
-
-Notes:
-
-- Timestamp may be Unix seconds, Unix milliseconds, or RFC3339.
-- The platform validates timestamp drift within roughly `+-5` minutes.
-- Nonce must be unique for the same app key in a short time window.
-- For empty bodies, hash the empty byte string.
-
-## Request Body Rules
-
-Client responsibilities:
-
-- Send only the business fields shown by our Open Platform swagger.
-- Sign the runtime public request path, not only the short interface path.
-- Do not add wrapper objects or hidden integration fields that are not part of our public schema.
-
-If a legacy schema still exposes an internal managed field, prefer the route description and current swagger examples. Do not ask the customer to send fields that are not part of the Open Platform public contract.
-
-## Credential Acquisition
-
-Treat credentials as environment-specific.
-
-Sandbox:
-
-1. The developer applies for app access.
-2. The operator activates the app access with `env_type=sandbox`.
-3. The platform records sandbox Glink mapping and issues a sandbox `open_app_id/open_app_secret`.
-4. The app access becomes `sandbox_active`.
-
-Production:
-
-1. The developer submits production access after sandbox work is complete.
-2. The operator approves production with `env_type=production`.
-3. The platform issues a production `open_app_id/open_app_secret`.
-4. The production credential becomes usable only after the app access reaches `production_active`.
-
-Important constraints:
-
-- Sandbox and production credentials are separate and not interchangeable.
-- Developers can see platform credentials only.
-- Developers cannot see internal integration secrets.
-
-## How To View Or Reset Keys
-
-Developer portal APIs:
-
-- `GET /api/portal/apps/{app_id}/credentials`
-  - Returns the credential list for the app.
-  - Includes `open_app_id`, `provider_code`, `env_type`, `open_secret_version`, and masked secret data.
-  - Does not return the plain secret in normal list queries.
-- `POST /api/portal/apps/{app_id}/credentials/reset`
-  - Resets the platform secret and returns `plain_open_secret`.
-  - If the app has more than one credential mapping, pass both `provider_code` and `env_type`.
-
-Response fields that matter:
-
-- `open_app_id`: the App Key to place into `X-OP-App-Key`.
-- `open_secret_masked`: masked secret for display only.
-- `open_secret_version`: useful for rotation tracking.
-- `plain_open_secret`: returned only on first issuance or reset.
-
-Practical guidance:
-
-- If a developer says "I can only see a masked secret", instruct them to use the reset endpoint or the corresponding portal UI action.
-- If the task is only to call sandbox APIs, do not assume production credentials work.
-- If the app has both sandbox and production mappings, always name the target `env_type` explicitly.
-
-## Common Auth Failures
-
-- `APP_KEY_INVALID`
-  - Wrong `open_app_id`, wrong environment, or the credential does not exist.
-- `SIGN_ERROR`
-  - Wrong secret, wrong path, wrong query ordering, wrong body hash, or newline formatting mismatch.
-- `TIMESTAMP_EXPIRED`
-  - Clock skew exceeds the allowed window.
-- `NONCE_REPLAY`
-  - Nonce was reused under the same app key.
-- `PRODUCT_FORBIDDEN`
-  - The app is not enabled for the product, the mapping is not active, or an IP whitelist rule failed.
-
-## Response Contract
-
-The platform wraps business responses in a common envelope:
-
-```json
-{
-  "request_id": "req_xxx",
-  "trace_id": "trc_xxx",
-  "downstream_request_id": "dreq_xxx",
-  "code": "SUCCESS",
-  "message": "ok",
-  "data": {}
-}
-```
-
-Interpretation:
-
-- `request_id` and `trace_id` are platform-side tracing keys.
-- `downstream_request_id` is a platform response field used for cross-system tracing when available.
-- `code=SUCCESS` means the business call succeeded.
-- `code=SUPPLIER_BIZ_ERROR` means the business call failed after reaching the hotel integration and can still arrive with HTTP `200`.
+# Glink Auth And Credentials
+
+## Required Headers
+
+Send these headers on every Glink open-platform request:
+
+- `X-OP-App-Key`
+- `X-OP-Timestamp`
+- `X-OP-Nonce`
+- `X-OP-Sign`
+
+Optional headers that can help tracing or idempotency:
+
+- `X-OP-Client-Request-Id`
+- `X-Trace-Id`
+- `X-Idempotency-Key`
+
+`X-OP-App-Key` is the issued `open_app_id`.
+
+## Signature Algorithm
+
+Build the canonical string in this exact order, separated by newline characters:
+
+```text
+METHOD
+PATH
+CANONICAL_QUERY
+BODY_SHA256
+TIMESTAMP
+NONCE
+APP_KEY
+```
+
+Rules:
+
+- Uppercase `METHOD`.
+- Use the exact runtime public request path. Customer-facing docs use short paths like `/region/businesses`; for actual signing, prefix with `/openapi/v1/glink`, for example `/openapi/v1/glink/region/businesses`.
+- Sort query parameters by key and then value before joining them as `k=v&k2=v2`.
+- Hash the raw request body bytes with SHA256 and use the lowercase hex digest.
+- Use the request timestamp exactly as sent in `X-OP-Timestamp`.
+- Use the request nonce exactly as sent in `X-OP-Nonce`.
+- Use the same `open_app_id` that is sent in `X-OP-App-Key`.
+- Sign the canonical string with the plain `open_app_secret` using HMAC-SHA256, then output lowercase hex.
+
+Notes:
+
+- Timestamp may be Unix seconds, Unix milliseconds, or RFC3339.
+- The platform validates timestamp drift within roughly `+-5` minutes.
+- Nonce must be unique for the same app key in a short time window.
+- For empty bodies, hash the empty byte string.
+
+## Request Body Rules
+
+Client responsibilities:
+
+- Send only the business fields shown by our Open Platform swagger.
+- Sign the runtime public request path, not only the short interface path.
+- Do not add wrapper objects or hidden integration fields that are not part of our public schema.
+
+If a legacy schema still exposes an internal managed field, prefer the route description and current swagger examples. Do not ask the customer to send fields that are not part of the Open Platform public contract.
+
+## Credential Acquisition
+
+Treat credentials as environment-specific.
+
+Sandbox:
+
+1. The developer applies for app access.
+2. The operator activates the app access with `env_type=sandbox`.
+3. The platform records sandbox Glink mapping and issues a sandbox `open_app_id/open_app_secret`.
+4. The app access becomes `sandbox_active`.
+
+Production:
+
+1. The developer submits production access after sandbox work is complete.
+2. The operator approves production with `env_type=production`.
+3. The platform issues a production `open_app_id/open_app_secret`.
+4. The production credential becomes usable only after the app access reaches `production_active`.
+
+Important constraints:
+
+- Sandbox and production credentials are separate and not interchangeable.
+- Developers can see platform credentials only.
+- Developers cannot see internal integration secrets.
+
+## How To View Or Reset Keys
+
+Developer portal APIs:
+
+- `GET /api/portal/apps/{app_id}/credentials`
+  - Returns the credential list for the app.
+  - Includes `open_app_id`, `provider_code`, `env_type`, `open_secret_version`, and masked secret data.
+  - Does not return the plain secret in normal list queries.
+- `POST /api/portal/apps/{app_id}/credentials/reset`
+  - Resets the platform secret and returns `plain_open_secret`.
+  - If the app has more than one credential mapping, pass both `provider_code` and `env_type`.
+
+Response fields that matter:
+
+- `open_app_id`: the App Key to place into `X-OP-App-Key`.
+- `open_secret_masked`: masked secret for display only.
+- `open_secret_version`: useful for rotation tracking.
+- `plain_open_secret`: returned only on first issuance or reset.
+
+Practical guidance:
+
+- If a developer says "I can only see a masked secret", instruct them to use the reset endpoint or the corresponding portal UI action.
+- If the task is only to call sandbox APIs, do not assume production credentials work.
+- If the app has both sandbox and production mappings, always name the target `env_type` explicitly.
+
+## Common Auth Failures
+
+- `APP_KEY_INVALID`
+  - Wrong `open_app_id`, wrong environment, or the credential does not exist.
+- `SIGN_ERROR`
+  - Wrong secret, wrong path, wrong query ordering, wrong body hash, or newline formatting mismatch.
+- `TIMESTAMP_EXPIRED`
+  - Clock skew exceeds the allowed window.
+- `NONCE_REPLAY`
+  - Nonce was reused under the same app key.
+- `PRODUCT_FORBIDDEN`
+  - The app is not enabled for the product, the mapping is not active, or an IP whitelist rule failed.
+
+## Response Contract
+
+The platform wraps business responses in a common envelope:
+
+```json
+{
+  "request_id": "req_xxx",
+  "trace_id": "trc_xxx",
+  "downstream_request_id": "dreq_xxx",
+  "code": "SUCCESS",
+  "message": "ok",
+  "data": {}
+}
+```
+
+Interpretation:
+
+- `request_id` and `trace_id` are platform-side tracing keys.
+- `downstream_request_id` is a platform response field used for cross-system tracing when available.
+- `code=SUCCESS` means the business call succeeded.
+- `code=SUPPLIER_BIZ_ERROR` means the business call failed after reaching the hotel integration and can still arrive with HTTP `200`.