1. 快速开始
龙虾开放平台（通用版）
  • 欢迎语
  • 快速开始
    • 接入流程
    • 公共请求头
    • 注意事项
    • 速率限制与配额策略
    • 鉴权说明
    • 错误码
  • 机票
    • 机票接口说明
    • 机场搜索
      GET
    • 创建机票订单
      POST
    • 机票验价
      POST
    • 机票查询列表
      POST
  • 酒店
    • 酒店接口说明
    • 酒店查询列表
      POST
    • 酒店房型详情
      POST
    • 创建酒店订单
      POST
  • 数据模型
    • response.Response
    • schema.AirportSearchResponse
    • schema.FlightOrderCreateRequest
    • schema.FlightOrderCreateResponse
    • schema.FlightPricingRequest
    • schema.FlightPricingResponse
    • schema.FlightSearchResponse
    • schema.HotelOrderCreateRequest
    • schema.HotelOrderCreateResponse
    • schema.HotelRoomsRequest
    • schema.HotelRoomsResponse
    • schema.HotelSearchRequest
    • schema.HotelSearchResponse
    • schema.AirportItem
    • schema.ContactInfo
    • schema.InvoiceAddress
    • schema.PassengerInfo
    • schema.PassengerFareItem
    • schema.FlightItem
    • schema.GuestInfo
    • schema.RoomType
    • schema.HotelSearchFilters
    • schema.HotelItem
    • schema.PageInfo
    • schema.CabinFareItem
    • schema.RoomTypeProduct
  1. 快速开始

注意事项

通用约定#

1.
所有接口均通过 HTTPS 调用，生产环境请使用 https://open.longxiachuxing.com/api。
2.
请求体统一为紧凑 JSON（application/json），避免多余空格。
3.
服务端要求来源 IP 必须命中应用白名单，请提前提供调用方公网出口 IP。
4.
业务成功与失败统一通过响应体 code 字段区分，请勿仅依赖 HTTP 状态码。
5.
request_id 在每次响应中返回，排查问题时请优先附上该字段。
6.
Token 一旦签发请妥善保管，切勿写进客户端代码或上传到代码仓库。

机票相关#

1.
舱位价格直下 vs 验价下单：机票搜索 (/open/v1/flight/search) 返回的每个舱位均带 search_offer_id；如果舱位上同时返回 offer_id 且 pricing_required = false，可直接进入下单；否则需调用 /open/v1/flight/pricing 验价拿到 offer_id 后再下单。
2.
offer_id 有效期：验价返回的 offer_id 默认 10 分钟内有效（以响应中的 expired_at 为准），超过后需重新验价。
3.
往返查询：trip_type = roundtrip 时必须同时传 depart_date 和 return_date；tag 字段用于控制返程匹配规则（lowest_price / same_supplier）。
4.
机场搜索：/open/v1/flight/airport/search 仅做模糊查询，不要把它放在主链路上反复调用。

酒店相关#

1.
两步式下单：搜索接口返回的 search_offer_id 仅用于查询房型；产品级 offer_id 必须通过 /open/v1/hotel/rooms 拿到，不可直接拿 search_offer_id 去下单。
2.
价格语义：房型详情 room_types[].products[].price 为 元 / 晚；订单总价由平台按入住天数计算，写入响应的 total_amount。
3.
入境游字段：搜索结果中的 hotel_name_en 仅在该酒店登记了英文名时返回；下单时如需登记英文姓名，请使用 guests[].name_en。
4.
风控约束（与 /open/v1/hotel/search 保持一致）：
不可指定过去日期；
check_out 必须晚于 check_in；
单次最多返回 50 条，超过请分页获取（page + page_size）。

订单 / 幂等#

1.
out_trade_no 即幂等键：<app_id, out_trade_no> 唯一确定一笔订单。同一个 out_trade_no 重复下单会返回相同的平台订单号，不会创建多笔订单。
2.
支付过期时间：机票订单创建后默认在 pay_expire_time 之前完成支付（一般 15 分钟内），超时订单会被自动关单。
3.
回调地址：可在下单时通过 callback_url 传入接入方接收订单状态变化的 Webhook URL；龙虾出行会以 HMAC 签名形式回调（具体格式见后续 Webhook 文档章节）。
4.
退改签：当前版本仅开放下单链路，退改签接口待后续版本上线。

风控与稳定性#

1.
调用方需保证本机时间准确（NTP 同步），避免时区差异导致价格 / 日期类参数被识别为非法值。
2.
不要短时间内重复提交相同搜索请求，命中限流会被临时锁定。
3.
建议在客户端实现 指数退避 + 抖动 的重试策略，避免全部并发集中在同一秒。
4.
出现 5xx / 50001 时通常为偶发性错误，可在 1~2 秒后重试同一请求；若持续失败请联系开放平台运营并附上 request_id。
修改于 2026-06-10 04:13:39
上一页
公共请求头
下一页
速率限制与配额策略
Built with