1. 百度转化追踪联调newType 字段为什么总让线索 API 回传失败百度转化追踪的线索 API 回传是 oCPC 投放里绕不开的一环。简单说你在百度推广后台建好转化追踪拿到 token然后后端在用户完成注册、付费、表单提交这些动作时调百度接口把转化数据回传过去百度用这些数据去优化流量分配。听起来就是发个 POST 请求的事但真正联调的时候一个newType字段能把人卡到怀疑人生。我这次联调的场景是信息流推广 oCPC转化目标选了「表单按钮点击」「表单提交成功」「服务购买成功」三个事件接入方式选线索 API。联调页面会显示三张事件卡片每张都是「待联调」状态你需要扫码生成带bd_vid的测试 URL后端拿这个bd_vid去调https://ocpc.baidu.com/ocpcapi/api/uploadConvertData回传测试数据页面才会点亮。问题就出在newType上。我前后重试了 7 次前 6 次要么只亮一部分要么全 success 但页面纹丝不动。最后发现根因特别简单newType是百度定义好的转化类型编码每个事件对应一个固定数字传错了百度就按另一个事件处理页面自然不认。这篇就把这 7 次重试的复盘、可复制的请求体、newType取值对照表以及用 TaoToken 统一 Key 通道在 CC Switch 里写settings.json骨架后逐项验证的动作清单一次讲清楚。适合谁看正在接百度转化追踪线索 API 的后端同学、做 oCPC 投放需要回传转化数据的运营/开发、以及被联调页面「待联调」卡住过的人。2. 前置准备TaoToken 统一 Key 通道与联调环境在讲newType之前先把联调环境里跟 Key 管理相关的部分理一下。我这边后端服务会调用多个模型接口做线索评分和意图识别Key 散落在各个配置文件里联调时改一个环境就要同步改好几处很容易出错。后来我用 TaoToken 做统一 Key 通道把所有模型的调用收敛到一个入口联调时只需要维护一份配置。TaoToken 的定位是统一的大模型 API 接入层官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它的价值在于你不需要为每个模型单独管一套 Key 和 base_url统一走一个通道切换模型只改模型名。对于百度转化追踪这种联调场景后端要同时跑线索评分、表单意图识别、付费行为打标用统一通道能少很多环境变量。具体操作上我是在 CC Switch 里管理配置的。CC Switch 是一个多环境配置切换工具你可以把不同环境的settings.json骨架写好联调时一键切换。下面是我用的骨架结构重点是env里的ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN指向 TaoToken 通道{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Bash(curl:*), Read, Write ] } }这里有几个点要注意。ANTHROPIC_BASE_URL填https://taotoken.net/api不要带 UTM 参数UTM 只用于官网跳转统计。ANTHROPIC_AUTH_TOKEN去 TaoToken 控制台的 API Keys 页面生成地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。生成后直接粘进settings.json不要提交到 Git。如果你还没配过可以先去模型对话页面验证 Key 是否可用https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。能正常对话说明 Key 和通道都没问题再往下做百度线索 API 联调。注意TaoToken 是模型 API 的统一接入通道不替代百度转化追踪本身。百度线索 API 的 token、bd_vid、newType这些还是走百度自己的体系两者是配合关系不要混在一起。3. 可复制配置线索 API 请求体与 newType 取值对照表这一节是核心。百度线索 API 的回传接口是POST https://ocpc.baidu.com/ocpcapi/api/uploadConvertData请求体是 JSON 数组每个元素代表一次转化回传。关键字段有token、bd_vid、newType、convertTime、convertType。下面是我最终跑通的请求体三个事件一次回传[ { token: 你的百度转化追踪token, bd_vid: 联调页面生成的bd_vid, newType: 5, convertTime: 1735689600000, convertType: form_button_click }, { token: 你的百度转化追踪token, bd_vid: 联调页面生成的bd_vid, newType: 3, convertTime: 1735689600000, convertType: form_submit_success }, { token: 你的百度转化追踪token, bd_vid: 联调页面生成的bd_vid, newType: 10, convertTime: 1735689600000, convertType: service_purchase_success } ]convertTime是毫秒时间戳convertType是我自己加的业务标识百度不强制要求但方便日志排查。真正决定事件归属的是newType。下面这张对照表是我踩坑后整理的建议直接存下来转化事件newType 取值说明咨询按钮点击1页面咨询按钮电话按钮点击2拨打电话按钮表单提交成功3表单真正提交激活4App 激活表单按钮点击5表单上的按钮点击不是提交服务购买成功10付费转化应用注册25App 注册表单提交成功备用26部分账户用这个表单按钮点击备用27部分账户用这个咨询按钮点击备用28部分账户用这个电话按钮点击备用114部分账户用这个我前 6 次失败的核心原因就是把「表单按钮点击」当成了newType3。实际上3是「表单提交成功」5才是「表单按钮点击」。百度收到3就按表单提交处理联调页面上「表单按钮点击」那张卡片当然不会亮。还有一个坑不同账户的编码表可能有细微差异26/27/28/114这些备用值就是我在搜索时看到的。最稳的做法是去百度推广后台的转化追踪文档里查你账户对应的编码表不要凭记忆猜。用 curl 测试的话命令长这样curl -X POST https://ocpc.baidu.com/ocpcapi/api/uploadConvertData \ -H Content-Type: application/json \ -d [ { token: 你的token, bd_vid: 你的bd_vid, newType: 5, convertTime: 1735689600000 }, { token: 你的token, bd_vid: 你的bd_vid, newType: 3, convertTime: 1735689600000 }, { token: 你的token, bd_vid: 你的bd_vid, newType: 10, convertTime: 1735689600000 } ]返回{code:0,message:success}只代表百度收到了请求不代表联调页面会点亮。页面点亮取决于newType是否匹配你选的事件。这点一定要分清否则会像我一样看到 success 却以为成功了。4. 验证请求逐项点亮联调页面的动作清单联调页面有 1 小时超时超时后bd_vid失效要重新扫码。所以配好脚本、备好参数再开始别边调边等。下面是我最终跑通的验证清单按顺序做第一步在百度推广后台新建转化追踪渠道选信息流推广转化目标选不限转化事件勾选你要的三个接入方式选线索 API拿到 token。第二步打开联调页面扫码生成带bd_vid的测试 URL。把bd_vid复制出来填进上面的请求体。第三步确认newType映射表单按钮点击用5表单提交成功用3服务购买成功用10。三个事件一次回传不要分三次。第四步执行 curl 或后端脚本观察返回。返回code:0后刷新联调页面三张卡片应该全部变绿。第五步如果还有卡片没亮单独回传那个事件的newType看返回和页面变化。比如「表单按钮点击」没亮就只传newType5确认是不是编码问题。第六步联调通过后把测试bd_vid换成真实用户行为里的bd_vid在正式环境回传。真实bd_vid来自用户点击广告后落地页 URL 里的参数后端要把它存下来跟用户 ID 关联。这里有个细节bd_vid是百度用来关联点击和转化的唯一标识联调用的bd_vid和正式环境的不一样。联调通过只代表你的请求格式和newType对了正式回传还要确保bd_vid能正确透传。如果你在联调过程中需要调模型做线索意图判断可以用 TaoToken 的 Coding Plan 来跑批量测试https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它适合长期编码和 Agent 场景联调时用来批量验证回传逻辑比较顺手。5. 本篇常见错排查newType 与线索 API 的 7 类报错这一节把我踩过的和搜索时看到的错误归一下类你对着排查能省不少时间。第一类newType传错导致页面不亮。这是最高频的。表现是接口返回 success但联调页面某张卡片一直「待联调」。排查方法对照上面的表确认你选的事件和newType是否匹配。表单按钮点击是5不是3。第二类一次只传一个事件。表现是传了 A 事件B 事件卡片不亮。百度联调页面是按事件独立校验的你选了几个事件就要传几个newType。建议第一次就把所有事件的newType一起传。第三类bd_vid过期。联调页面 1 小时超时超时后bd_vid失效再传也是 success 但页面不动。排查方法重新扫码生成新bd_vid重新回传。第四类token填错。表现是接口返回非 0 错误码。排查方法去百度推广后台转化追踪详情页复制 token注意不要多空格。第五类convertTime格式错。百度要毫秒时间戳传成秒级会解析异常。排查方法用Date.now()或time.time()*1000生成。第六类请求头Content-Type没设。表现是接口报参数错误。排查方法加-H Content-Type: application/json。第七类把 TaoToken 的 Key 和百度 token 搞混。TaoToken 的 Key 是给模型 API 用的百度 token 是给线索 API 用的两者不能互换。排查方法检查请求体里的token是不是百度后台那个。注意联调页面显示 success 不等于转化追踪配置完成。联调只是验证你的回传格式和newType正确正式投放还要确保真实bd_vid能透传、回传时机对、去重逻辑对。6. 语义一致 CTA联调通过后的接入与验证入口联调通过后接下来就是把测试逻辑搬到正式环境。正式环境要处理三件事bd_vid的透传和存储、回传时机的选择注册成功、付费成功等、以及重复回传的去重。去重可以用bd_vid newType做唯一键避免同一转化多次上报。如果你在正式接入时需要统一管理模型 KeyTaoToken 的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言的接入示例。API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 生成后写进 CC Switch 的settings.json骨架即可。验证模型通道是否正常用模型对话页面最快https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。长期做编码和 Agent 联调的可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。最后说个我自己的经验百度转化追踪联调最耗时的不是写代码是等联调页面刷新和重新扫码。所以第一次就把newType对照表查清楚三个事件一次传完能省掉我那次 7 次重试里的大部分时间。newType5这个值我建议你直接记在便签上。
百度转化追踪联调踩坑记：newType 字段与线索 API 配置的 7 次重试复盘
1. 百度转化追踪联调newType 字段为什么总让线索 API 回传失败百度转化追踪的线索 API 回传是 oCPC 投放里绕不开的一环。简单说你在百度推广后台建好转化追踪拿到 token然后后端在用户完成注册、付费、表单提交这些动作时调百度接口把转化数据回传过去百度用这些数据去优化流量分配。听起来就是发个 POST 请求的事但真正联调的时候一个newType字段能把人卡到怀疑人生。我这次联调的场景是信息流推广 oCPC转化目标选了「表单按钮点击」「表单提交成功」「服务购买成功」三个事件接入方式选线索 API。联调页面会显示三张事件卡片每张都是「待联调」状态你需要扫码生成带bd_vid的测试 URL后端拿这个bd_vid去调https://ocpc.baidu.com/ocpcapi/api/uploadConvertData回传测试数据页面才会点亮。问题就出在newType上。我前后重试了 7 次前 6 次要么只亮一部分要么全 success 但页面纹丝不动。最后发现根因特别简单newType是百度定义好的转化类型编码每个事件对应一个固定数字传错了百度就按另一个事件处理页面自然不认。这篇就把这 7 次重试的复盘、可复制的请求体、newType取值对照表以及用 TaoToken 统一 Key 通道在 CC Switch 里写settings.json骨架后逐项验证的动作清单一次讲清楚。适合谁看正在接百度转化追踪线索 API 的后端同学、做 oCPC 投放需要回传转化数据的运营/开发、以及被联调页面「待联调」卡住过的人。2. 前置准备TaoToken 统一 Key 通道与联调环境在讲newType之前先把联调环境里跟 Key 管理相关的部分理一下。我这边后端服务会调用多个模型接口做线索评分和意图识别Key 散落在各个配置文件里联调时改一个环境就要同步改好几处很容易出错。后来我用 TaoToken 做统一 Key 通道把所有模型的调用收敛到一个入口联调时只需要维护一份配置。TaoToken 的定位是统一的大模型 API 接入层官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它的价值在于你不需要为每个模型单独管一套 Key 和 base_url统一走一个通道切换模型只改模型名。对于百度转化追踪这种联调场景后端要同时跑线索评分、表单意图识别、付费行为打标用统一通道能少很多环境变量。具体操作上我是在 CC Switch 里管理配置的。CC Switch 是一个多环境配置切换工具你可以把不同环境的settings.json骨架写好联调时一键切换。下面是我用的骨架结构重点是env里的ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN指向 TaoToken 通道{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Bash(curl:*), Read, Write ] } }这里有几个点要注意。ANTHROPIC_BASE_URL填https://taotoken.net/api不要带 UTM 参数UTM 只用于官网跳转统计。ANTHROPIC_AUTH_TOKEN去 TaoToken 控制台的 API Keys 页面生成地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。生成后直接粘进settings.json不要提交到 Git。如果你还没配过可以先去模型对话页面验证 Key 是否可用https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。能正常对话说明 Key 和通道都没问题再往下做百度线索 API 联调。注意TaoToken 是模型 API 的统一接入通道不替代百度转化追踪本身。百度线索 API 的 token、bd_vid、newType这些还是走百度自己的体系两者是配合关系不要混在一起。3. 可复制配置线索 API 请求体与 newType 取值对照表这一节是核心。百度线索 API 的回传接口是POST https://ocpc.baidu.com/ocpcapi/api/uploadConvertData请求体是 JSON 数组每个元素代表一次转化回传。关键字段有token、bd_vid、newType、convertTime、convertType。下面是我最终跑通的请求体三个事件一次回传[ { token: 你的百度转化追踪token, bd_vid: 联调页面生成的bd_vid, newType: 5, convertTime: 1735689600000, convertType: form_button_click }, { token: 你的百度转化追踪token, bd_vid: 联调页面生成的bd_vid, newType: 3, convertTime: 1735689600000, convertType: form_submit_success }, { token: 你的百度转化追踪token, bd_vid: 联调页面生成的bd_vid, newType: 10, convertTime: 1735689600000, convertType: service_purchase_success } ]convertTime是毫秒时间戳convertType是我自己加的业务标识百度不强制要求但方便日志排查。真正决定事件归属的是newType。下面这张对照表是我踩坑后整理的建议直接存下来转化事件newType 取值说明咨询按钮点击1页面咨询按钮电话按钮点击2拨打电话按钮表单提交成功3表单真正提交激活4App 激活表单按钮点击5表单上的按钮点击不是提交服务购买成功10付费转化应用注册25App 注册表单提交成功备用26部分账户用这个表单按钮点击备用27部分账户用这个咨询按钮点击备用28部分账户用这个电话按钮点击备用114部分账户用这个我前 6 次失败的核心原因就是把「表单按钮点击」当成了newType3。实际上3是「表单提交成功」5才是「表单按钮点击」。百度收到3就按表单提交处理联调页面上「表单按钮点击」那张卡片当然不会亮。还有一个坑不同账户的编码表可能有细微差异26/27/28/114这些备用值就是我在搜索时看到的。最稳的做法是去百度推广后台的转化追踪文档里查你账户对应的编码表不要凭记忆猜。用 curl 测试的话命令长这样curl -X POST https://ocpc.baidu.com/ocpcapi/api/uploadConvertData \ -H Content-Type: application/json \ -d [ { token: 你的token, bd_vid: 你的bd_vid, newType: 5, convertTime: 1735689600000 }, { token: 你的token, bd_vid: 你的bd_vid, newType: 3, convertTime: 1735689600000 }, { token: 你的token, bd_vid: 你的bd_vid, newType: 10, convertTime: 1735689600000 } ]返回{code:0,message:success}只代表百度收到了请求不代表联调页面会点亮。页面点亮取决于newType是否匹配你选的事件。这点一定要分清否则会像我一样看到 success 却以为成功了。4. 验证请求逐项点亮联调页面的动作清单联调页面有 1 小时超时超时后bd_vid失效要重新扫码。所以配好脚本、备好参数再开始别边调边等。下面是我最终跑通的验证清单按顺序做第一步在百度推广后台新建转化追踪渠道选信息流推广转化目标选不限转化事件勾选你要的三个接入方式选线索 API拿到 token。第二步打开联调页面扫码生成带bd_vid的测试 URL。把bd_vid复制出来填进上面的请求体。第三步确认newType映射表单按钮点击用5表单提交成功用3服务购买成功用10。三个事件一次回传不要分三次。第四步执行 curl 或后端脚本观察返回。返回code:0后刷新联调页面三张卡片应该全部变绿。第五步如果还有卡片没亮单独回传那个事件的newType看返回和页面变化。比如「表单按钮点击」没亮就只传newType5确认是不是编码问题。第六步联调通过后把测试bd_vid换成真实用户行为里的bd_vid在正式环境回传。真实bd_vid来自用户点击广告后落地页 URL 里的参数后端要把它存下来跟用户 ID 关联。这里有个细节bd_vid是百度用来关联点击和转化的唯一标识联调用的bd_vid和正式环境的不一样。联调通过只代表你的请求格式和newType对了正式回传还要确保bd_vid能正确透传。如果你在联调过程中需要调模型做线索意图判断可以用 TaoToken 的 Coding Plan 来跑批量测试https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它适合长期编码和 Agent 场景联调时用来批量验证回传逻辑比较顺手。5. 本篇常见错排查newType 与线索 API 的 7 类报错这一节把我踩过的和搜索时看到的错误归一下类你对着排查能省不少时间。第一类newType传错导致页面不亮。这是最高频的。表现是接口返回 success但联调页面某张卡片一直「待联调」。排查方法对照上面的表确认你选的事件和newType是否匹配。表单按钮点击是5不是3。第二类一次只传一个事件。表现是传了 A 事件B 事件卡片不亮。百度联调页面是按事件独立校验的你选了几个事件就要传几个newType。建议第一次就把所有事件的newType一起传。第三类bd_vid过期。联调页面 1 小时超时超时后bd_vid失效再传也是 success 但页面不动。排查方法重新扫码生成新bd_vid重新回传。第四类token填错。表现是接口返回非 0 错误码。排查方法去百度推广后台转化追踪详情页复制 token注意不要多空格。第五类convertTime格式错。百度要毫秒时间戳传成秒级会解析异常。排查方法用Date.now()或time.time()*1000生成。第六类请求头Content-Type没设。表现是接口报参数错误。排查方法加-H Content-Type: application/json。第七类把 TaoToken 的 Key 和百度 token 搞混。TaoToken 的 Key 是给模型 API 用的百度 token 是给线索 API 用的两者不能互换。排查方法检查请求体里的token是不是百度后台那个。注意联调页面显示 success 不等于转化追踪配置完成。联调只是验证你的回传格式和newType正确正式投放还要确保真实bd_vid能透传、回传时机对、去重逻辑对。6. 语义一致 CTA联调通过后的接入与验证入口联调通过后接下来就是把测试逻辑搬到正式环境。正式环境要处理三件事bd_vid的透传和存储、回传时机的选择注册成功、付费成功等、以及重复回传的去重。去重可以用bd_vid newType做唯一键避免同一转化多次上报。如果你在正式接入时需要统一管理模型 KeyTaoToken 的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言的接入示例。API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 生成后写进 CC Switch 的settings.json骨架即可。验证模型通道是否正常用模型对话页面最快https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。长期做编码和 Agent 联调的可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。最后说个我自己的经验百度转化追踪联调最耗时的不是写代码是等联调页面刷新和重新扫码。所以第一次就把newType对照表查清楚三个事件一次传完能省掉我那次 7 次重试里的大部分时间。newType5这个值我建议你直接记在便签上。