Bỏ qua để đến nội dung

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ồngHướ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épHướ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ợpWeb Components
Cho phép đại lý AI tìm kiếm và đặt phòngMCP Servers và Agentic Payments
Kết nối với channel manager hoặc PMSThêm Channel Manager của bạn

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.

Bạn cần:

  • grpcurl, hoặc Postman hoặc Insomnia. Partner API dùng gRPC, không phải REST.
  • curl.

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.

  1. Truy cập staging-app.wink.travel, nhấn Sign-In / Register và đăng ký.

  2. Nhấn Accounts ở thanh bên trái, rồi Create, 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.

Ứng dụng cung cấp thông tin đăng nhập cho mã của bạn.

  1. Trên thẻ tài khoản của bạn, nhấn Actions > Manage account, rồi tab Applications.

  2. Nhấn Create new application, đặt tên và chọn Machine-to-machine làm loại client.

  3. Dưới phần scopes, chọn Inventory & rates (đọc). Partner API kiểm tra inventory.read.

  4. Nhấn Create application và 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.

Terminal window
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:

Terminal window
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:

errorHTTP statusNguyên nhân thường gặp
invalid_client401Client ID hoặc secret sai, hoặc dùng thông tin sản xuất trên staging-iam
invalid_scope400Yêu cầu scope mà ứng dụng không đăng ký
unauthorized_client400Ứng dụng không được phép dùng grant client_credentials
invalid_request400Thiếu tham số bắt buộc, ví dụ body là JSON thay vì form

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:

Terminal window
grpcurl -H "authorization: Bearer $WINK_TOKEN" \
-d '{}' \
staging-partner.wink.travel:443 wink.partner.v1.Accounts/ListAccounts

Sao chép accountId của tài khoản affiliate từ Bước 1:

Terminal window
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:

Terminal window
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/SearchByCity

Dù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, starRating và 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.

https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID>
  • <urlName> là urlName của khách sạn từ Bước 5.
  • client-id là Client ID của ứng dụng bạn từ Bước 2.
  • configuration-id là 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ĩaVí dụ
sdNgày nhận phòngsd=2027-03-14
n hoặc edSố đêm, hoặc ngày trả phòngn=2 hoặc ed=2027-03-16
rcKhách mỗi phòngrc=a2 (2 người lớn)
lNgôn ngữ hiển thịl=en
cTiền tệ hiển thịc=USD
pMã khuyến mãip=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.

  1. Trong Portal, vào Applications > Webhooks và thêm một endpoint nhận yêu cầu POST.

  2. Đă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.

  3. 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.

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:

  1. 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.

  2. Bỏ staging- khỏi mọi host:

    StagingSản xuất
    https://staging-iam.wink.travelhttps://iam.wink.travel
    staging-partner.wink.travel:443partner.wink.travel:443
    https://staging-book.wink.travelhttps://book.wink.travel
  3. 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.