Để tích hợp thông tin về giá và tình trạng còn chỗ, đố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 Tham chiếu, nhưng bạn có thể tìm thấy thông tin về các vấn đề chung sau này.
Định dạng yêu cầu và phản hồi
Ban đầu, hệ thống sẽ chỉ hỗ trợ định dạng JSON. Nếu bạn cần thêm đị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 tại transport-help@google.com để 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 nội dung POST.
Xin lưu ý rằng để đảm bảo tính rõ ràng về cấu trúc, tài liệu về giao diện API được cung cấp dưới dạng định nghĩa thông báo vùng đệm giao thức và bản dịch định nghĩa thông báo vùng đệm giao thức sang đối tượng JSON được xác định bằng cách ánh xạ JSON chính tắc, 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.
Xác thực
Google hỗ trợ phương thức Xác thực tiêu hoá HTTP, OAuth 2.0 và Xác thực chứng chỉ ứng dụng khách (xem phần Cấu hình đối tác). Đối tác nên cung cấp cho Google thông tin đăng nhập chính xác trong quá trình kiểm thử API:
- Đối với phương thức Tiêu hoá: tên người dùng và mật khẩu.
- Đối với OAuth 2.0: client_id và client_secret.
- Đối với Chứng chỉ: Chứng chỉ ứng dụng khách SSL.
Mã trạng thái và xử lý lỗi
Nói chung, bạn có thể trả về các mã trạng thái sau trong phản hồi HTTP:
| Mã HTTP | 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 kết quả thành công (ví dụ: TripOptionsResult), không phải phản hồi lỗi. |
| 400 | Yêu cầu lỗi | Yêu cầu nhận được không hợp lệ. Bạn nên sử dụng 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 có tên không chính xác trong yêu cầu). |
| 403 | Cấm | Quyền bị từ chối/cấm (người gọi đã biết và bị từ chối). Bạn không được sử dụng phản hồi này cho các trường hợp từ chối do hết một số tài nguyên (hãy sử dụng Lỗi quá nhiều yêu cầu cho những lỗi đó). Bạn không được sử dụng Lỗi cấm nếu không xác định được người gọi (hãy sử dụng Lỗi không được phép 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 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 đã hế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 mong đợi đã bị phá vỡ. Mã lỗi này được dành riêng cho các lỗi nghiêm trọng và cho biế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 rất có thể là một điều kiện tạm thời mà bạn có thể khắc phục bằng cách thử lại với thời gian chờ. |
| 504 | Hết thời gian chờ của cổng nối | Thời hạn đã hết 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 hết. |
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 phản hồi hoặc thông báo lỗi dành riêng cho phương thức được xác định trong API.
- bạn nên 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 lỗi hay không
- Bạn không thể thử lại
SEGMENT_KEY_NOT_FOUND.
- Bạn không thể thử lại
- Chỉnh sửa thông tin cũ
Unavailable.Reason.CANCELEDcho biết chuyến đi nên được xóa (xin lưu ý rằng đây là một phần của phản hồi thành công)Unavailable.Reason.TEMPORARILY_UNAVAILABLEcũng như các mã lỗiSEGMENT_KEY_NOT_FOUND,SUBOPTIMAL_ITINERARY,BOOKING_WINDOW_NOT_SUPPORTEDvàTICKETING_PROHIBITEDsẽ 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 xuất phát. Nếu bạn cần thêm các loại lỗi, vui lòng liên hệ với Nhóm vận chuyển của Google Du lịch.
QPS (Số truy vấn mỗi giây)
Mức QPS mà Google gửi có thể thay đổi dựa trên 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 để truy cập vào trang web của đối tác để đặt chỗ.
Độ trễ
Yêu cầu sẽ hết thời gian chờ sau 10 giây. Sẽ không có nguyên tắc bổ sung về độ trễ cho quá trình tích hợp đối tác phiên bản beta. Tuy nhiên, các SLO độ trễ khác sẽ được xác định trong Nguyên tắc về chất lượng dữ liệu đối tác.
Đơn vị tiền tệ, thuế và phí
Tất cả giá được gửi đến Google 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 đơn vị tiền tệ được hỗ trợ.
Đơn vị tiền tệ
Đơn vị tiền tệ cho một mức giá được chỉ định bằng currency_code
trường. Trường này phải là mã đơn vị tiền tệ
ISO 4217 hợp lệ.
Ví dụ: 10,25 USD:
{
"price": {
"currency_code": "USD",
"units": 10,
"nanos": 250000000
}
}
Thuế và phí
Giá mà bạn cung cấp phải là giá cuối cùng, tổng giá mà người dùng sẽ trả, bao gồm tất cả các khoản thuế (như thuế GTGT) và mọi khoản phí bổ sung (như phí đặt chỗ hoặc phí thẻ thanh toán). Bạn có thể thêm thông tin chi tiết không bắt buộc về giá vé 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á kèm theo thông tin chi tiết không bắt buộc về giá vé cho người dùng.