HAPPYTRAVEL 开放接口 v1

提交订单

提交一位游客的资料。成功后订单直接进入供应商「待处理」，在代理端、供应商端、管理端都能看到。

{
  "external_id": "TRIP-20261104-0081",
  "name": "ZHANG SAN",
  "passport_no": "E12345678",
  "nationality": "CHN",
  "birth_date": "1990-01-01",
  "msisdn": "085283673294",
  "package_serial": "0150000066492291",
  "imei": "866641057096095",
  "arrival_date": "2026-11-06",
  "contact": "+86 138 0000 0000",
  "remark": "晚上航班",
  "passport_photo": "/9j/4AAQSkZJRg...",
  "package_photo": "/9j/4AAQSkZJRg..."
}

{
  "ok": true,
  "order": {
    "order_no": "#1104-012",
    "external_id": "TRIP-20261104-0081",
    "status": "pending",
    "created_at": "2026-11-04 14:30"
  }
}

{
  "ok": false,
  "error": "duplicate_msisdn",
  "message": "这张电话卡已经提交过了",
  "existing_order_no": "#1103-004"
}

查询订单

用平台单号或合作方单号查询。订单号里的 # 可以省略，1104-012 和 %231104-012 都可以。

{
  "ok": true,
  "order": {
    "order_no": "#1104-012",
    "external_id": "TRIP-20261104-0081",
    "status": "returned",
    "return_reason": "护照照片反光，看不清号码",
    "msisdn": "085283673294",
    "imei": "866641057096095",
    "arrival_date": "2026-11-06",
    "created_at": "2026-11-04 14:30",
    "updated_at": "2026-11-04 15:02",
    "history": [
      {"at": "2026-11-04 14:30", "event": "submitted"},
      {"at": "2026-11-04 15:02", "event": "returned", "reason": "护照照片反光，看不清号码"}
    ]
  }
}

订单列表

返回 {"ok":true,"total":128,"page":1,"orders":[…]}，每条订单字段和「查询订单」一样，不含 history。

修改重提交

只有 returned 状态的订单可以重提交。只传要改的字段即可，照片不传就沿用原来的。成功后状态变为 resubmitted，进入供应商「重提交」。

{
  "passport_photo": "/9j/4AAQSkZJRg...",
  "remark": "已重拍护照照片"
}

套餐充值

套餐由平台管理员创建，每个套餐有唯一的产品 ID（product_id）。先用 GET /v1/plans 取得可用套餐，再给订单指定套餐；也可以在提交订单时直接带上 "product_id"。平台充值后按套餐结算金额从代理账户余额扣款。

// GET /v1/plans 返回
{"ok": true, "currency": "¥", "local_currency": "Rp",
 "plans": [{"product_id": "TSEL-10G-30", "name": "10GB 30天", "price": 45.45, "local_price": 100000}]}

// POST /v1/orders/1104-012/topup
{"product_id": "TSEL-10G-30"}      // 传 null 表示取消；已充值的订单不能再改（409 topup_locked）

// 每个订单都带 topup 字段
"topup": {"status": "pending", "product_id": "TSEL-10G-30", "plan": "10GB 30天", "price": 45.45}
// status: none 未选 · pending 待充值 · done 已充值 · failed 充值退回（附 fail_reason）· self 代理自充 · other 其他原因

充值结果会通过回调通知：topup.done（已充值）、topup.failed（充值退回，附 topup_fail_reason）。

识别辅助（可选）

合作方系统如果没有自己的识别功能，可以把照片发过来，用我们平台的识别结果预填表单。传 {"photo":"base64…"}，返回识别出的字段，和网页上的识别是同一套。

// POST /v1/recognize/imei 返回
{"ok": true, "imeis": ["866641057096095", "866641057096103"]}