Máy chủ đối tác

Để tích hợp thông tin về giá và tình trạng phòng, đối tác cần triển khai Partner API. Giao diện này dựa trên REST và cho phép Google gửi các lệnh gọi trực tiếp qua HTTP. Mặc dù thông tin chi tiết về từng phương thức API được mô tả trong phần Tài liệu tham khảo, nhưng bạn có thể tìm thấy thông tin về các mối lo ngại chung ở phần sau.

Định dạng yêu cầu và phản hồi

Ban đầu, chỉ định dạng JSON mới được hỗ trợ. Nếu bạn cần thêm các định dạng yêu cầu hoặc phản hồi, hãy liên hệ với Nhóm vận chuyển du lịch theo địa chỉ [e-mail] để thảo luận về trường hợp sử dụng của bạn.

Yêu cầu sẽ được gửi bằng phương thức HTTP POST, với thông báo yêu cầu trong phần nội dung POST.

Xin lưu ý rằng để có cấu trúc rõ ràng, tài liệu về giao diện API được cung cấp dưới dạng các định nghĩa thông báo của Protocol Buffer và bản dịch của một định nghĩa thông báo Protocol Buffer thành một đối tượng JSON được xác định bằng ánh xạ JSON chuẩn, sử dụng các lựa chọn để phát ra các trường có giá trị mặc định và sử dụng tên trường proto thay vì tên lowerCamelCase.

Lưu ý quan trọng: Bạn nên sử dụng các thư viện giao thức đệm và các tiện ích JsonFormat đi kèm cho các API an toàn về kiểu đảm bảo rằng các phản hồi chính xác về mặt cú pháp được tạo ra. Định nghĩa enum xuất hiện trong tài liệu không bao gồm giá trị UNSPECIFIED. Bạn nên thêm các phần này khi sử dụng trực tiếp protobuf.

Xác thực

Google hỗ trợ phương thức Xác thực chuỗi đại diện HTTP và Xác thực bằng chứng chỉ máy khách. Tất cả các lệnh gọi HTTP của Partner API đều sử dụng phương thức Xác thực thông báo HTTP (với tên người dùng và mật khẩu) hoặc Xác thực chứng chỉ ứng dụng. Đối tác phải cung cấp cho Google tên người dùng và mật khẩu (xem phần Cấu hình đối tác) hoặc Chứng chỉ ứng dụng SSL.

Mã trạng thái và xử lý lỗi

Nhìn chung, các mã trạng thái sau đây có thể được trả về trong phản hồi HTTP:

Mã HTTP	Nội dung mô tả HTTP	Ghi chú
2xx	OK	Không phải là lỗi; được trả về khi thành công. Nội dung phản hồi dự kiến sẽ chứa một kết quả thành công (ví dụ: TripOptionsResult), không phải là một phản hồi lỗi.
400	Yêu cầu không hợp lệ	Yêu cầu nhận được không hợp lệ. Bạn nên sử dụng các phản hồi lỗi dành riêng cho phương thức để trả về thông tin chi tiết bổ sung về lỗi trong nội dung phản hồi. Thông thường, bạn chỉ nên sử dụng HTTP 400 nếu Google gặp lỗi kỹ thuật (ví dụ: một trường bị đặt tên sai trong yêu cầu).
403	Cấm	Quyền bị từ chối/bị cấm (người gọi đã biết và bị từ chối). Không được dùng phản hồi này cho các trường hợp từ chối do cạn kiệt một số tài nguyên (thay vào đó, hãy dùng Lỗi quá nhiều yêu cầu cho những lỗi đó). Không được dùng Forbidden nếu không xác định được người gọi (thay vào đó, hãy dùng Unauthorized cho những lỗi đó).
404	Không tìm thấy	Không tìm thấy tài nguyên được yêu cầu. Bạn nên sử dụng các phản hồi lỗi dành riêng cho phương thức để trả về thông tin chi tiết bổ sung về lỗi trong nội dung phản hồi.
429	Quá nhiều yêu cầu	Một số tài nguyên đã cạn kiệt, có thể là hạn mức cho mỗi người dùng.
500	Lỗi máy chủ nội bộ	Lỗi nội bộ. Điều này có nghĩa là một số bất biến mà hệ thống cơ bản dự kiến đã bị phá vỡ. Mã lỗi này dành riêng cho các lỗi nghiêm trọng và cho biết một lỗi trong quá trình triển khai máy chủ API của đối tác.
503	Dịch vụ không khả dụng	Dịch vụ này hiện không hoạt động. Đây có thể là một điều kiện tạm thời. Bạn có thể khắc phục bằng cách thử lại với độ trễ.
504	Hết thời gian chờ của cổng	Đã hết thời hạn trước khi thao tác có thể hoàn tất. Đối với các thao tác thay đổi trạng thái của hệ thống, lỗi này có thể được trả về ngay cả khi thao tác đã hoàn tất thành công. Ví dụ: phản hồi thành công từ một máy chủ có thể bị trì hoãn đủ lâu để thời hạn kết thúc.

Xin lưu ý rằng đối với tất cả các điều kiện tiên quyết, đối số không hợp lệ hoặc lỗi không tìm thấy:

• bạn nên sử dụng các thông báo lỗi hoặc phản hồi dành riêng cho phương thức được xác định trong API.
• bạn phải sử dụng mã http chính xác, như được chỉ định trong mã dành riêng cho phương thức (xem ví dụ: TripOptionsErrorType)

Điều này cho phép cung cấp thông tin chi tiết hơn về các loại lỗi này. Bạn có thể sử dụng thông tin này để:

• Xác định xem có thể thử lại một lỗi hay không
  • Bạn không thể thử lại SEGMENT_KEY_NOT_FOUND.
• Chỉnh sửa thông tin cũ
  • Unavailable.Reason.CANCELED cho biết bạn nên xoá chuyến đi (lưu ý rằng đây là một phần của phản hồi thành công)
  • Unavailable.Reason.TEMPORARILY_UNAVAILABLE cũng như các mã lỗi SEGMENT_KEY_NOT_FOUND, SUBOPTIMAL_ITINERARY, BOOKING_WINDOW_NOT_SUPPORTED và TICKETING_PROHIBITED sẽ xoá mọi mức giá mà chúng tôi đã nhận được trước đó từ bộ nhớ đệm.
• Cung cấp hướng dẫn phù hợp cho người dùng

Danh sách hiện tại về các lỗi dành riêng cho phương thức được cung cấp trong TripOptionsError là điểm bắt đầu. Nếu bạn cần thêm các loại lỗi khác, vui lòng liên hệ với Nhóm Google Travel Transport.

QPS (Số truy vấn mỗi giây)

Mức QPS mà Google gửi có thể thay đổi tuỳ thuộc vào khoảng không quảng cáo của đối tác và số lượng người dùng xem dữ liệu được lưu vào bộ nhớ đệm hoặc nhấp qua trang web của đối tác để đặt phòng.

Độ trễ

Yêu cầu sẽ hết thời gian chờ sau 10 giây. Không có nguyên tắc bổ sung nào về độ trễ đối với các chế độ tích hợp đối tác thử nghiệm. Tuy nhiên, các SLO về độ trễ khác sẽ được xác định trong Nguyên tắc về chất lượng dữ liệu của đối tác.

Đơn vị tiền tệ, thuế và phí

Tất cả giá mà bạn gửi đến Google đều phải bao gồm tất cả các khoản thuế và phí, đồng thời phải được chỉ định bằng một loại tiền tệ được hỗ trợ.

Đơn vị tiền tệ

Đơn vị tiền tệ cho giá được chỉ định bằng cách sử dụng trường currency_code. Trường này phải là mã đơn vị tiền tệ ISO 4217 hợp lệ.

Ví dụ:102.500 VND

{
  "price": {
    "currency_code": "USD",
    "units": 10,
    "nanos": 250000000
  }
}

Thuế và phí

Giá bạn cung cấp phải là giá cuối cùng, tổng giá mà người dùng sẽ thanh toán, bao gồm tất cả các loại thuế (như thuế GTGT) và mọi khoản phí bổ sung (như phí đặt phòng hoặc phí thẻ thanh toán). Bạn có thể thêm thông tin chi tiết về giá vé (không bắt buộc) bằng cách sử dụng trường line_items có thể lặp lại. Google sẽ hiển thị tổng giá và thông tin chi tiết về giá vé (không bắt buộc) cho người dùng.