聚光表单投放-线索管理获取线索列表 API 对接开发说明（对外）使用指引
1、对接流程
第一步：在落地页-数据推送功能处填写有效的POST消息接收地址
第二步：发送测试消息进行联调测试（response code必须为200才可联调成功）
第三步：使用联调成功的落地页进行投放，API实时回传表单数据
2、平台功能截图
3、消息发送
用户提交表单后，将以POST请求的方式将信息以JSON数据格式推送到在落地页配置页面中填写的消息接收地址。如果返回的responsecode为200，则表示推送成功。对于推送失败的情况，系统将每隔30秒进行一次重试，Zui多重试3次。
地址格式要求：
消息接收地址必须是一个对外开放的HTTP服务URL，能够接受POST请求。
例如：http://example.com/leads
4、签名验证
为了确保消息来源于小红书，可以选择对POST数据的来源进行安全认证（非必须），验证方法如下：
-解析POST消息header中的X-Red-Signature参数（格式为sha1=5bf9f4192d049dfe442edbcd533223673bb188e4）。
- 解析POST消息的request body（原始未经反序列化的原始body数据）。
-使用落地页配置页面获取的token作为secretKey，与body数据生成签名，并与header中的signature进行校验。
Java示例代码：
```
// Java示例代码
// 签名验证
public boolean verifySignature(HttpServletRequest request,String secretKey) {
String signatureHeader =request.getHeader("X-Red-Signature");
if (signatureHeader != null) {
String[] signatureParts =signatureHeader.split("=");
if (signatureParts.length == 2){
String algorithm =signatureParts[0];
String signature =signatureParts[1];
String requestBody =getRequestBody(request);
// 生成签名
StringgeneratedSignature = generateSignature(requestBody, secretKey);
// 校验签名
if(algorithm.equals("sha1") &&signature.equals(generatedSignature)) {
returntrue;
}
}
}
return false;
}
```
Python示例代码：
```
# Python示例代码
# 签名验证
def verify_signature(request, secret_key):
signature_header =request.headers.get('X-Red-Signature')
if signature_header:
signature_parts =signature_header.split('=')
if len(signature_parts) == 2:
algorithm =signature_parts[0]
signature =signature_parts[1]
request_body =get_request_body(request)
# 生成签名
generated_signature =generate_signature(request_body, secret_key)
# 校验签名
if algorithm == 'sha1'and signature == generated_signature:
returnTrue
return False
```
推送消息示例：直接提供包含姓名、电话、邮箱、性别、地址、单选、多选、文本、数值等类型代码示例的消息推送示例。
签名验证demo（Java）：提供了Java版本的签名验证示例代码。
常见Q&A
Q1、表单的API回传中，默认会包含用户提交表单的地域数据吗？还是必须由客户定义字段来收集并回传？
A：只支持通过地址或门店组件等方式记录或传递地域数据，默认不会包含。
Q2、用户在表单落地页提交成功后，但在客户CRM系统中查询不到信息，该如何解决？
A：可能有以下情况：1）小红书在对外传输数据时采用了根据用户ID和落地页ID去重的机制，同一页面多次提交相同手机号只会传输一次。这一般发生在客户内部员工测试链路时，建议客户更换手机号进行测试。2）确认是否在测试数据发送时没有配置API，如果是，请建议客户更换用户账号重新提交。如果问题仍然存在，请按照排查模板提交问题以便排查。
Q3、API回传是否支持上传加密文件？
A：不支持。
Q4、API回传是否支持区分搜索和信息流？
A：支持，可以使用字段channel进行区分。
Q5、URL字段是指落地页的URL吗？是否需要编码？
A：URL字段是指发送地址，并不是落地页地址，与编码无关。
Q6、表单数据中的label值是由表单定义的值吗？
A：是的，label值由表单定义决定。
Q7、文档中的参数中没有渠道号信息，如果希望在URL中携带渠道号来区分数据，应该如何操作？
A：不支持定制参数。
Q8、落地页的token是每个表单都不同，还是一个账户下共用一个token？
A：落地页的token是在专业号下唯一的。