艾恋相亲开放接口

Appearance

跟进任务 ​

嘉宾跟进任务是平台向外部系统派发的"今日待执行任务"，外部系统拉取后执行匹配/推荐，并将结果回传至平台。

任务列表 ​

GET /api/open/v1/follow-up/tasks

权限：open:follow-up:read

获取今日（或指定日期）待执行的任务列表。

查询参数：

参数类型必填说明
pageint否页码，默认 1
page_sizeint否每页条数，默认 50，最大 1000
statusstring否任务状态，默认 pending：pending / dispatched / completed / failed / skipped
task_typestring否任务类型筛选
datestring否计划日期（YYYY-MM-DD），默认今天
company_idint否按公司筛选

响应示例：

json
{
    "code": 200,
    "message": "success",
    "data": {
        "list": [
            {
                "id": 1001,
                "follow_up_id": 500,
                "guest_id": 2001,
                "guest_name": "张三",
                "company_id": 5,
                "task_type": "recommend",
                "task_day": 3,
                "scheduled_date": "2025-08-08",
                "status": "pending",
                "guest_brief": {
                    "gender": 1,
                    "age": 28,
                    "city": "上海",
                    "education": 3,
                    "occupation": "软件工程师"
                },
                "matchmaker_brief": {
                    "id": 12,
                    "name": "王红娘",
                    "company_name": "上海红娘婚介",
                    "wechat": "wang_hongniang",
                    "wechat_id": "wxid_abc123"
                }
            }
        ],
        "total": 42
    }
}

任务详情 ​

GET /api/open/v1/follow-up/tasks/{task_id}

权限：open:follow-up:read

获取单个任务的完整详情，包含完整嘉宾资料和红娘信息，供外部系统进行匹配计算。

路径参数：

参数类型说明
task_idint任务 ID

响应示例：

json
{
    "code": 200,
    "message": "success",
    "data": {
        "task": {
            "id": 1001,
            "follow_up_id": 500,
            "guest_id": 2001,
            "task_type": "recommend",
            "task_day": 3,
            "scheduled_date": "2025-08-08",
            "status": "pending"
        },
        "guest": {
            "id": 2001,
            "name": "张三",
            "gender": 1,
            "age": 28,
            "height": 178,
            "weight": 72,
            "education_level": 3,
            "income_level": 3,
            "income_amount": 250000,
            "family_income_amount": 350000,
            "family_income_level": "30-50万",
            "occupation": "软件工程师",
            "workplace": "上海",
            "native_place": "江苏",
            "marriage_status": 1,
            "has_children": 0,
            "has_car": 1,
            "has_house": 1,
            "hobbies": "旅游,运动",
            "self_intro": "性格开朗，喜欢旅行和运动...",
            "photos": ["https://oss.ailian.com/guest/2001.jpg"],
            "req_age_min": 25,
            "req_age_max": 30,
            "req_height_min": 160,
            "req_education_min": 3,
            "req_income_amount": 200000,
            "req_income_text": "年收入20万以上",
            "req_location": "上海",
            "requirement": "希望对方年龄在25-30之间...",
            "requirement_tags": {
                "age_min": 25,
                "age_max": 30,
                "height_min": 160,
                "education_min": 3,
                "locations": ["上海"]
            }
        },
        "matchmaker": {
            "id": 12,
            "name": "王红娘",
            "phone": "13800001234",
            "wechat": "wang_hongniang",
            "wechat_id": "wxid_abc123",
            "avatar": "https://oss.ailian.com/avatar/12.jpg",
            "company_id": 5,
            "company_name": "上海红娘婚介",
            "certified": true,
            "guest_count": 120,
            "match_count": 45
        },
        "already_recommended_guest_ids": [2005, 2008],
        "history_match_count": 2
    }
}

说明：

  • guest 字段包含嘉宾的完整资料和择偶要求，供外部系统进行匹配计算
  • already_recommended_guest_ids 是该跟进计划中已推荐过的嘉宾 ID 列表，避免重复推荐
  • matchmaker 包含红娘的完整信息，可用于联系沟通

派发/锁定任务 ​

POST /api/open/v1/follow-up/tasks/{task_id}/dispatch

权限：open:follow-up:write

锁定一个待执行任务，标记为"已派发"。同一任务不能被重复派发。

路径参数：

参数类型说明
task_idint任务 ID

请求体：无

响应示例：

json
{
    "code": 200,
    "message": "success",
    "data": {
        "id": 1001,
        "status": "dispatched",
        "dispatched_at": "2025-08-08T10:30:00",
        "dispatched_to": "crm_system_001"
    }
}

冲突处理：如果任务已被其他系统锁定，返回 HTTP 409。

回传执行成功 ​

POST /api/open/v1/follow-up/tasks/{task_id}/complete

权限：open:follow-up:write

任务执行成功后，回传匹配结果。

路径参数：

参数类型说明
task_idint任务 ID

请求体：

字段类型必填说明
matched_guest_idint否匹配成功的嘉宾 ID
match_scorefloat否匹配分数（0-100）
share_linkstring否分享链接
share_channelstring否分享渠道
extraobject否额外信息（JSON 对象）

请求示例：

json
{
    "matched_guest_id": 2050,
    "match_score": 85.5,
    "share_link": "https://ai.ailian.com/share/abc123",
    "share_channel": "wechat"
}

响应示例：

json
{
    "code": 200,
    "message": "success",
    "data": {
        "task_id": 1001,
        "status": "completed"
    }
}

幂等性：已完成的任务重复调用返回成功（含 "idempotent": true）。

回传执行失败 ​

POST /api/open/v1/follow-up/tasks/{task_id}/fail

权限：open:follow-up:write

任务执行失败时，回传失败原因。

路径参数：

参数类型说明
task_idint任务 ID

请求体：

字段类型必填说明
error_codestring否错误编码
error_msgstring否错误描述

请求示例：

json
{
    "error_code": "GUEST_UNREACHABLE",
    "error_msg": "嘉宾电话无法接通"
}

响应示例：

json
{
    "code": 200,
    "message": "success",
    "data": {
        "task_id": 1001,
        "status": "failed"
    }
}

幂等性：已失败的任务重复调用返回成功（含 "idempotent": true）。

标记跳过 ​

POST /api/open/v1/follow-up/tasks/{task_id}/skip

权限：open:follow-up:write

跳过当前任务（例如嘉宾暂时不配合、数据不完整等）。

路径参数：

参数类型说明
task_idint任务 ID

请求体：

字段类型必填说明
reasonstring否跳过原因

请求示例：

json
{
    "reason": "嘉宾要求暂不匹配"
}

响应示例：

json
{
    "code": 200,
    "message": "success",
    "data": {
        "task_id": 1001,
        "status": "skipped"
    }
}

幂等性：已跳过的任务重复调用返回成功（含 "idempotent": true）。

任务状态流转 ​

pending ──dispatch──> dispatched ──complete──> completed
  │                      │
  │                      ├──fail──> failed
  │                      │
  └──skip──> skipped      └──skip──> skipped

典型对接流程 ​

1. GET  /follow-up/tasks          获取今日待执行任务列表（status=pending）
2. POST /follow-up/tasks/{id}/dispatch  锁定一条任务
3. GET  /follow-up/tasks/{id}     获取完整嘉宾资料 + 择偶要求
4. 外部系统执行匹配/推荐算法
5. POST /follow-up/tasks/{id}/complete  回传匹配结果（或 fail/skip）