Môi trường, giới hạn và phiên bản

Sandbox và production, một Base URL

Base URL: https://api.dubaitrip.com/v1. Sandbox và production dùng chung URL này; khóa bạn dùng để ký sẽ chọn môi trường. Khóa dt_sbx_ chạy trên môi trường thử nghiệm của các nhà cung cấp — tìm kiếm, định giá, kiểm tra giá, tạo đơn, đặt phòng, xuất vé và hủy đều hoạt động trọn vẹn trên kho hàng thử nghiệm, không có vé hay voucher thật và không bị tính phí. Khóa dt_live_, được cấp sau khi xét duyệt production, đi tới kho hàng thực và được quyết toán từ tiền ký quỹ của bạn.

Đặt chỗ sandbox và production được tách riêng trong cổng nhà phát triển (mỗi đặt chỗ đều được đánh dấu), còn phạm vi quyền, giới hạn và quy tắc IP được quản lý theo từng môi trường.

Giới hạn tần suất và hạn ngạch

Mỗi khóa bị điều tiết bởi một token bucket (số yêu cầu mỗi giây duy trì cộng một burst) và một hạn ngạch hằng ngày. Mặc định sandbox: 2 yêu cầu/giây, burst 5, 2.000 yêu cầu/ngày. Giới hạn production được thỏa thuận theo từng tài khoản. Vượt quá bucket sẽ trả về 429 api_rate_limited kèm header Retry-After; dùng hết hạn ngạch sẽ trả về 429 api_quota_exceeded cho đến nửa đêm UTC.

Các lượt tìm kiếm nặng được thiết kế bất đồng bộ: truyền wait=false để nhận ngay một searchId rồi thăm dò endpoint tìm kiếm, hoặc wait=true để nhận kết quả đầy đủ trong một lệnh gọi. Mỗi lần thăm dò đều được tính vào giới hạn của bạn như mọi yêu cầu khác.

Giới hạn look-to-book

Các lượt tìm kiếm còn được phân bổ theo số đặt chỗ bạn thực hiện. Mỗi ngày trong một khung thời gian trượt (mặc định 7 ngày) cấp một hạn mức tìm kiếm miễn phí, và mỗi đặt chỗ thực hiện trong khung đó cộng thêm cap lượt tìm kiếm — cap là số lượt tìm kiếm trên mỗi đặt chỗ đã thỏa thuận cho tài khoản của bạn và hiển thị trên cổng nhà phát triển. Các lần thăm dò, định giá, quy tắc giá vé và đọc dữ liệu tĩnh không bao giờ được tính; chỉ các lệnh gọi tìm kiếm chuyến bay và khách sạn mới được tính.

Khi hết hạn mức, các lượt tìm kiếm trả về 429 look_to_book_exceeded kèm header Retry-After chỉ tới nửa đêm UTC kế tiếp, khi ngày cũ nhất trong khung bị loại ra. Một đặt chỗ sẽ mở lại hạn mức ngay lập tức. Thẻ Look-to-book trên cổng nhà phát triển hiển thị bộ đếm trực tiếp, cap và phần còn lại; nếu tích hợp của bạn có lý do chính đáng để tìm kiếm nhiều hơn hẳn số đặt chỗ, hãy đề nghị chúng tôi nâng cap thay vì liên tục thử lại khi bị từ chối.

Idempotency

Các endpoint cam kết tiền hoặc nguồn hàng — tạo đơn hoặc đặt phòng, xuất vé, hủy — yêu cầu header Idempotency-Key (bất kỳ chuỗi duy nhất nào dài tối đa 128 ký tự, UUID là lý tưởng). Thử lại với cùng khóa sẽ trả về phản hồi ban đầu thay vì tạo bản trùng; một nội dung khác dưới khóa đã dùng sẽ trả về 409.

Phiên bản

Phiên bản nằm trong đường dẫn (/v1). Các thay đổi bổ sung — trường tùy chọn mới, giá trị enum mới, endpoint mới — được phát hành mà không tăng phiên bản, vì vậy hãy phân tích một cách phòng thủ và bỏ qua các trường không biết. Thay đổi phá vỡ tương thích sẽ có phiên bản chính mới kèm thời gian chuyển đổi; hướng dẫn Nhật ký thay đổi liệt kê mọi thay đổi.