Linkflow开放接口指南

Linkflow 开放平台目前通过私有 App 对接。私有 App 只属于创建它的租户；使用该 App 获取的 Access Token 也只能访问该租户被授权的资源。

接入约定

项目	约定
公网基础地址	`https://cdp-api.linkflowtech.com`
获取 Token	`GET /token`
业务接口	文档中的接口路径均相对于上述基础地址
鉴权	除 Token 接口外，每个请求必须带 `X-OpenApi-Token` 请求头
请求体	有请求体的接口使用 `Content-Type: application/json`；上传标签文件接口使用 `multipart/form-data`
时间格式	日期参数使用 `yyyy-MM-dd`；日期时间参数使用 `yyyy-MM-dd HH:mm:ss`。含空格的查询参数必须 URL 编码
字符编码	请求和响应均使用 UTF-8 JSON

例如，联系人列表的完整地址是 https://cdp-api.linkflowtech.com/open/contacts。

调用流程

在 Linkflow 管理端创建私有 App，安全保存 App Key 和 App Secret。
调用 GET /token 获取 Access Token；将响应中的 expiration 作为 Token 的最终有效期依据。
调用业务接口时传入 X-OpenApi-Token: <token>。Token 缺失、失效或无权访问时，请重新获取 Token 或检查 App 的资源授权。
对游标接口，使用本批响应中最大的游标字段作为下一次请求的游标；返回空数组即表示没有更多数据。不要并发推进同一个游标。

成功响应按接口定义返回 JSON 数据或 { "code": "0", "message": "ok" }。失败响应通常为包含 code 与 message 的 JSON；客户端应按 HTTP 状态码和 code 处理，不应仅依赖错误文案。接口可能会限流，调用方应对 429、5xx 和可重试网络错误实施带退避的重试。

Private App

创建Private App

通过创建私有App获取 App Key 和 App Secret

登录Linkflow系统之后，进入菜单“设置”－》“App集成设置”－》“私有App设置”，然后点击右上角的按钮“创建私有App”，在弹出窗口中填写“App名字”和“App描述”，最后点击右下角的“保存”按钮，系统就会在当前弹出窗口生成App Key和App Secret。

通过App Key和App Secret获取Access Token

在获取 App Key 和 App Secret 之后，可获取 Access Token 访问 Linkflow 资源。

GET /token?refresh=false HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Key: 创建私有App取得的App Key
X-OpenApi-Secret: 创建私有App取得的App Secret

HTTP/1.1 200 OK
Content-Type: application/json

{
    "expiration": "2017-09-04 09:30:23",
    "token": "Mi03Y2IxNjNkMC05YWFjLTQ5NmYtOWE3OS01NjU3ZWRjMmQwNzk="
}

HTTP Request

GET https://cdp-api.linkflowtech.com/token

Headers

Parameter	Description
X-OpenApi-Key	创建私有App取得的App Key
X-OpenApi-Secret	创建私有App取得的App Secret

Querystring parameters

Parameter	Required	Default	Type	Description
refresh	false	false	Boolean	`false` 时有效 Token 会被复用；`true` 时强制生成并替换当前 Token。仅在确有泄露或轮换需求时使用。

expiration 是 Token 的到期时间。请在到期前刷新并安全存储 Token；不要在客户端代码、日志或错误信息中暴露 App Secret 或 Token。

联系人和事件

创建联系人和事件

POST /open/messages HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，返回200状态码及成功消息

HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": "0",
    "message": "ok"
}

请求示例如下：

{
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "channelKey": "udc_12SyQfFmg",
    "channelType": "UDC",
    "identities": [
        {
            "id": "321100199012203412",
            "type": "idCard"
        },
        {
            "id": "email@163.com",
            "type": "email"
        }
    ],
    "messages": [
        {
            "message_id": "{随机uuid}",
            "domain": "contact",
            "action": "set",
            "ts": 1663146117310,
            "data": {
                "name": "contactName",
                "email": "email@163.com",
                "utm": {},
                "props": {
                    "string": "merge1",
                    "int": 11,
                    "date": "2022-09-15T03:20:13.000Z",
                    "long": 11111111111111112001,
                    "bool": false
                }
            }
        },
        {
            "message_id": "{随机uuid}",
            "domain": "identity",
            "action": "set",
            "ts": 1663146117310,
            "data": {
                "id": "member_10001",
            }
        },
        {
            "message_id": "{随机uuid}",
            "domain": "event",
            "action": "track",
            "ts": 1667295883115,
            "data": {
                "utm": {},
                "event": "WECHAT_WXA__HIDE",
                "eventDate": 1663146117310,
                "props": {
                    "s_hideCount": 2,
                    "s_showCount": 2,
                    "s_visitDepth": 4,
                    "s_stayTime": 14,
                    "s_entryPagePath": "pages/index/index",
                    "s_exitPagePath": "pages/index/index",
                    "s_originScene": 1005
                }
            }
        }
    ]
}

HTTP Request

POST https://cdp-api.linkflowtech.com/open/messages

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Request Body

Parameter	Required	Default	Type	Description
request_id	false		String	随机uuid
channelKey	true		String	渠道id
channelType	false	UDC	String	渠道类型，UDC、TTMP或WECHAT_WXA
messages	true		List	联系人、事件或渠道账号数据
identities	true		List	身份识别数据

messages

Parameter	Required	Type	Description
message_id	false	String	随机uuid
domain	true	String	contact/event/identity
action	true	String	当domain=contact或identity时，固定为set; 当domain=event时，固定为track
ts	true	String	当前时间戳
data	true	Object	具体联系人、事件或渠道账号数据

当 domain=identity 时，用于为当前识别到的联系人绑定当前渠道下的渠道账号。data.id 为要绑定的渠道账号 ID，必填

identities

Parameter	Required	Default	Type	Description
id	true		String	身份id
type	true		String	身份类型

查询联系人

GET /open/identity/contact?idType=idCard&id=321100199012203412 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，存在返回联系人id，不存在返回null

HTTP/1.1 200 OK
703941987164160

HTTP Request

GET https://cdp-api.linkflowtech.com/open/identity/contact

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Request Parameters

Parameter	Required	Default	Type	Description
id	true		String	身份id
idType	true		String	身份类型

Error Code

HTTP Status Code	Parameter	Description
500	B00010	参数不合法

根据联系人查询渠道账号

GET /open/contacts/703941987164160/channel_identities HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，返回渠道账号列表，示例如下

HTTP/1.1 200 OK
[
    {
        "dateCreated": "2022-05-23 11:27:08",
        "lastUpdated": "2022-05-23 11:27:08",
        "ver": 2,
        "id": 140992033742850,
        "contactId": 703941987164160,
        "channelId": 140926029029409,
        "isActive": true,
        "externalId": "wmbbj8CwAA6LB80PlgbjpHyzUGrupa9g",
        "channel": {
            "dateCreated": "2022-07-19 09:53:24",
            "lastUpdated": "2022-10-21 16:06:52",
            "ver": 55,
            "id": 140926029029409,
            "channelId": "ww0b8772cfc1ed757c",
            "channelType": "WORKWECHAT_PRO",
            "name": "钢铁侠",
            "status": "ACTIVE",
            "propertyVersion": "0",
            "tenantId": 1,
            "orgId": "1"
        }
    },
    {
        "dateCreated": "2022-05-23 11:27:08",
        "lastUpdated": "2022-05-23 11:27:08",
        "ver": 2,
        "id": 140992033873922,
        "contactId": 703941987164160,
        "channelId": 140879002099713,
        "isActive": true,
        "channel": {
            "dateCreated": "2022-05-13 11:54:24",
            "lastUpdated": "2022-08-30 11:56:10",
            "ver": 5,
            "id": 140879002099713,
            "channelId": "wx13b37f13976645ac",
            "channelType": "WECHAT",
            "name": "Linkflow体验账号",
            "status": "ACTIVE",
            "propertyVersion": "0",
            "tenantId": 1,
            "orgId": "1"
        }
    }
]

HTTP Request

GET https://cdp-api.linkflowtech.com/open/contacts/{id}/channel_identities

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Path Parameters

Parameter	Required	Default	Type	Description
id	true		Long	联系人id

查询企业微信联系我二维码

GET /open/workwechat/ww0b8772cfc1ed757c/qrcodes HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，返回联系我二维码列表，示例如下

HTTP/1.1 200 OK
[
    {
        "dateCreated": "2022-07-19 10:43:41",
        "lastUpdated": "2022-09-06 09:57:16",
        "id": 2,
        "configId": "7c4028ec8fc99597bf28cc8791f9aa71",
        "qrCode": "https://wework.qpic.cn/wwpic/8350_c_NNsuGtQQyhaO4_1658198622/0",
        "tenantId": 1,
        "channelId": 140926029029409,
        "utm": {
            "source": "新建来源",
            "campaign": "新建活动",
            "term": "新建关键字"
        },
        "contactWay": {
            "remark": "添加单人",
            "type": "SINGLE"
        },
        "isSetWelcomeMessage": false,
        "workWechatWelcomeMessageId": 17
    },
    {
        "dateCreated": "2022-08-26 16:07:51",
        "lastUpdated": "2022-08-26 16:07:51",
        "id": 3,
        "configId": "6e49729729d83fc67ef9cb91715ba14b",
        "qrCode": "https://wework.qpic.cn/wwpic/493891_tr12MGgQTES9Nfs_1661501271/0",
        "tenantId": 1,
        "channelId": 140926029029409,
        "utm": {
            "source": "",
            "campaign": "",
            "term": ""
        },
        "contactWay": {
            "remark": "11",
            "type": "SINGLE"
        },
        "isSetWelcomeMessage": false
    },
    {
        "dateCreated": "2022-08-26 16:08:57",
        "lastUpdated": "2022-08-26 16:08:58",
        "id": 4,
        "configId": "f85c9c5306431e9697ed545b73fbda75",
        "qrCode": "https://wework.qpic.cn/wwpic/669369_Du9K4uucRRylYMG_1661501337/0",
        "tenantId": 1,
        "channelId": 140926029029409,
        "utm": {
            "source": "123",
            "campaign": "456",
            "term": "789"
        },
        "contactWay": {
            "remark": "22",
            "type": "SINGLE"
        },
        "isSetWelcomeMessage": false
    },
    {
        "dateCreated": "2022-09-05 14:29:40",
        "lastUpdated": "2022-09-05 14:30:42",
        "id": 5,
        "configId": "9b8030360ccf225d3b4384d54d534a15",
        "qrCode": "https://wework.qpic.cn/wwpic/343776_tKQhZjgNRFabtTA_1662359381/0",
        "tenantId": 1,
        "channelId": 140926029029409,
        "utm": {
            "source": "",
            "campaign": "",
            "term": ""
        },
        "contactWay": {
            "remark": "测试二维码欢迎语",
            "type": "SINGLE"
        },
        "isSetWelcomeMessage": true,
        "workWechatWelcomeMessageId": 10
    }
]

HTTP Request

GET https://cdp-api.linkflowtech.com/open/workwechat/{channelId}/qrcodes

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Path Parameters

Parameter	Required	Default	Type	Description
channelId	true		String	企业微信渠道id

HTTP Status Code	Parameter	Description
500	B00022	渠道不存在

创建/更新订单订单

POST /open/messages/orders HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，返回200状态码及成功消息

HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": "0",
    "message": "ok"
}

请求示例如下：

{
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "channelKey": "udc_12SyQfFmg",
    "channelType": "UDC",
    "identities": [
        {
            "id": "321100199012203412",
            "type": "idCard"
        },
        {
            "id": "email@163.com",
            "type": "email"
        }
    ],
    "messages": [
        {
            "message_id": "{随机uuid}",
            "domain": "salesOrder",
            "action": "set",
            "ts": 1663146117310,
            "data": {
              "saleChannel": "有赞",
              "orderId": "E20221028",
              "orderStatus": "TRADE_CLOSED",
              "orderSource": "other",
              "payType": "优惠兑换",
              "payDate": "2022-10-28 10:33:45",
              "orderDate": "2022-10-28 10:33:44",
              "totalPrice": 100.240,
              "paymentPrice": 0,
              "refundPrice": 0,
              "successDate": "2022-10-28 10:33:45",
              "cancelDate": "2022-10-28 10:33:45",
              "cancelType": "2",
              "storeName": "微商城",
              "storeId": "111111",
              "paymentId": "1",
              "receiverName": "1",
              "deliveryProvince": "吉林省",
              "deliveryCity": "四平市",
              "deliveryDistrict": "梨树县",
              "deliveryAddress": "1",
              "receiverMobile": "12345678901",
              "totalQuantity": 1,
              "orderType": "普通订单",
              "isPresale": "是",
              "presaleStatus": "XXX",
              "isMemberOrder": "是",
              "storeCardUsed": 100,
              "deliveryDate": "2022-10-28 10:33:45",
              "guideCode": "1A2S3D",
              "props":{
                "test_date":"2022-10-28 10:33:45"
              },
              "lines": [
                {
                  "lineId": "L20221028",
                  "orderDate": "2022-10-28 10:33:44",
                  "itemTotalPrice": 0,
                  "itemPaymentPrice": 0,
                  "quantity": 2,
                  "refundQuantity": 0,
                  "refundPrice": 0.000,
                  "brandName": "1",
                  "category": "1",
                  "productName": "维生素C",
                  "productAlias": "111111",
                  "itemId": "111111",
                  "itemNo": "1",
                  "outerItemNo": "1",
                  "price": 50.12,
                  "skuName": "数量:1瓶",
                  "skuId": "1",
                  "skuNo": "1",
                  "isPresent": "false",
                  "refundType": "退款-商家主动退款",
                  "refundStatus": "退货退款",
                  "lineStatus": "退货退款",
                  "categoryId": "123",
                  "itemMealId": "123",
                  "itemMealName": "111111",
                  "isEstimate": "是",
                  "outerItemId":"100000000",
                  "outerSkuName":"中份",
                  "outerSkuId":"100000001",
                  "outerSkuNo":"100000000",
                  "deliveryDate":"2022-10-28 10:33:45",
                  "props":{
                    "test_number": 100.12
                  }
                }
              ]
            }
        }
    ]
}

HTTP Request

POST https://cdp-api.linkflowtech.com/open/messages/orders

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Request Body

Parameter	Required	Default	Type	Description
request_id	false		String	随机uuid
channelKey	true		String	渠道id
channelType	false	UDC	String	渠道类型，UDC、YOUZAN、YOUZANSELF
messages	true		List	联系人或事件数据
identities	true		List	身份识别数据

messages

Parameter	Required	Type	Description
message_id	false	String	随机uuid
domain	true	String	salesOrder
action	true	String	值固定为set
ts	true	String	当前时间戳
data	true	Object	具体订单数据

data - salesOrderHead

Parameter	Required	Type	Description
saleChannel	true(创建时必填)	String	订单销售渠道: 天猫、有赞、微盟等
orderId	true	String	订单号
orderStatus	true(创建时必填)	String	订单状态：见有赞渠道状态映射及系统订单状态码
orderSource	false	String	订单来源:小程序、公众号等
payType	false	String	支付方式:支付宝，微信等
payDate	false	DateTime	订单支付时间
orderDate	true	DateTime	订单创建时间
totalPrice	false	BigDecimal	订单总金额
paymentPrice	false	BigDecimal	订单实付金额
refundPrice	false	BigDecimal	退款金额
successDate	false	DateTime	订单完成时间
cancelDate	false	DateTime	订单关闭时间
cancelType	false	String	订单关闭类型
storeName	false	String	店铺名称
storeId	false	String	店铺ID
paymentId	false	String	支付流水号
receiverName	false	String	收货人姓名
deliveryProvince	false	String	收货人所在省份
deliveryCity	false	String	收货人所在城市
deliveryDistrict	false	String	收货人所在地区
deliveryAddress	false	String	收货人详细地址
receiverMobile	false	String	收货人手机号
totalQuantity	false	String	商品总数
orderType	false	String	订单类型
isPresale	false	String	是否预售
presaleStatus	false	String	预售订单状态
isMemberOrder	false	String	是否会员单
storeCardUsed	false	Integer	使用购物金
deliveryDate	false	DateTime	订单发货时间
guideCode	false	String	订单对应导购
props	false	Map	订单头自定义属性

data - salesOrderLine

Parameter	Required	Type	Description
lineId	true	String	订单行ID
orderDate	false	DateTime	订单创建时间
itemTotalPrice	false	BigDecimal	商品总价
itemPaymentPrice	false	BigDecimal	商品实付金额
quantity	false	Integer	数量
refundQuantity	false	Integer	退货数量
refundPrice	false	BigDecimal	退款金额
brandName	false	String	品牌
category	false	String	品类
productName	false	String	商品名称
productAlias	false	String	商品别名
itemId	false	String	商品ID
itemNo	false	String	商品编码
outerItemNo	false	String	平台商品编码
price	false	BigDecimal	商品单价
skuName	false	String	sku名称
skuId	false	String	skuId
skuNo	false	String	sku编码
isPresent	false	String	是否赠品
refundType	false	String	退款类型
refundStatus	false	String	退款状态
lineStatus	false	String	子订单状态
categoryId	false	String	品类ID
itemMealId	false	String	套餐ID
itemMealName	false	String	套餐名称
isEstimate	false	String	是否评价
outerItemId	false	String	平台商品ID
outerSkuName	false	String	平台sku名称
outerSkuId	false	String	平台skuId
outerSkuNo	false	String	平台sku编码
deliveryDate	false	DateTime	子订单发货时间
props	false	Map	订单行自定义属性

identities

Parameter	Required	Default	Type	Description
id	true		String	身份id
type	true		String	身份类型

有赞订单状态映射

YouZan Order Code	System Order Status Code
WAIT_BUYER_PAY	WAIT_BUYER_PAY
TRADE_PAID	WAIT_SELLER_SEND_GOODS
WAIT_CONFIRM	WAIT_SELLER_SEND_GOODS
WAIT_SELLER_SEND_GOODS	WAIT_SELLER_SEND_GOODS
WAIT_BUYER_CONFIRM_GOODS	WAIT_BUYER_CONFIRM_GOODS
TRADE_SUCCESS	TRADE_SUCCESS
TRADE_CLOSED	TRADE_CLOSED
其他状态	OTHER

系统订单状态码

System Order Status Code	Description
WAIT_BUYER_PAY	待支付
WAIT_SELLER_SEND_GOODS	待发货
SELLER_CONSIGNED_PART	部分发货
WAIT_BUYER_CONFIRM_GOODS	已发货
WAIT_BUYER_CONFIRM_PAY	已发货未付款
TRADE_BUYER_SIGNED	已签收
TRADE_SUCCESS	订单完成
TRADE_CLOSED	订单关闭
TRADE_CLOSED_ALL_REFUND	全额退款交易关闭
TRADE_CLOSED_PARTIAL_REFUND	部分退款
PAID_FORBID_CONSIGN	禁止发货
OTHER	其他

同步创建联系人和事件

使用与“创建联系人和事件”完全相同的请求体，但会同步处理并返回结果。需要立即获知数据校验或处理失败时使用本接口；普通 POST /open/messages 仅提交到异步处理链路，成功响应不代表后续数据已落库。

POST /open/messages/sync HTTP/1.1
Accept: application/json
Content-Type: application/json
X-OpenApi-Token: Access Token

HTTP Request

POST https://cdp-api.linkflowtech.com/open/messages/sync

响应成功时为 { "code": "0", "message": "ok" }。请求体字段、domain 和 action 约束与前述“创建联系人和事件”接口一致。

游标获取事件

按 extraId 升序拉取事件。下一次请求传入本批结果中最大的 extraId；返回空数组表示已读取完毕。单次 size 最大为 1000。

GET /open/events/cursor?lastMaxExtraId=0&size=200 HTTP/1.1
Accept: application/json
X-OpenApi-Token: Access Token

HTTP Request

GET https://cdp-api.linkflowtech.com/open/events/cursor

Querystring parameters

Parameter	Required	Default	Type	Description
lastMaxExtraId	false	0	Long	上一批最大 `extraId`；首次请求传 `0`
size	false	200	Integer	返回数量，最大 1000

Response

[
  {
    "extraId": 1001,
    "eventDate": 1663146117310,
    "contactId": 29,
    "channelId": 63,
    "channelName": "官网",
    "event": "page_view",
    "props": { "path": "/home" }
  }
]

事件还可能包含 context、sdkVersion、sdkType、platform、设备与地理位置字段、utm、parentId 和 items。eventDate 为毫秒时间戳。

Parameter	Required	Type	Description
tagKey	true	String	标签key，唯一识别标识，需要以tag_开头，只包含：小写字母、数字、下划线
tagName	true	String	标签显示名
dataType	true	String	标签值数据类型，枚举值，只支持传入text、number、array、datetime、boolean
tagType	true	String	只支持传"UPLOAD"
identityType	true	String	用户身份类型，如：phone、email、wechat.unionid
channelId	true	String	当用户身份类型为externalId时，需要传channelId（连接的数值型id）

Error Code

HTTP Status Code	Parameter	Description
500	B00002	必填参数为空
500	B00010	参数不合法
500	B00159	channelId不存在
500	B00037	标签超过配额数
500	B01157	key不符合tag_开头，只包含：小写字母、数字、下划线
500	B01151	标签已经存在

删除用户标签元数据

DELETE /v1/tags/tagkeys/{tagKey} HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，返回200状态码及成功消息，示例如下

HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": "0",
    "message": "ok"
}

HTTP Request

DELETE https://cdp-api.linkflowtech.com/v1/tags/tagkeys/{tagKey}

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Request Parameters

Parameter	Required	Default	Type	Description
tagKey	true		String	标签key，唯一识别标识，需要以tag_开头，只包含：小写字母、数字、下划线

Error Code

HTTP Status Code	Parameter	Description
500	B00002	必填参数为空
500	B_01162	标签不存在

获取用户标签元数据列表

GET /v1/tags?size=1&page=0 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，系统会返回元数据列表，示例如下

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
      "tagId": 2,
      "tagKey": "tag_878",
      "tagName": "用户活跃度",
      "dataType": "text",
      "tagType": "UPLOAD",
      "status": "ACTIVE",
      "folderId": 56,
      "dateCreated": "2017-11-30 19:37:12",
      "lastUpdated": "2017-11-30 19:37:12",
      "lastCalculateTime":"2017-11-30 20:37:12",
  }
]

HTTP Request

GET https://cdp-api.linkflowtech.com/v1/tags?size=1&page=0

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Request Parameters

Parameter	Required	Default	Type	Description
page	true		integer	第几页，从0开始
size	true		integer	每页条数，限制200条

tagType 标签类型

tagType	Description
RULE_LAYER	自定义分层
EVENT_PROPERTY_PREFERENCES	事件偏好
EVENT_INDICATOR	事件指标
FIRST_LAST_TIME	第N次特征
UPLOAD	导入
SQL	SQL创建
EMOTION	情感分析
ANNIVERSARY	纪念日
TIME_INTERVAL	间隔标签
WEIGHT	权重标签
RFM	RFM标签
SALES_ORDER	订单
CLV	CLV预测标签
ORDER_PROPERTY_PREFERENCES	订单偏好
CUSTOMIZED_PREDICT	自定义预测
LIFE_CYCLE	生命周期
SELF_DEFINE_INDICATOR	指标标签

Error Code

HTTP Status Code	Parameter	Description
500	B00010	参数不合法

获取标签目录列表

GET /open/folders HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，系统会返回标签目录列表，示例如下

HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "id": 175,
        "name": "测试目录名称",
        "domain": "TAG",
        "parentId": 174,
        "dateCreated": "2024-11-08 15:03:10",
        "lastUpdated": "2024-11-08 15:03:10"
    }
]

HTTP Request

GET https://cdp-api.linkflowtech.com/open/folders

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

上传用户标签值文件

POST /v1/tags/tagkeys/{tagKey}/upload/file/operates/{operate} HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，系统会返回上传文件结果消息体，示例如下

HTTP/1.1 200 OK
Content-Type: application/json
{
    "tagKey":"tag_878",
    "fileName": "tag_878_file1",
    "ossUrl": "https://devtest.leadswarp.com/oss/1/tag/upload/tmp/20220321/7216b1262f184413bb529701a060eba9/ef00c630b0bb4f90a10de9e5bfcd7194"
}

HTTP Request

POST https://cdp-api.linkflowtech.com/v1/tags/tagkeys/{tagKey}/upload/file/operates/{operate}

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Request Parameters

Parameter	Required	Type	Description
tagKey	true	String	标签key，唯一识别标识，需要以tag_开头，只包含：小写字母、数字、下划线
operate	true	String	overwrite覆盖，即删除标签元数据中已有的文件，用新上传的文件代替,append：追加，即保留标签元数据中已有的文件，并新增新上传的文件
file	true	MultipartFile	上传的文件，文件大小限制在100M内；请求必须使用 `multipart/form-data`

Error Code

HTTP Status Code	Parameter	Description
500	B01163	文件大小超过100M
500	B00010	参数不合法
500	B01162	tagKey不存在

发起计算用户标签值任务

POST /v1/tags/tagkeys/{tagKey}/calculate HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，系统会返回200及成功消息，示例如下

HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": "0",
    "message": "ok"
}

HTTP Request

POST https://cdp-api.linkflowtech.com/v1/tags/tagkeys/{tagKey}/calculate

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Request Parameters

Parameter	Required	Default	Type	Description
tagKey	true		String	标签key，唯一识别标识，需要以tag_开头，只包含：小写字母、数字、下划线

Error Code

HTTP Status Code	Parameter	Description
500	B01162	tagKey不存在
500	B01152	任务计算状态不对,只有FINISH, ERROR, CALC_ERROR允许重新计算
500	B01165	标签不是启用状态不可以进行重新计算

生成用户标签值文件

POST /v1/tags/tagkeys/{tagKey}/export HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token
{
  "identityType": "externalId",
  "channelId": "111"
}

在提交请求之后，系统会返回创建任务消息体，示例如下

HTTP/1.1 200 OK
Content-Type: application/json
{
  "tagKey":"tag_sf",
  "taskId":19723653547885,
  "status":"INITIAL"
}

HTTP Request

POST https://cdp-api.linkflowtech.com/v1/tags/tagkeys/{tagKey}/export

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Request Parameters

Parameter	Required	Type	Description
tagKey	true	String	标签key，唯一识别标识，需要以tag_开头，只包含：小写字母、数字、下划线
identityType	true	String	用户识别标识类型
channelId	如果identity_type为externalId，则为必填	String	自定义连接id（连接的数值型id）

Error Code

HTTP Status Code	Parameter	Description
500	B00002	必填参数为空
500	B00010	参数不合法
500	B01162	tagKey不存在
500	B00159	channelId不存在

获取用户标签值文件下载地址

GET /v1/tags/tagkeys/export/{taskId} HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，系统会返回文件下载地址，示例如下

HTTP/1.1 200 OK
Content-Type: application/json
{
    "taskId": 19723653547885,
    "status": "FINISH",
    "errorMsg": "",
    "fileUrl": ""
}

HTTP Request

GET https://cdp-api.linkflowtech.com/v1/tags/tagkeys/export/{taskId}

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Request Parameters

Parameter	Required	Default	Type	Description
taskId	true		Long	生成标签文件任务id

批量修改标签值

POST /v1/tags/value HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

请求示例如下：

{
   "identity":{
        "id":"18888888888",
        "type":"mobilePhone"
   },
   "actions":[
    {
        "tagId":382,
        "action":"delete"
    },
    {
        "tagId":383,
        "value":"红色,蓝色",
        "action":"set"
    }]
}

在提交请求之后，系统会返回200及成功消息，示例如下

HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": "0",
    "message": "ok"
}

HTTP Request

POST https://cdp-api.linkflowtech.com/v1/tags/value

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

RequestBody

Parameter	Required	Default	Type	Description
identity	true		Object	身份
actions	true		List	标签操作列表，单次最多 50 条

Identity

Parameter	Required	Default	Type	Description
id	true		String	身份id
type	true		String	身份类型

Action

Parameter	Required	Type	Description
tagId	true	Long	标签id，仅支持导入标签，其他标签类型不处理
value	条件必填	String	`action` 为 `set` 时必填；多个值使用逗号分隔。`delete` 时不传该字段
action	true	String	`set`：设置值；`delete`：删除该标签值

Error Code

HTTP Status Code	Parameter	Description
400	B00031	列表超过最大数量
400	B01376	身份不存在

维度表

维度表数据上传

POST /open/dim/{dimensionId}/data HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

单次仅支持上传至多1000条数据。

在提交请求之后，系统成功上传数据后，返回200状态码及成功消息 ```http HTTP/1.1 200 OK Content-Type: application/json

{ "code": "0", "message": "ok" } ```

请求示例如下：

[
    {
        "id":"1",
        "color":"红色"
    },
    {
        "id":"2",
        "color":"红色"
    },
    {
        "id":"3",
        "color":"红色"
    }

]

HTTP Request

POST https://cdp-api.linkflowtech.com/open/dim/{dimensionId}/data

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Path Parameters

Parameter	Required	Default	Type	Description
dimensionId	true	-	String	维度表alias

Error Code

HTTP Status Code	Parameter	Description
500	B01206	上传数量超过限制
500	B00043	维度表不存在
500	B01201	维度表无主键
500	B01205	数据结点不包含主键列

联系人

获取联系人列表

GET /open/contacts?size=1&page=0&groupId=1&search=13774202819 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，系统会返回一个JSON数组，里面包含了所有符合条件的联系人，示例如下

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "anonymousId": null,
        "name": "peter pan",
        "nickname": null,
        "gender": "unknown",
        "dateOfBirthday": null,
        "avatar": null,
        "mobilePhone": "13774202819",
        "homePhone": null,
        "email": null,
        "country": null,
        "state": null,
        "street": null,
        "city": null,
        "postalCode": null,
        "comments": null,
        "userName": null,
        "title": null,
        "website": null,
        "company": null,
        "industry": null,
        "department": null,
        "idCard": null,
        "utm": {
            "source": "source",
            "campaign": "campaign",
            "medium": "medium",
            "content": "content",
            "term": "term"
        },
        "props": {
            "attr1": "单身",
            "attr2": 10000
        },
        "isAnonymous": false,
        "id": 2865,
        "dateCreated": "2017-08-22 13:50:51",
        "lastUpdated": "2017-08-22 13:50:51"
    }
]

HTTP Request

GET https://cdp-api.linkflowtech.com/open/contacts

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Querystring parameters

Parameter	Required	Default	Type	Description
page	false	0	Integer	第几页，从0开始
size	false	200	Integer	每页条数
groupId	false		Long	联系人所在的组，不填写时查询全部联系人
search	false		String	搜索关键词

更新联系人

使用联系人 ID 更新联系人字段。请求体中的 id 会被忽略，以路径中的 id 为准；只传需要更新的字段。props 为自定义属性键值对，utm 为来源信息对象。系统字段（例如创建时间、租户等）不会被此接口更新。

PUT /open/contacts/{id} HTTP/1.1
Accept: application/json
Content-Type: application/json
X-OpenApi-Token: Access Token

{
  "name": "peter pan",
  "mobilePhone": "13774202819",
  "props": {
    "member_level": "gold"
  }
}

HTTP Request

PUT https://cdp-api.linkflowtech.com/open/contacts/{id}

Path Parameters

Parameter	Required	Type	Description
id	true	Long	要更新的联系人 ID

Request Body

Parameter	Required	Type	Description
name, nickname, mobilePhone, email, gender, company 等	false	String	联系人标准属性；未传字段不作为更新目标
dateOfBirthday	false	String	出生日期，使用系统支持的日期格式
utm	false	Object	`source`、`campaign`、`medium`、`content`、`term` 等来源字段
props	false	Object	自定义联系人属性；键必须是已配置的联系人属性 alias

响应为更新后的联系人对象；联系人不存在时响应体为 null。

游标方式获取联系人

GET /open/contacts/cursor?lastMaxId=0&size=200 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，系统会返回一个JSON数组，里面包含了所有符合条件的联系人，示例如下

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "anonymousId": null,
        "name": "peter pan",
        "nickname": null,
        "gender": "unknown",
        "dateOfBirthday": null,
        "avatar": null,
        "mobilePhone": "13774202819",
        "homePhone": null,
        "email": null,
        "country": null,
        "state": null,
        "street": null,
        "city": null,
        "postalCode": null,
        "comments": null,
        "userName": null,
        "title": null,
        "website": null,
        "company": null,
        "industry": null,
        "department": null,
        "idCard": null,
        "utm": {
            "source": "source",
            "campaign": "campaign",
            "medium": "medium",
            "content": "content",
            "term": "term"
        },
        "props": {
            "attr1": "单身",
            "attr2": 10000
        },
        "isAnonymous": false,
        "id": 2865,
        "dateCreated": "2017-08-22 13:50:51",
        "lastUpdated": "2017-08-22 13:50:51"
    }
]

HTTP Request

GET https://cdp-api.linkflowtech.com/open/contacts/cursor

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Querystring parameters

Parameter	Required	Default	Type	Description
lastMaxId	true		Long	上一次返回的联系人列表的最大id，第一次传0
size	false	200	Integer	返回联系人数量

批量获取联系人ID

第三方通过该接口，按照更新时间查询符合特定条件的联系人ID列表。

GET /open/contacts_bulk/ids?page=0&size=5&minUpdateTime=2017-01-01&maxUpdateTime=2018-01-01 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，系统会返回一个符合条件的联系人ID数组，示例如下

HTTP/1.1 200 OK
Content-Type: application/json

[
    1,
    3,
    5,
    7,
    8
]

HTTP Request

GET https://cdp-api.linkflowtech.com/open/contacts_bulk/ids

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Querystring parameters

Parameter	Required	Default	Type	Description
page	true	-	number	第几页，从0开始
size	true	-	number	每页条数注：page*size<=10000
maxUpdateTime	false	-	Date	最大更新时间，格式 `yyyy-MM-dd`，包含该日期全天
minUpdateTime	false	-	Date	最小更新时间，格式 `yyyy-MM-dd`，包含该日期的数据
anonymous	false	0	number	-1：全量；0：实名；1：匿名

Error Code

HTTP Status Code	Parameter	Description
420	B00030	page*size必须小于等于10000

批量获取联系人详情

第三方通过该接口，通过联系人contactId列表获取联系人详情数据。最多支持一次拉取100条。

GET /open/contacts_bulk?ids=1,3,5,7,8&needOpenId=1 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，系统会返回一个JSON数组，里面包含了所有符合条件的联系人，示例如下

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 1,
        "dateCreated": "2017-07-19 20:00:57",
        "lastUpdated": "2017-08-04 12:00:00",
        "ver": null,
        "anonymousId": null,
        "name": "康熙",
        "nickname": "康熙",
        "gender": "male",
        "dateOfBirthday": "1991-11-11 00:00:00",
        "avatar": null,
        "profilePhoto": null,
        "mobilePhone": "13888888888",
        "homePhone": "025-83729999",
        "email": "test@nazaio.com",
        "country": "中国",
        "state": "江苏",
        "street": "雨花",
        "city": "南京",
        "postalCode": "210000",
        "comments": "备注",
        "userName": null,
        "title": "java",
        "website": "https://www.linkflowtech.com/",
        "company": "上海源犀信息科技有限公司",
        "industry": "IT",
        "department": "研发",
        "idCard": null,
        "utm": {
            "source": "source",
            "campaign": "campaign",
            "medium": "medium",
            "content": "content",
            "term": "term"
        },
        "props": {
            "attr1": "单身",
            "attr2": 10000
        },
        "isAnonymous": false,
        "openIds": [
            {
                "channelId": "wx5a39a02868a39999",
                "channelName": "渠道名称A",
                "openId": "olbUb0gzPm0Z1eDkEhvq_Ieoqfa"
            },
            {
                "channelId": "wxaceb2577e5f99999",
                "channelName": "渠道名称B",
                "openId": "olbUb0gzPm0Z1eDkEhvq_NaWOzSc"
            }
        ]
    },
    {
        "id": 3,
        "dateCreated": "2017-03-29 16:16:57",
        "lastUpdated": "2017-03-29 16:16:57",
        "ver": null,
        "anonymousId": "olbUb0gzPm0Z1eDkEhvq_NaWOzSc",
        "name": "Kyle Lee",
        "nickname": "Kyle Lee",
        "gender": "male",
        "dateOfBirthday": null,
        "avatar": "http://wx.qlogo.cn/mmopen/UOlZKghBxaY81Ynib8fuQyRIJpyJQpIuGNONH6DLicqOdE8uskPI8KYbn1aUdnA0kPkhCfVV4m80c1z6Lh9bmu7w/0",
        "profilePhoto": null,
        "mobilePhone": null,
        "homePhone": null,
        "email": "bb@nazaio.com",
        "country": "中国",
        "state": "广东",
        "street": null,
        "city": "广州",
        "postalCode": null,
        "comments": "",
        "userName": null,
        "title": null,
        "website": null,
        "company": null,
        "industry": null,
        "department": null,
        "idCard": null,
        "utm": {
            "source": "source",
            "campaign": "campaign",
            "medium": "medium",
            "content": "content",
            "term": "term"
        },
        "props": {
            "attr1": "已婚",
            "attr2": 18000
        },
        "isAnonymous": false,
        "openIds": [
            {
                "channelId": "wx5a39a02868a39316",
                "channelName": "打头哇万",
                "openId": "olbUb0gzPm0Z1eDkEhvq_111"
            },
            {
                "channelId": "wxaceb2577e5f98632",
                "channelName": "联否Linkflow",
                "openId": "olbUb0gzPm0Z1eDkEhvq_NaWOzSc"
            }
        ]
    },
    {
        "id": 5,
        "dateCreated": "2017-03-29 22:37:22",
        "lastUpdated": "2017-03-29 22:37:22",
        "ver": null,
        "anonymousId": "olbUb0q01JkL55FwJxVpuA1f3suk",
        "name": "Alpha",
        "nickname": "Alpha",
        "gender": "male",
        "dateOfBirthday": null,
        "avatar": "http://wx.qlogo.cn/mmopen/PiajxSqBRaEKZJSIIapCZUPDAG7quD6y3WkvTVlMLibTHlYaV6IuiaeEaw3Se5DraR73bXN0PGUia8kekibmDgdkVHw/0",
        "profilePhoto": null,
        "mobilePhone": null,
        "homePhone": null,
        "email": "cc@nazaio.com",
        "country": "中国",
        "state": "江苏",
        "street": null,
        "city": "南京",
        "postalCode": null,
        "comments": "",
        "userName": null,
        "title": null,
        "website": null,
        "company": null,
        "industry": null,
        "department": null,
        "idCard": null,
        "utm": {
            "source": "source",
            "campaign": "campaign",
            "medium": "medium",
            "content": "content",
            "term": "term"
        },
        "props": {
            "attr1": "已婚",
            "attr2": 20000
        },
        "isAnonymous": false,
        "openIds": [
            {
                "channelId": "wxaceb2577e5f0000",
                "channelName": "渠道名称A",
                "openId": "olbUb0q01JkL55FwJxVpuA1f3suk"
            }
        ]
    }
]

HTTP Request

GET https://cdp-api.linkflowtech.com/open/contacts_bulk

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Querystring parameters

Parameter	Required	Default	Type	Description
ids	true	-	List	联系人id数组,每次传入的id个数不能超过100个,如超过则只取前100个id的数据
needOpenId	false	-	String	是否获取联系人的openid。1为获取，不填则默认为不需要获取。

获取联系人所有的身份信息

POST /open/contacts/identities HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token
{
    "identity":{
        "id":"13888888888",
        "type":"phone"

    },
    "identityTypes":[
        "idcard",
        "email"
    ]
}

在提交请求之后，系统会返回联系人ID和所有符合条件的联系身份结果，示例如下

HTTP/1.1 200 OK
Content-Type: application/json

{
    "contactId": 29,
    "identities": [
        {
            "id": "123456@qq.com",
            "type": "email",
            "dateCreated": "2023-02-20 15:47:30"
        }
    ]
}

HTTP Request

POST https://cdp-api.linkflowtech.com/open/contacts/identities

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Request Body

Parameter	Required	Default	Type	Description
identity	true		Object	联系人身份
identityTypes	false		List	身份类型

identity

Parameter	Required	Default	Type	Description
id	true		String	身份id
type	true		String	身份类型

identityTypes

Parameter	Required	Default	Type	Description
type	false		String	身份类型

获取联系人标签值

POST /open/contacts/tags HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token
{
    "id":"13888888888",
    "type":"phone"
}

在提交请求之后，系统会返回联系人标签值结果，示例如下

HTTP/1.1 200 OK
Content-Type: application/json

[
 {
     "tagId": 1,
     "tagName": "性别",
     "tagKey": "tag_yhxb",
     "value": "男"
 }
]

HTTP Request

POST https://cdp-api.linkflowtech.com/open/contacts/tags

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Request Body

Parameter	Required	Default	Type	Description
id	true		String	身份id
type	true		String	身份类型

解绑用户身份

DELETE open/contacts/identities/unbind  HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token
{
    "contactId": 29,
    "identities": [
        {
            "id": "17624321576",
            "type": "mobilePhone"
        }
    ]
}

在提交请求之后，系统成功解绑身份后，返回200状态码及成功消息

HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": "0",
    "message": "ok"
}

HTTP Request

DELETE https://cdp-api.linkflowtech.com/open/contacts/identities/unbind

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Request Body

Parameter	Required	Default	Type	Description
contactId	true		String	用户id
identities	true		Identity	身份列表

Identity

Parameter	Required	Default	Type	Description
id	true		String	身份id
type	true		String	身份类型。仅支持自定义身份及mobilePhone，wechat.unionId, wechat.openId, wxa.openId, workwechat.externalUserId

Error Code

HTTP Status Code	Parameter	Description
404	B00008	联系人id不存在
500	B01402	解绑后联系人身份数量小于1
500	B01403	身份类型不存在
500	B01404	身份类型不可解绑
500	B01405	身份值不存在

根据联系人ID查询身份

GET open/contacts/{id}/identities  HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，返回联系人身份列表

[
  {
    "id": "wmueeyBwAAaqpOpwAE4MHw3nZdch4ZSw",
    "type": "workwechat.externalUserId",
    "dateCreated": "2024-01-26 14:47:16"
  },
  {
    "id": "oIx981RYQX7_t__yOi53U9pzSjxE",
    "type": "wechat.unionId",
    "dateCreated": "2024-01-26 14:47:16"
  }
]

HTTP Request

GET https://cdp-api.linkflowtech.com/open/contacts/{id}/identities

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Error Code

HTTP Status Code	Parameter	Description
404	B00008	联系人id不存在

联系人属性元数据

获取联系人属性元数据

返回当前租户可用于联系人 props 的属性定义。创建或更新联系人前，先调用本接口确认自定义属性的 alias 和数据类型。

GET /v2/contacts/meta/properties?isSystem=false HTTP/1.1
Accept: application/json
X-OpenApi-Token: Access Token

HTTP Request

GET https://cdp-api.linkflowtech.com/v2/contacts/meta/properties

Querystring parameters

Parameter	Required	Default	Type	Description
isSystem	false	false	Boolean	是否返回系统属性；`false` 返回自定义属性，`true` 返回系统属性

Response

[
  {
    "id": 101,
    "label": "会员等级",
    "remark": "CRM 同步字段",
    "alias": "member_level",
    "pinyin": "huiyuan dengji",
    "dataType": "text"
  }
]

Field	Type	Description
id	Long	属性 ID
label	String	属性显示名称
remark	String	属性说明
alias	String	API 中 `props` 使用的键
pinyin	String	属性拼音
dataType	String	属性数据类型；写入 `props` 时应与之匹配

群组

查询群组

GET /open/groups?id=126&name=wechat&groupType=static&ext1=wx134210231&ext2=wechattagid HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，系统会返回一个JSON数组，里面包含了所有符合条件的群组，示例如下

HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "lastUpdated": "2017-12-07 16:59:38",
        "groupType": "static",
        "dateCreated": "2017-12-07 16:59:38",
        "name": "618潜在客户",
        "id": 47
    },
    {
        "lastUpdated": "2017-12-11 16:52:39",
        "groupType": "dynamic",
        "dateCreated": "2017-12-11 11:20:04",
        "name": "最近7天活跃客户",
        "id": 51
    }
]

最多返回2000条数据，超过上限请调整查询条件。

HTTP Request

GET https://cdp-api.linkflowtech.com/open/groups

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Querystring parameters

Parameter	Required	Default	Type	Description
id	false	null	Integer	群组id
name	false	null	String	群组名称(模糊查询)
groupType	false	null	String	static或dynamic
lastUpdated	false	null	DateTime	最小更新时间，格式 `yyyy-MM-dd HH:mm:ss`
ext1	false	null	String	微信appId
ext2	false	null	String	微信群组id

创建群组

POST /open/groups HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token
{
  "name" : "this-is-group-name",
  "groupType" : "static",
  "ext1" : "wechatappid",
  "ext2" : "wechattagid"
}

在提交请求之后，系统会返回刚创建的群组，示例如下

HTTP/1.1 200 OK
Content-Type: application/json
{
    "lastUpdated": "2018-06-25 14:58:22",
    "groupType": "static",
    "dateCreated": "2018-06-25 14:58:22",
    "name": "this-is-group-name",
    "id": 334
}

HTTP Request

POST https://cdp-api.linkflowtech.com/open/groups

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Request Parameters

Parameter	Required	Default	Type	Description
name	true	-	String	群组名称
groupType	false	static	String	默认为static，目前不能设置别的值
ext1	false	null	String	微信appId
ext2	false	null	String	微信群组id

Error Code

HTTP Status Code	Parameter	Description
400	B00001	群组已存在
412	B00157	群组数量已达到上限

修改群组名

POST /open/groups/{id}?name=this-is-group-name HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

仅支持单个修改。

在提交请求之后，系统成功修改群组名后，返回200状态码及成功消息

HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": "0",
    "message": "ok"
}

HTTP Request

POST https://cdp-api.linkflowtech.com/open/groups/{id}

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Path Parameters

Parameter	Required	Default	Type	Description
id	true	-	Long	群组id

Request Parameters

Parameter	Required	Default	Type	Description
name	true	-	String	群组名称

Error Code

HTTP Status Code	Parameter	Description
404	B00017	群组不存在或已删除
420	B01102	群组名已存在

删除群组

DELETE /open/groups/{id} HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

仅支持单个删除。

在提交请求之后，系统成功删除群组后，返回200状态码及成功消息

HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": "0",
    "message": "ok"
}

HTTP Request

DELETE https://cdp-api.linkflowtech.com/open/groups/{id}

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Path Parameters

Parameter	Required	Default	Type	Description
id	true	-	Long	群组id

Error Code

HTTP Status Code	Parameter	Description
404	B00017	群组不存在或已删除

查询联系人的群组

GET /open/contacts/{contactId}/groups?groupType=static HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，系统会返回联系人的群组，示例如下

HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "lastUpdated": "2017-12-07 16:59:38",
        "groupType": "static",
        "dateCreated": "2017-12-07 16:59:38",
        "name": "618潜在客户",
        "id": 47
    },
    {
        "lastUpdated": "2017-12-11 16:52:39",
        "groupType": "static",
        "dateCreated": "2017-12-11 11:20:04",
        "name": "关注用户",
        "id": 51
    }
]

HTTP Request

GET https://cdp-api.linkflowtech.com/open/contacts/{contactId}/groups

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Path Parameters

Parameter	Required	Default	Type	Description
contactId	true	-	Integer	联系人id

Request Parameters

Parameter	Required	Default	Type	Description
groupType	false	null	String	群组类型

Error Code

HTTP Status Code	Parameter	Description
404	B00008	联系人不存在

查询群组联系人

GET /open/groups/{groupId}/contacts?memberId=2346&size=500 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

在提交请求之后，系统会返回群组的联系人，示例如下

HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "lastUpdated": "2018-04-19 11:19:41",
        "dateCreated": "2018-04-19 11:19:41",
        "contact": {
            "mobilePhone": null,
            "name": "'非常满意'&*-^!@#$%{}[]\\|、\"\"「」【】",
            "id": 17771,
            "email": null
        },
        "contactGroupId": 252,
        "version": null,
        "memberId": 1243167
    },
    {
        "lastUpdated": "2018-04-19 14:54:53",
        "dateCreated": "2018-04-19 14:54:53",
        "contact": {
            "mobilePhone": null,
            "name": "tiger",
            "id": 17760,
            "email": null
        },
        "contactGroupId": 252,
        "version": null,
        "memberId": 1243184
    }
]

HTTP Request

GET https://cdp-api.linkflowtech.com/open/groups/{groupId}/contacts

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Path Parameters

Parameter	Required	Default	Type	Description
groupId	true	-	Integer	群组id

Querystring parameters

Parameter	Required	Default	Type	Description
memberId	false	0	Integer	起始memberId(不包含)
size	false	500	Integer	查询数量,最大值:500

Error Code

HTTP Status Code	Parameter	Description
400	B00031	size超过最大数量
404	B00008	群组不存在

添加群组联系人

POST /open/groups/{groupId}/contacts HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token
[
  17760, 17771, 17578
]

联系人数量不大于5000.

在提交请求之后，系统会返回加组结果，示例如下

HTTP/1.1 200 OK
Content-Type: application/json
{
    "success": [
        17760,
        17771,
        17578
    ],
    "failure": [],
    "group": {
        "lastUpdated": "2018-06-25 14:58:10",
        "groupType": "static",
        "dateCreated": "2018-06-25 10:15:46",
        "name": "双11vip客户",
        "id": 333
    }
}

单次最多 5000 个联系人 ID。当前接口返回的 failure 固定为空数组；调用方需要自行校验联系人 ID 的有效性，不能依赖该字段判断失败项。

HTTP Request

POST https://cdp-api.linkflowtech.com/open/groups/{groupId}/contacts

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Path Parameters

Parameter	Required	Default	Type	Description
groupId	true	-	Integer	群组id

RequestBody Parameters

Parameter	Required	Default	Type	Description
contactIds	true	-	List	联系人id列表

Error Code

HTTP Status Code	Parameter	Description
400	B00031	联系人超过最大数量
404	B00017	群组不存在或不是静态群组

删除群组联系人

DELETE /open/groups/{groupId}/contacts HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token
[
  17760, 17771, 17578
]

联系人数量不大于50.

在提交请求之后，系统会返回删组结果，示例如下

HTTP/1.1 200 OK
Content-Type: application/json
{
    "success": [
        17760,
        17771,
        17578
    ],
    "group": {
        "lastUpdated": "2018-06-25 14:58:10",
        "groupType": "static",
        "dateCreated": "2018-06-25 10:15:46",
        "name": "双11vip客户",
        "id": 333
    }
}

单次最多 50 个联系人 ID。响应只包含 group 和实际成功删除的 success，不返回 failure；无效或不在该群组内的 ID 不会单独报告。

HTTP Request

DELETE https://cdp-api.linkflowtech.com/open/groups/{groupId}/contacts

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Path Parameters

Parameter	Required	Default	Type	Description
groupId	true	-	Integer	群组id

RequestBody Parameters

Parameter	Required	Default	Type	Description
contactIds	true	-	List	联系人id列表

Error Code

HTTP Status Code	Parameter	Description
400	B00031	联系人超过最大数量
404	B00017	群组不存在或不是静态群组

订单

获取订单列表

GET /open/orders?lastMaxId=100 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

GET /open/orders?page=2&startTime=2023-01-01%2015%3A44%3A20&endTime=2024-03-16%2015%3A44%3A20 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

HTTP/1.1 200 OK

返回数据示例如下：

[
    {
        "dateCreated": "2023-03-16 15:48:41",
        "lastUpdated": "2023-03-16 15:48:41",
        "ver": 1,
        "id": 144357503180802,
        "props": {},
        "tenantId": 1,
        "saleChannel": "有赞",
        "channelId": 63,
        "contactId": 706402597617664,
        "orderId": "433",
        "orderStatus": "SELLER_CONSIGNED_PART",
        "orderOuterStatus": "SELLER_CONSIGNED_PART",
        "orderSource": "other",
        "payType": "优惠兑换",
        "payDate": "2022-11-28 10:33:45",
        "orderDate": "2022-11-28 10:33:44",
        "totalPrice": 100.240,
        "paymentPrice": 123.456,
        "refundPrice": 0.000,
        "successDate": "2022-11-28 10:33:45",
        "cancelDate": "2022-11-28 10:33:45",
        "cancelType": "2",
        "storeName": "微商城",
        "storeId": "111111",
        "paymentId": "1",
        "receiverName": "1",
        "deliveryProvince": "吉林省",
        "deliveryCity": "四平市",
        "deliveryDistrict": "梨树县222",
        "deliveryAddress": "1",
        "receiverMobile": "12345678901",
        "totalQuantity": 1,
        "orderType": "普通订单",
        "isPresale": "是",
        "presaleStatus": "XXX",
        "isMemberOrder": "是",
        "storeCardUsed": 100,
        "deliveryDate": "2022-11-28 10:33:45",
        "guideCode": "1A2S3D",
        "lines": [
            {
                "dateCreated": "2023-03-16 15:48:41",
                "lastUpdated": "2023-03-16 15:48:41",
                "ver": 1,
                "id": 144357503180803,
                "props": {},
                "tenantId": 1,
                "orderId": "433",
                "lineId": "L202210ddzda28",
                "saleChannel": "有赞",
                "channelId": 63,
                "contactId": 706402597617664,
                "orderDate": "2022-11-28 10:33:44",
                "itemTotalPrice": 0.000,
                "itemPaymentPrice": 0.000,
                "quantity": 2,
                "refundQuantity": 0,
                "refundPrice": 92.000,
                "brandName": "1",
                "category": "1",
                "productName": "维生素C1",
                "productAlias": "111111",
                "itemId": "111111",
                "itemNo": "1",
                "outerItemNo": "1",
                "price": 50.12,
                "skuName": "数量:1瓶",
                "skuId": "1",
                "skuNo": "1",
                "isPresent": "false",
                "refundType": "退款-商家主动退款",
                "refundStatus": "退货退款",
                "lineStatus": "退货退款",
                "categoryId": "123",
                "itemMealId": "123",
                "itemMealName": "111111",
                "isEstimate": "是"
            }
        ]
    },
    {
        "dateCreated": "2023-03-16 15:48:41",
        "lastUpdated": "2023-03-16 15:48:41",
        "ver": 1,
        "id": 144357503180804,
        "props": {},
        "tenantId": 1,
        "saleChannel": "有赞",
        "channelId": 63,
        "contactId": 706402597617664,
        "orderId": "882",
        "orderStatus": "SELLER_CONSIGNED_PART",
        "orderOuterStatus": "SELLER_CONSIGNED_PART",
        "orderSource": "other",
        "payType": "优惠兑换",
        "payDate": "2022-11-28 10:33:45",
        "orderDate": "2022-11-28 10:33:44",
        "totalPrice": 100.240,
        "paymentPrice": 123.456,
        "refundPrice": 0.000,
        "successDate": "2022-11-28 10:33:45",
        "cancelDate": "2022-11-28 10:33:45",
        "cancelType": "2",
        "storeName": "微商城",
        "storeId": "111111",
        "paymentId": "1",
        "receiverName": "1",
        "deliveryProvince": "吉林省",
        "deliveryCity": "四平市",
        "deliveryDistrict": "梨树县222",
        "deliveryAddress": "1",
        "receiverMobile": "12345678901",
        "totalQuantity": 1,
        "orderType": "普通订单",
        "isPresale": "是",
        "presaleStatus": "XXX",
        "isMemberOrder": "是",
        "storeCardUsed": 100,
        "deliveryDate": "2022-11-28 10:33:45",
        "guideCode": "1A2S3D",
        "lines": [
            {
                "dateCreated": "2023-03-16 15:48:41",
                "lastUpdated": "2023-03-16 15:48:41",
                "ver": 1,
                "id": 144357503180805,
                "props": {},
                "tenantId": 1,
                "orderId": "882",
                "lineId": "L202210ddzda28",
                "saleChannel": "有赞",
                "channelId": 63,
                "contactId": 706402597617664,
                "orderDate": "2022-11-28 10:33:44",
                "itemTotalPrice": 0.000,
                "itemPaymentPrice": 0.000,
                "quantity": 2,
                "refundQuantity": 0,
                "refundPrice": 928.000,
                "brandName": "1",
                "category": "1",
                "productName": "维生素C1",
                "productAlias": "111111",
                "itemId": "111111",
                "itemNo": "1",
                "outerItemNo": "1",
                "price": 50.12,
                "skuName": "数量:1瓶",
                "skuId": "1",
                "skuNo": "1",
                "isPresent": "false",
                "refundType": "退款-商家主动退款",
                "refundStatus": "退货退款",
                "lineStatus": "退货退款",
                "categoryId": "123",
                "itemMealId": "123",
                "itemMealName": "111111",
                "isEstimate": "是"
            }
        ]
    }
]

HTTP Request

GET https://cdp-api.linkflowtech.com/open/orders

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Request Params

Parameter	Required	Default	Type	Description
lastMaxId	false		Long	游标ID,取上一批返回列表数据的最后一条ID字段值,第一次调用可以传0
startTime	false		datetime	yyyy-MM-dd HH:mm:ss格式,需要做urlEncode,时间开始闭区间,会与订单更新时间做匹配,大于等于关系
endTime	false		datetime	yyyy-MM-dd HH:mm:ss格式,需要做urlEncode,时间结束开区间,会与订单更新时间做匹配,小于关系
size	false	200	Integer	每页条数
page	false	1	Integer	页数，从 1 开始；分页模式必须满足 `size * (page - 1) <= 20000`

传入lastMaxId为游标模式传入startTime,endTime,page为分页模式

Error Code

HTTP Status Code	Parameter	Description
500	B00093	分页偏移量超过 20000

报表

获取报表结果

HTTP Request

GET https://cdp-api.linkflowtech.com/open/report/{reportId}

参数

Name	Location	Type	Required	Description
reportId	path variable	Long	True	报表ID
X-OpenApi-Token	header	String	True	通过 App Key 和 App Secret 换取的 Token

GET /open/report/{reportId} HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

返回数据样例

备注:不同的报表类型返回的result结构并不一样, 具体以调用api返回结果为准

报表计算可能会转异步进行, 这个时候返回的status为0, 可以轮询调用该接口直到status返回1为止

chartType 可为 NUMBER、PIE、STACK_BAR、LINE、BAR、TWO_YAXIS、LINE_AREA 或 TABLE。仅 TWO_YAXIS 图表会返回 yaxisChartTypeSetting。

{
    "status": 1,
    "reportName": "test",
    "chartType": "TWO_YAXIS",
    "chart": {
      "type": "TWO_YAXIS",
      "display": "双轴图",
      "yaxisChartTypeSetting": {
        "left": "BAR",
        "right": "LINE",
        "leftDisplay": "时间柱状图",
        "rightDisplay": "折线"
      }
    },
    "measures": [
      "任意事件的总次数",
      "创建订单的总次数"
    ],
    "dimensions": [
      {
        "field": "#{contact.gender}",
        "fieldType": "text",
        "fieldLabel": "性别"
      }
    ],
    "result": [
        {
            "dateList": [
                "2024-05-20",
                "2024-05-21",
                "2024-05-22",
                "2024-05-23",
                "2024-05-24",
                "2024-05-25",
                "2024-05-26"
            ],
            "dimRsList": [
                {
                    "dim": [
                        "总体"
                    ],
                    "rs": [
                        [
                            "0"
                        ],
                        [
                            "0"
                        ],
                        [
                            "0"
                        ],
                        [
                            "0"
                        ],
                        [
                            "0"
                        ],
                        [
                            "0"
                        ],
                        [
                            "0"
                        ]
                    ],
                    "summary": [
                        "0"
                    ]
                }
            ]
        }
    ]
}

获取仪表盘定义

HTTP Request

GET https://cdp-api.linkflowtech.com/open/dashboard/{dashboardId}/summary

参数

Name	Location	Type	Required	Description
dashboardId	path variable	Long	True	仪表盘ID
X-OpenApi-Token	header	String	True	通过 App Key 和 App Secret 换取的 Token

GET /open/dashboard/{dashboardId}/summary HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

返回数据样例

{
    "kanBanName": "y01",
    "reports": [
        {
            "id": 404,
            "reportName": "归因无"
        },
        {
            "id": 410,
            "reportName": "统计分析"
        },
        {
            "id": 411,
            "reportName": "分享转发"
        },
        {
            "id": 412,
            "reportName": "用户"
        },
        {
            "id": 413,
            "reportName": "粉丝数"
        },
        {
            "id": 597,
            "reportName": "自定义指标条件"
        },
        {
            "id": 655,
            "reportName": "用户生日是今天"
        },
        {
            "id": 656,
            "reportName": "网易云商通话拦截"
        },
        {
            "id": 689,
            "reportName": "通话属性采集"
        }
    ]
}

短链接

创建普通追踪短链接

HTTP Request

POST https://cdp-api.linkflowtech.com/open/shorturl

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Request Body

Parameter	Required	Type	Description
url	true	String	原链接地址
utm.source	false	String	来源
utm.campaign	false	String	活动
utm.medium	false	String	媒介
utm.content	false	String	内容
utm.term	false	String	关键字

POST /open/shorturl HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

{
    "url": "http://www.baidu.com",
    "utm": {
        "source": "testSource",
        "campaign": "testCampgin",
        "medium": "testMedium",
        "content": "testContent",
        "term": "testTerm"
    }
}

HTTP/1.1 200 OK

返回数据示例如下：

{
    "shorturl": "http://ln8w.cn/5T2SnX"
}

创建分发追踪短链接

HTTP Request

POST https://cdp-api.linkflowtech.com/open/shorturl/distribute

Headers

Parameter	Description
X-OpenApi-Token	通过App Key和App Secret换取的Access Token

Request Body

Parameter	Required	Type	Description
url	true	String	原链接地址
utm.source	false	String	来源
utm.campaign	false	String	活动
utm.medium	false	String	媒介
utm.content	false	String	内容
utm.term	true	String	联系人id

Error Code

HTTP Status Code	Parameter	Description
500	B00008	联系人不存在

POST /open/shorturl/distribute HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
X-OpenApi-Token: Access Token

{
    "url": "http://www.baidu.com",
    "utm": {
        "source": "testSource",
        "campaign": "testCampgin",
        "medium": "testMedium",
        "content": "testContent",
        "term": "71302452690124"
    }
}

正常返回数据示例如下：

HTTP/1.1 200 OK
{
    "shorturl": "http://ln8w.cn/3Ud9po6x"
}

异常返回数据示例如下：

HTTP/1.1 420 Client Error
{
    "code": "B00008",
    "message": "No [contact] found with id [71302452690124]"
}

错误处理

错误响应通常为 JSON 对象。不同接口返回的附加字段可能不同，但客户端至少应记录 HTTP 状态码、code、message 和请求 ID（如有），并按 code 分支处理。

{
  "code": "B00091",
  "message": "Invalid(or expired) token",
  "status": 403
}

鉴权与通用错误

HTTP Status	Code	Meaning	Client action
403	B00002	缺少 `X-OpenApi-Token`	补充请求头后重试
403	B00090	App 没有该路径或 HTTP 方法的权限	检查请求方法与 App 资源授权
403	B00091	Token 无效、已过期，或 Token 对应的 App 不可用	重新获取 Token，并检查私有 App 状态
404	-	路径不存在	检查公网 URL 与路径参数是否正确
429	-	请求过于频繁	使用指数退避并限制并发；不要立即无间隔重试
500/503	-	系统异常或暂时不可用	仅对幂等请求自动重试；写请求应结合 `request_id` 去重并先确认处理结果

业务接口的具体错误码列在各接口章节。 httpcode=420 为业务统一错误状态码。

Linkflow开放接口指南

接入约定

调用流程

Private App

创建Private App

通过App Key和App Secret获取Access Token

HTTP Request

Headers

Querystring parameters

联系人和事件

创建联系人和事件

HTTP Request

Headers

Request Body

messages

identities

查询联系人

HTTP Request

Headers

Request Parameters

Error Code

根据联系人查询渠道账号

HTTP Request

Headers

Path Parameters

查询企业微信联系我二维码

HTTP Request

Headers

Path Parameters

创建/更新订单订单

HTTP Request

Headers

Request Body

messages

data - salesOrderHead

data - salesOrderLine

identities

有赞订单状态映射

系统订单状态码

同步创建联系人和事件

HTTP Request

游标获取事件

HTTP Request

Querystring parameters

Response

标签

创建用户标签元数据

HTTP Request

Headers

Request Parameters

Error Code

删除用户标签元数据

HTTP Request

Headers

Request Parameters

Error Code

获取用户标签元数据列表

HTTP Request

Headers

Request Parameters

tagType 标签类型

Error Code

获取标签目录列表

HTTP Request

Headers

上传用户标签值文件

HTTP Request

Headers

Request Parameters

Error Code

发起计算用户标签值任务

HTTP Request

Headers

Request Parameters

Error Code

生成用户标签值文件

HTTP Request

Headers

Request Parameters

Error Code