B2B Booking Skill

> ⚠️ Critical Rules (Must Follow)

>

> 1. Never fabricate hotels, room types, or prices from training data or memory. All hotel-related data MUST come exclusively from the live HTTP API responses. If an API call fails and retries do not help, tell the user the exact error — never answer from memory or recommend alternatives on your own.

> 2. When the API returns HTTP 401 or {"ok": false, "error": "unauthorized: ..."}, the user_key is invalid or expired. Stop the workflow immediately: delete {baseDir}/user_key.txt and ask the user to visit the AgentAuth Dashboard to obtain a new user_key before continuing.

> 3. Interpret the cancellation policy field cancelPolicyInfos correctly. refundable: true means the rate IS refundable / cancellable — never interpret it as "non-cancellable". For refundable rates, startDateTime is the free-cancellation deadline: cancelling before it is free, cancelling after it incurs the amount as a cancellation fee. amount > 0 does NOT mean the rate is non-cancellable.

API

Base URL: http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028

All endpoints are POST and require a user_key field in the request body.

Endpoint List

Response Format

Success: {"ok": true, "data": {...}}

Failure: {"ok": false, "error": "error description"}

Calling Examples (curl)

# Search regions
curl -s -X POST -H "Content-Type: application/json" \
  "http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028/skill/search_location" \
  -d '{"user_key": "<user_key>", "keyword": "Tokyo"}'

# Search hotels
curl -s -X POST -H "Content-Type: application/json" \
  "http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028/skill/search_hotels" \
  -d '{"user_key": "<user_key>", "region_id": "3263", "check_in_date": "2026-05-01", "check_out_date": "2026-05-03", "adults": 2}'

# Query room types
curl -s -X POST -H "Content-Type: application/json" \
  "http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028/skill/query_room_rates" \
  -d '{"user_key": "<user_key>", "hotel_id": "12345", "check_in_date": "2026-05-01", "check_out_date": "2026-05-03", "adults": 2, "room_count": 1}'

# Verify price
curl -s -X POST -H "Content-Type: application/json" \
  "http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028/skill/check_room_availability" \
  -d '{"user_key": "<user_key>", "hotel_id": "12345", "rate_code": "xxx", "check_in_date": "2026-05-01", "check_out_date": "2026-05-03", "adults": 2, "room_count": 1}'

# Create booking
curl -s -X POST -H "Content-Type: application/json" \
  "http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028/skill/create_booking" \
  -d '{"user_key": "<user_key>", "hotel_id": "12345", "rate_code": "xxx", "check_in_date": "2026-05-01", "check_out_date": "2026-05-03", "guest_name": "John Smith", "adults": 2, "room_count": 1, "total_price": 1260.00}'

# Query booking
curl -s -X POST -H "Content-Type: application/json" \
  "http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028/skill/query_booking" \
  -d '{"user_key": "<user_key>", "agent_ref_id": "TM20260501001"}'

# Cancel booking
curl -s -X POST -H "Content-Type: application/json" \
  "http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028/skill/cancel_booking" \
  -d '{"user_key": "<user_key>", "agent_ref_id": "TM20260501001"}'

# Pay
curl -s -X POST -H "Content-Type: application/json" \
  "http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028/skill/pay_order" \
  -d '{"user_key": "<user_key>", "agent_ref_id": "TM20260501001", "payment_type": 11}'

Setup

Before calling any API, the user must be authenticated.

Step 1 — User Key

1. Read {baseDir}/user_key.txt.
2. If the file does not exist or is empty — do NOT call any API. Tell the user:

> "Before we start, I need to verify your identity. Please visit https://aauth-170125614655.asia-northeast1.run.app/dashboard, sign in with Google, copy your user_key (format: uk_xxxxxxxx), and paste it here."

When the user provides it, save it to {baseDir}/user_key.txt and continue.

1. If the file exists and has content — use it directly; do NOT ask the user again.
2. If the API returns 401 or an error containing unauthorized — delete {baseDir}/user_key.txt and repeat step 2.

Endpoint Parameters

/skill/search_location

Returns data.regions (region list with region_id) and data.hotels (hotel list with hotel_id).

/skill/search_hotels

Returns data.hotels — at most the 3 cheapest hotels.

/skill/query_room_rates

Returns data.room_types. Each room type contains rate_code, total_price, currency_code, meal_info, refundable, cancelPolicyInfos.

/skill/check_room_availability

Returns data.room_types with the verified live price and rate_code (which may differ from the one returned earlier), plus cancelPolicyInfos.

/skill/create_booking

Returns data.agent_ref_id (booking reference).

/skill/query_booking

/skill/cancel_booking

Returns data.status, data.cancel_fee, data.refund_amount (if any), data.currency. Always confirm the booking reference with the user before cancelling.

/skill/pay_order

Returns data.pay_url — share this link with the user to complete the payment.

Booking Workflow

0. Search region (if needed)  → search_location to get region_id
1. Search hotels              → search_hotels
2. Query room rates           → query_room_rates
3. Verify price & lock room   → check_room_availability
4. Create booking             → create_booking (no phone or email required)
5. Initiate payment           → ask the user for payment method, then pay_order
6. Query booking              → query_booking (any time)
7. Cancel booking             → only after the user explicitly asks AND confirms the booking reference, then cancel_booking

Notes

• All dates must be in YYYY-MM-DD format.
• region_id and hotel_id MUST be passed as strings (e.g. "3263", not 3263).
• total_price MUST use the value returned by check_room_availability, not the one from query_room_rates.
• Do not proactively collect phone numbers or emails — the booking flow does not need them.
• After create_booking, ask for the payment method before calling pay_order.
• Always confirm the booking reference with the user before calling cancel_booking.
• Reading the cancellation policy: refundable: true = refundable / cancellable; startDateTime = free-cancellation deadline; amount = cancellation fee charged after that deadline — it does NOT mean non-cancellable.
• When showing room types for multiple hotels, the data for each hotel MUST come strictly from that hotel's query_room_rates response. Never mix data across hotels. If a hotel returns room_types: None or total: 0, only show "No rooms available for this hotel" — never fill in data from other hotels.
• When an API call fails, report the exact error to the user — do not fabricate data or recommend alternatives.

> For detailed parameter reference, region IDs, currency codes, and troubleshooting, see references/parameter_guide.md