Bắt đầu nhanh
Hướng dẫn này đưa bạn từ con số không đến tích hợp hoạt động trong khoảng 30 phút. Cuối cùng bạn sẽ có:
- giá trực tiếp cho khách sạn trong một thành phố, từ Partner API,
- một liên kết đặt phòng ghi nhận đặt phòng vào tài khoản của bạn,
- một đặt phòng thử nghiệm, và một webhook thông báo cho bạn khi có đặt phòng.
Mọi thứ diễn ra trong staging, môi trường thử nghiệm của chúng tôi. Bạn không cần xin phép truy cập, và việc chuyển sang môi trường sản xuất sau này cũng không cần phê duyệt.
Đây có phải hướng dẫn phù hợp với bạn không?
Phần tiêu đề “Đây có phải hướng dẫn phù hợp với bạn không?”| Bạn muốn… | Bắt đầu tại đây |
|---|---|
| Hiển thị khách sạn trong ứng dụng, trang web hoặc sản phẩm AI của bạn và gửi khách du lịch để đặt phòng, kiếm hoa hồng | Hướng dẫn này |
| Đặt phòng thay cho khách hàng với tư cách đại lý du lịch có giấy phép | Hướng dẫn này đến Bước 5, sau đó xem Đặt phòng với tư cách đại lý du lịch |
| Nhúng khách sạn có thể đặt mà không cần viết tích hợp | Web Components |
| Cho phép đại lý AI tìm kiếm và đặt phòng | MCP Servers và Agentic Payments |
| Kết nối với channel manager hoặc PMS | Thêm Channel Manager của bạn |
Cách hoạt động
Phần tiêu đề “Cách hoạt động”Bạn sử dụng Partner API để tìm khách sạn và giá trực tiếp của chúng. Mỗi khách sạn có một urlName ổn định. Bạn biến nó thành liên kết đến Wink Booking Engine, book.wink.travel, mang theo các ID của bạn. Khách du lịch đặt phòng và thanh toán tại đó, và đặt phòng được ghi nhận vào tài khoản của bạn.
Trước khi bắt đầu
Phần tiêu đề “Trước khi bắt đầu”Bạn cần:
grpcurl, hoặc Postman hoặc Insomnia. Partner API dùng gRPC, không phải REST.curl.
Bước 1: Tạo tài khoản staging
Phần tiêu đề “Bước 1: Tạo tài khoản staging”Staging hoàn toàn tách biệt với sản xuất, với đăng nhập và tài khoản riêng.
-
Truy cập staging-app.wink.travel, nhấn
Sign-In / Registervà đăng ký. -
Nhấn
Accountsở thanh bên trái, rồiCreate, chọn I am an Affiliate. Các đặt phòng bạn gửi sẽ được ghi nhận vào tài khoản này. Xem Tạo tài khoản.
Bước 2: Tạo ứng dụng
Phần tiêu đề “Bước 2: Tạo ứng dụng”Ứng dụng cung cấp thông tin đăng nhập cho mã của bạn.
-
Trên thẻ tài khoản của bạn, nhấn
Actions>Manage account, rồi tabApplications. -
Nhấn
Create new application, đặt tên và chọn Machine-to-machine làm loại client. -
Dưới phần scopes, chọn Inventory & rates (đọc). Partner API kiểm tra
inventory.read. -
Nhấn
Create applicationvà sao chép Client ID và Client secret. Mật khẩu chỉ hiển thị một lần và không thể lấy lại sau.
Xem Applications để biết các loại client và scope khác.
Bước 3: Lấy access token
Phần tiêu đề “Bước 3: Lấy access token”curl -X POST https://staging-iam.wink.travel/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id=<YOUR_CLIENT_ID>" \ -d "client_secret=<YOUR_CLIENT_SECRET>" \ -d "scope=inventory.read"Lưu access_token từ phản hồi:
export WINK_TOKEN=<access_token>Token có hạn sử dụng. Trong mã của bạn, hãy để thư viện OAuth2 tự động lấy và làm mới token. Xem Xác thực.
Nếu yêu cầu token bị từ chối, phản hồi là một body JSON với mã lỗi error:
error | HTTP status | Nguyên nhân thường gặp |
|---|---|---|
invalid_client | 401 | Client ID hoặc secret sai, hoặc dùng thông tin sản xuất trên staging-iam |
invalid_scope | 400 | Yêu cầu scope mà ứng dụng không đăng ký |
unauthorized_client | 400 | Ứng dụng không được phép dùng grant client_credentials |
invalid_request | 400 | Thiếu tham số bắt buộc, ví dụ body là JSON thay vì form |
Bước 4: Tìm ID tài khoản của bạn
Phần tiêu đề “Bước 4: Tìm ID tài khoản của bạn”Mỗi cuộc gọi Partner API đặt tên tài khoản bạn đang đại diện trong header managing-entity-id. Liệt kê các tài khoản token của bạn có thể đại diện:
grpcurl -H "authorization: Bearer $WINK_TOKEN" \ -d '{}' \ staging-partner.wink.travel:443 wink.partner.v1.Accounts/ListAccountsSao chép accountId của tài khoản affiliate từ Bước 1:
export WINK_ACCOUNT_ID=<accountId>Bước 5: Tìm khách sạn trong một thành phố
Phần tiêu đề “Bước 5: Tìm khách sạn trong một thành phố”Staging có khách sạn thử nghiệm với phòng trống ở Bangkok, nên tìm kiếm dùng slug bangkok-thailand:
grpcurl -H "authorization: Bearer $WINK_TOKEN" \ -H "managing-entity-id: $WINK_ACCOUNT_ID" \ -d '{ "urlName": "bangkok-thailand", "userSession": { "itinerary": { "startDate": "2026-12-01", "nights": 2, "room": { "adults": 2 } }, "currencyCode": "USD", "languageCode": "en" } }' \ staging-partner.wink.travel:443 wink.partner.v1.Search/SearchByCityDùng ngày nhận phòng trong tương lai; ngày trong quá khứ sẽ bị từ chối. Mỗi kết quả có:
name,starRatingvàheroImageUrl, đủ để hiển thị một dòng kết quả,roomTypes, các ưu đãi trực tiếp, phòng rẻ nhất trước,urlName, slug bạn cần cho liên kết đặt phòng.
Giá là số nguyên tính theo đơn vị nhỏ: chia cho 10 mũ currencyExponent từ phản hồi (2 cho USD, nên 12500 là $125.00).
Không biết slug thành phố? Tra cứu với wink.partner.v1.Lookup/Search. Để lấy nội dung đầy đủ của một bất động sản, dùng dịch vụ Content. Tham khảo Partner API mô tả mọi cuộc gọi.
Bước 6: Tạo liên kết đặt phòng
Phần tiêu đề “Bước 6: Tạo liên kết đặt phòng”https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID><urlName>làurlNamecủa khách sạn từ Bước 5.client-idlà Client ID của ứng dụng bạn từ Bước 2.configuration-idlà ID tùy chỉnh của bạn:Manage account>Customizations. Tùy chỉnh cũng thiết lập thương hiệu, ngôn ngữ mặc định và tiền tệ trên trang đặt phòng.
Truyền thông tin tìm kiếm của khách du lịch
Phần tiêu đề “Truyền thông tin tìm kiếm của khách du lịch”Thêm ngày, khách, ngôn ngữ và tiền tệ của khách du lịch vào cùng liên kết để trang khách sạn mở ra với các thông tin đã điền:
https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID>&sd=2027-03-14&n=2&rc=a2&l=en&c=USD| Tham số | Ý nghĩa | Ví dụ |
|---|---|---|
sd | Ngày nhận phòng | sd=2027-03-14 |
n hoặc ed | Số đêm, hoặc ngày trả phòng | n=2 hoặc ed=2027-03-16 |
rc | Khách mỗi phòng | rc=a2 (2 người lớn) |
l | Ngôn ngữ hiển thị | l=en |
c | Tiền tệ hiển thị | c=USD |
p | Mã khuyến mãi | p=ABC123 |
Các tham số này ghi đè mặc định trong tùy chỉnh của bạn. Hướng dẫn nút Đặt Ngay mô tả đầy đủ định dạng rc, bao gồm trẻ em và nhiều phòng.
Liên kết mở trang khách sạn; không thể chọn trước phòng hay giá. Khách du lịch chọn phòng trên trang khách sạn, với giá trực tiếp.
Xem Liên kết trực tiếp để liên kết đến trang chủ booking engine thay vì một khách sạn riêng.
Bước 7: Thực hiện đặt phòng thử nghiệm
Phần tiêu đề “Bước 7: Thực hiện đặt phòng thử nghiệm”Mở liên kết của bạn, chọn ngày và phòng, thanh toán bằng thẻ thử nghiệm Stripe, ví dụ 4242 4242 4242 4242 với ngày hết hạn tương lai và mã CVC bất kỳ. Không có thẻ thật nào bị trừ tiền trong staging. Ghi lại mã đặt phòng trên trang xác nhận; nó bắt đầu bằng WNK.
Bước 8: Nhận thông báo về đặt phòng
Phần tiêu đề “Bước 8: Nhận thông báo về đặt phòng”-
Trong Portal, vào
Applications > Webhooksvà thêm một endpoint nhận yêu cầuPOST. -
Đăng ký sự kiện
booking.create, hoặc để trống danh sách sự kiện để nhận tất cả trong quá trình phát triển. -
Gửi sự kiện thử nghiệm cho chính bạn, rồi thực hiện đặt phòng thử nghiệm khác và theo dõi sự kiện đến.
Xác minh chữ ký mỗi lần gửi trước khi tin tưởng. Xem Tích hợp Webhook và Danh mục sự kiện Webhook.
Bước 9: Chuyển sang sản xuất
Phần tiêu đề “Bước 9: Chuyển sang sản xuất”Không có bước phê duyệt cho nhà phát triển. (Tài khoản đại lý du lịch được chứng nhận trước; xem phần dưới.) Khi tích hợp của bạn hoạt động trong staging:
-
Tạo tài khoản và ứng dụng tại app.wink.travel, như các Bước 1 và 2. Thông tin đăng nhập không chuyển giữa các môi trường.
-
Bỏ
staging-khỏi mọi host:Staging Sản xuất https://staging-iam.wink.travelhttps://iam.wink.travelstaging-partner.wink.travel:443partner.wink.travel:443https://staging-book.wink.travelhttps://book.wink.travel -
Tra cứu lại ID tài khoản sản xuất (Bước 4) và ID tùy chỉnh (Bước 6). Chúng khác với staging.
Partner API tính phí theo số đêm khách sạn, với hạn mức miễn phí hàng tháng. Xem Partner API để biết giá và giới hạn.
Đặt phòng với tư cách đại lý du lịch
Phần tiêu đề “Đặt phòng với tư cách đại lý du lịch”Nếu tài khoản của bạn là đại lý du lịch có giấy phép, bạn không cần gửi khách du lịch đến book.wink.travel: bạn có thể tạo đặt phòng trực tiếp với wink.partner.v1.Booking/CreateBooking, và quản lý chúng với các cuộc gọi Booking khác. Các tài khoản khác gửi khách du lịch đến liên kết đặt phòng.
Tài khoản đại lý du lịch được chứng nhận: Wink xem xét đăng ký của mỗi đại lý trước khi cho phép đặt phòng. Đại lý muốn thu tiền trực tiếp từ khách hàng, với tư cách người bán hàng, phải đặt phòng qua Partner API và được Wink chấp thuận bằng văn bản. Xem Bắt đầu với tư cách đại lý du lịch và Tham khảo Partner API.
Các bước tiếp theo
Phần tiêu đề “Các bước tiếp theo”- Tạo client typed từ schema
.protothay vì gọigrpcurlthủ công. - Kết nối MCP server và dùng AI Skills để trợ lý lập trình viết tích hợp với API trực tiếp.
- Đọc danh sách đầy đủ môi trường và host.
