OTC油商大会数据接收

公共规则

请求方式为 HTTP POST，Body 使用 raw JSON。
请求头必须包含 X-API-Key，值为服务配置中的 API Key。
Content-Type 使用 application/json。
name 和 IMGPath 必传；company、title、id_type、IDCardNO 可选。
IMGPath 必须是绝对 HTTPS 图片地址，最长 65,535 字节，不接受 HTTP、相对路径或 Base64。
barcode 为字符串，最长 200 个字符，不允许重复。新增时可不传，不传由后端生成并返回；更新时必须传。
source_id 建议传对方系统稳定唯一 ID；服务使用 source_id + payload_hash 防止重复插入。
新增数据写入 regs_attendees_11287，默认 ticket 为 观众。

新增人员

POST/api/v1/attendees/receive

{
  "source_id": "miniapp-user-001",
  "name": "张三",
  "IMGPath": "https://cdn.example.com/photos/zhang-san.jpg",
  "company": "",
  "title": "经理",
  "id_type": "idcard",
  "IDCardNO": "330100199001011234"
}

不传 barcode 时，成功响应会返回后端生成的 8 位数字条码。

{
  "code": "OK",
  "message": "received",
  "data": {
    "id": 1,
    "barcode": "56E64EDB09B4"
  },
  "request_id": "..."
}

同一个 source_id 与同一份 payload 重复提交时，不再新增行，返回原记录。

{
  "code": "OK",
  "message": "received",
  "data": {
    "id": 1,
    "barcode": "56E64EDB09B4",
    "duplicate": true
  },
  "request_id": "..."
}

指定条码新增

POST/api/v1/attendees/receive

{
  "source_id": "partner-row-10001",
  "barcode": "56E64EDB09B4",
  "name": "李四",
  "IMGPath": "https://cdn.example.com/photos/li-si.jpg",
  "company": "",
  "title": "总监",
  "id_type": "passport",
  "IDCardNO": "P1234567"
}

更新人员

POST/api/v1/attendees/update

{
  "barcode": "56E64EDB09B4",
  "name": "张三修改后",
  "IMGPath": "https://cdn.example.com/photos/zhang-san-new.jpg",
  "company": "",
  "title": "总监",
  "id_type": "idcard",
  "IDCardNO": "330100199001011234"
}

更新接口必须传 barcode、name 和新的 HTTPS IMGPath。barcode 只用于查找且不可修改；未传 company 时不修改原公司，传空字符串时清空公司。

常见错误码

INVALID_API_KEY: 请求头 API Key 不正确。
INVALID_JSON: Body 不是合法 JSON。
VALIDATION_ERROR: 必填字段缺失、类型不正确、图片地址非法或字段超过长度限制。
DUPLICATE_BARCODE: 指定 barcode 已存在，或自动生成多次碰撞。
DUPLICATE_REQUEST: source_id 与 payload 指纹已经存在，但未能返回原记录。
ATTENDEE_NOT_FOUND: 更新时找不到对应 barcode。
DATABASE_ERROR: 数据库读写失败或超时。

OTC油商大会

最后一条