CHL SAAS saas_plat openapi batch_create - nxtele/http-api-document GitHub Wiki

批量创建客户

批量创建客户

  • URL：https://chl-api.nxlink.ai/saas/cdp/openapi/customers/batch_create
  • Method：POST
  • Content-Type：application/json
  • 需要鉴权：是

请求参数

header参数：

参数名 类型 必选 示例值 说明
accessKey String 是 fme2na3kdi3ki 用户身份标识
ts String 是 1655710885431 当前请求的时间戳（单位是毫秒），牛信服务端允许用户端请求最大时间误差为60秒
bizType String 是 2 WhatsApp业务类型，取固定值“2”
action String 是 mt WhatsApp业务操作，取固定值“mt”
sign String 是 6e9506557d1f289501d333ee2c365826 API入参参数签名 查看公共约定

body参数：

参数名 类型 必选 示例值 说明
type integer 是 1 0:放弃旧数据，使用新数据 1:基于旧数据更新/增加数据项目 2:保留旧数据、放弃新数据
tenant_id integer 是 123 租户id
app_key string 是 46oKF=os appkey
strict_binding boolean 否 false 是否开启客户与坐席一一对应的严格绑定模式，默认false
customers array 是 customers信息 批量创建,单次限制100

消息类型

  • customers参数：
参数名 类型 必选 示例值 说明
full_name String 是 - 客户名称，最大长度为255字符
first_name String 否 - 姓，最大长度为128字符
last_name String 否 - 名，最大长度为128字符
sms_phone String 否 - 手机号码，最大长度为30字符，纯数字
whats_app_phone String 否 - WhatsApp号码，最大长度为30字符，纯数字
viber_phone String 否 - viber phone，最大长度为30字符，纯数字
messenger String 否 - messenger，最大长度为32字符，纯数字
instagram String 否 - instagram，最大长度为32字符，纯数字
zalo String 否 - zalo，最大长度为32字符，纯数字
line String 否 - line，最大长度为50字符
country String 否 - 国家，最大长度为50字符
email String 否 - 邮箱，最大长度为50字符
address String 否 - 街道，最大长度为100字符
birthday String 否 - 生日，格式：yyyy-MM-dd
tagStr String 否 - 标签名，以逗号分隔
remark String 否 - 备注，最大长度为2000字符
time_zone String 否 - 时区
gender integer 否 - 性别，1男，0女
customize_field String 否 - 自定义字段数据，JSON格式字符串
belong_seat_user String 否 - 归属坐席，最大长度为128字符。非必填项，未填写时直接创建成功
weight integer 否 - 客户等级，取值范围1-5

注意：

  • sms_phone、whats_app_phone、email、viber_phone、messenger、instagram、line、zalo不能同时为空
  • 电话号码字段（sms_phone、whats_app_phone、viber_phone、messenger、instagram、zalo）必须是纯数字
  • belong_seat_user为非必填项，未填写时不做校验直接创建成功
  • 当strict_binding=true时，如果belong_seat_user不存在，该记录会记录到failItems中，其他记录继续处理

请求示例

批量发送请求示例

body（application/json） 参数：

{
    "type": 0,
    "tenant_id": 123,
    "strict_binding": true,
    "customers": [
        {
            "full_name": "zhang san",
            "first_name": "san",
            "last_name": "zhang",
            "sms_phone": "18163725558",
            "whats_app_phone": "8618163725558",
            "viber_phone": "8618163725558",
            "country": "China",
            "email": "[email protected]",
            "address": "Wujin District, Tai'an City, Fujian Province",
            "birthday": "1976-04-12",
            "remark": "重要客户",
            "tagStr": "test,99",
            "time_zone": "GMT+8",
            "gender": 1,
            "belong_seat_user": "[email protected]",
            "weight": 5,
            "line": "line123456",
            "zalo": "1234567890",
            "messenger": "9876543210",
            "instagram": "1122334455",
            "customize_field": "{\"customize_1_14\": \"aa\"}"
        },
        {
            "full_name": "li si",
            "first_name": "si",
            "last_name": "li",
            "sms_phone": "18135539411",
            "whats_app_phone": "8618135539411",
            "country": "China",
            "email": "[email protected]",
            "address": "Wujin District, Tai'an City, Fujian Province",
            "birthday": "2015-08-19",
            "remark": "普通客户",
            "time_zone": "GMT+8",
            "tagStr": "88,99",
            "gender": 1,
            "belong_seat_user": "[email protected]"
        }
    ]
}

响应参数

响应结构

参数名 类型 说明
code Integer 结果编码
data JsonObject 请求结果
message String 请求结果说明
traceId String 链路追踪ID

data字段结构（BatchCreateResultVO）

参数名 类型 说明
totalCount Integer 总数
successCount Integer 成功数
failCount Integer 失败数
failItems Array 失败详情列表
successItems Array 成功详情列表

FailItem结构

参数名 类型 说明
index Integer 数据在请求中的位置
errorCode Integer 错误码
errorMessage String 错误信息

SuccessItem结构

参数名 类型 说明
index Integer 数据在请求中的位置
customerId Long 客户ID
whatsAppPhone String WhatsApp手机号

响应示例

成功示例（全部成功）

{
    "code": 0,
    "message": null,
    "traceId": "56bf81643292cd6a89ecde64ae00db13",
    "data": {
        "totalCount": 2,
        "successCount": 2,
        "failCount": 0,
        "failItems": [],
        "successItems": [
            {
                "index": 0,
                "customerId": 1214631327620775936,
                "whatsAppPhone": "8618163725558"
            },
            {
                "index": 1,
                "customerId": 1214631327620775937,
                "whatsAppPhone": "8618135539411"
            }
        ]
    }
}

部分成功示例（strict_binding=true时）

{
    "code": 0,
    "message": null,
    "traceId": "de31e85fdcc9489f9a7b8c99193b9a93",
    "data": {
        "totalCount": 2,
        "successCount": 1,
        "failCount": 1,
        "failItems": [
            {
                "index": 1,
                "errorCode": 12148,
                "errorMessage": "归属坐席 agent1 不存在，请前往 管理->成员 确认"
            }
        ],
        "successItems": [
            {
                "index": 0,
                "customerId": 1214631327620775936,
                "whatsAppPhone": "8618163725558"
            }
        ]
    }
}

失败示例（strict_binding=false时，整体失败）

{
    "code": 12148,
    "message": "归属坐席 agent1 不存在，请前往 管理->成员 确认",
    "traceId": "4516857e03a84c4cbe1339a93f24a1b6",
    "data": null
}
⚠️ **GitHub.com Fallback** ⚠️