Kakao 提链 API

CDK 认证 · REST JSON · 扫码完成后结算

快速接入

项目	值
Base URL
协议	HTTPS
数据格式	`application/json; charset=utf-8`
认证	`X-CDK: KSCAN-...`，兼容 `X-CDK-Key`

最小请求

创建订单后建议每 1 秒查询一次订单。直接展示 order.feedback 即可获得与网页前端一致的账号和任务反馈；order.attempt / order.max_attempts 为实时尝试进度，默认最多 10 次；当 order.terminal=true 时停止轮询。扫码回执由外部工作台同步，通常在 2 秒内更新。

认证与订单归属

请求头

Content-Type: application/json X-CDK: KSCAN-XXXX-XXXX-XXXX-XXXX

场景	响应
缺少 CDK	HTTP 401
CDK 不存在、停用或额度不足	HTTP 400
查询其他 CDK 创建的订单	HTTP 404
请求过于频繁	HTTP 429

CDK 同时用于认证、订单归属和额度结算。日志只保留订单编号和状态。

创建订单

POST/orders

请求体

字段	类型	必填	说明
`access_token`	string	必填	完整 AT 输入内容
`email`	string	否	账号邮箱；返回和前端列表中只显示掩码，未填写时从 Token 读取
`channel`	string	否	固定使用 `KAKAO_KK`
`mode`	string	否	固定使用 `EXTRACT`
`productType`	string	否	固定使用 `KAKAO_EXTRACT`
`ticket`	string	否	填写时必须与请求头 CDK 一致

请求

HTTP 201

{ "ok": true, "order": { "order_id": "KAI-0123ABCDEF", "status": "extracting", "phase": "eligibility", "message": "正在验证卡密并检测账号 0 元试用资格…", "feedback": "正在验证卡密并检测账号 0 元试用资格…", "feedback_code": "checking_eligibility", "feedback_level": "pending", "terminal": false, "retryable": false, "account": "pe***n@example.com", "attempt": 1, "max_attempts": 10, "retry_count": 0, "created_at": 1785256800, "updated_at": 1785256800, "completed_at": 0, "error": "" }, "ticket": {"code":"KSCAN-XXXX-XXXX-XXXX-XXXX","available_uses":0,"pending_uses":1} }

创建后系统自动执行资格确认、链接提取和外部工作台投递。扫码完成后扣除额度，提取或扫码失败时释放额度。

查询订单

GET/orders/{order_id}

等待扫码响应示例

{ "ok": true, "order": { "order_id": "KAI-0123ABCDEF", "status": "awaiting_scan", "phase": "scan", "message": "链接已提取，请等待 Kakao Pay 扫码。", "feedback": "链接已提取，请等待 Kakao Pay 扫码。", "feedback_code": "awaiting_scan", "feedback_level": "pending", "terminal": false, "retryable": false, "account": "pe***n@example.com", "attempt": 1, "max_attempts": 10, "retry_count": 0, "link": "https://pay.nicepay.co.kr/...", "error": "" }, "ticket": {"available_uses":0,"pending_uses":1} }

响应字段

字段	说明
`order.status`	订单状态：`queued`、`extracting`、`awaiting_scan`、`completed`、`failed` 或 `expired`
`order.phase`	当前环节：`eligibility`、`extraction`、`scan` 或 `completed`
`order.account`	掩码账号邮箱或不可逆账号摘要
`order.attempt` / `order.max_attempts`	当前完整链路尝试次数和本轮上限，默认上限 10
`order.retry_count`	管理员手动重新提取次数
`order.feedback`	可直接显示给用户的中文反馈，与网页前端一致
`order.feedback_code`	稳定的机器可读反馈代码
`order.feedback_level`	`pending`、`success` 或 `error`
`order.terminal`	`true` 表示订单结束，客户端停止轮询
`order.retryable`	失败后是否适合重新提交
`order.link`	提取出的 Kakao Pay 链接，仅在链接已生成后返回
`order.error`	后端原始失败原因，仅用于日志和排查
`ticket`	额度和冻结状态

查询额度

GET/tickets/status

{"ok":true,"ticket":{"code":"KSCAN-XXXX-XXXX-XXXX-XXXX","total_uses":1,"used_uses":0,"pending_uses":0,"available_uses":1,"status":"active"}}

订单状态机

extracting资格检测或链接提取

awaiting_scan链接已投递，等待扫码

completed扫码完成并扣除额度

failed / expired处理结束并释放额度

前端反馈代码

feedback_code	显示内容
`retry_queued`	账号已加入重新提取队列。
`checking_eligibility`	正在验证卡密并检测账号 0 元试用资格…
`extracting_link`	0 元试用资格已确认，正在提取 Kakao Pay 链接。
`awaiting_scan`	链接已提取，请等待 Kakao Pay 扫码。
`scan_completed`	Kakao Pay 扫码完成，卡密额度已扣除。
`account_has_plus`	该账号已开通 Plus，不允许提炼。
`account_invalid`	帐户已失效或被封禁 401
`eligibility_failed`	暂时无法确认资格，请稍后重试。
`workstation_failed`	外部扫码工作台失败提示

以 terminal 判断是否停止轮询，以 feedback 显示内容。管理员手动重提时状态会短暂变为 queued，随后重新进入资格检测。error 留作开发日志。

HTTP 错误处理

{"ok":false,"error":"可读错误说明","feedback":"可直接显示给用户的错误说明","feedback_code":"account_has_plus","terminal":true,"retryable":false}

HTTP	场景	处理
400	参数、AT、CDK 或额度错误	显示 `feedback`，修正请求后再提交
401	缺少 CDK	补充 `X-CDK`
404	订单不存在或归属不符	检查订单号和 CDK
409	Token 明确显示账号已开通 Plus	停止提炼，不重试
429	请求过于频繁	指数退避
500 / 503	服务暂时异常	保存订单号后查询

完整示例

JavaScript

Python

外部工作台状态与投递回执

以下接口使用 X-CDK 认证，只返回该 CDK 自己创建的投递记录。

GET/workstation/status

{"ok":true,"workstation":{"online_count":2,"queued_count":3,"accepting":true}}

online_count 为在线人工，queued_count 为扫码排队数量，accepting 表示是否接单。

POST/workstation/submissions/status

{"ids":["外部投递ID-1","外部投递ID-2"]}

批量查询投递 ID 的扫码状态，返回 submission_id、state、workstation_id、settlement_state 和更新时间。