16. 声网 API 16.2 预约视频通话【未授权拦截通过，待登录态联调】

Table of Contents

16.2 预约视频通话【未授权拦截通过，待登录态联调】

POST /tieup/api/v1/video-call-bookings

请求头：

Idempotency-Key: video_call_10001_20260602143000_x7f9k2

请求体：

{
  "artist_id": 1,
  "video_call_plan_code": "call_30m",
  "scheduled_start_at": "2026-06-06 20:00:00",
  "payment_method": "candy"
}

请求参数：

参数 类型 必填 说明
artist_id integer 是 目标艺人 ID
video_call_plan_code string 是 业务配置中的视频通话档位编码
scheduled_start_at string 是 格式：Y-m-d H:i:s
payment_method string 否 当前仅支持 candy=糖果余额；不传默认 candy

响应：

{
  "booking_id": 40001,
  "booking_no": "VC202606170001",
  "artist_id": 20001,
  "scheduled_start_at": "2026-06-20 20:00:00",
  "scheduled_end_at": "2026-06-20 20:10:00",
  "duration_minutes": 10,
  "status": 1,
  "room_no": "VR2026061719590012345678"
}

响应字段：

字段 类型 说明
booking_id integer 视频通话预约 ID
booking_no string 视频通话预约编号
artist_id integer 艺人 ID
scheduled_start_at string 预约开始时间
scheduled_end_at string 预约结束时间
duration_minutes integer 时长，单位分钟
status integer 业务状态值，含义按当前接口业务对象解释；常用值见接口说明或全局 SQL 枚举
room_no string 本地房间编号，调用统一入房接口时作为 room_id 传入

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "booking_id": 40001,
    "booking_no": "VC202606170001",
    "artist_id": 20001,
    "scheduled_start_at": "2026-06-20 20:00:00",
    "scheduled_end_at": "2026-06-20 20:10:00",
    "duration_minutes": 10,
    "status": 1,
    "room_no": "VR2026061719590012345678"
  }
}

业务规则：

  • 粉丝必须已订阅该偶像。
  • video_call_plan_code 必须可关联 tieup_video_call_plan.plan_code，并与艺人 tieup_artist_pricing.video_call_plan_code 兼容。
  • scheduled_start_at 必须命中服务端按艺人当前工作时间、通话时长和休息间隔生成的合法格子起点；非格子起点返回 422。
  • 当前预约接口按糖果余额扣减完成闭环，写入 tieup_order.amount_cent = 0、tieup_video_call_booking、tieup_video_call_room、tieup_video_call_event 和 tieup_user_transaction；payment-delivery 已预留 video_call 已支付订单激活补偿能力，但本接口暂不开放第三方现金视频支付创建。
  • 通话档位不保存糖果数量；预约创建时锁定艺人定价后，按 video_call_price_per_minute（糖果/分钟）乘以档位 duration_minutes 得到糖果数量，写入 tieup_video_call_booking.candy_amount 快照并扣减糖果余额。
  • 同一艺人预约创建时在事务内锁定 tieup_artist_pricing 行，并检查待通话、准备中、通话中的时间段重叠，避免并发重复预约。
  • 同一 fan_user_id + Idempotency-Key 只允许复用同一艺人、同一通话档位和同一预约开始时间，换任一关键参数返回 422。
  • 获取房间前校验参与方身份、预约状态和 enterable_at 至 expired_at 准入窗口。
  • 测试状态：已完成代码实现、PHP 语法检查和局部静态分析，待 APP 统一入房链路联调。