卡世界平台API开放对接，一文看懂怎么接

API对接 技术文档 卡世界

想自动化对接号卡业务？接口文档看懵了？这篇帮你理清楚。

先搞清楚：你能拿到什么

我们开放的接口覆盖了从「选品」到「结算」的完整链路。不需要再手动后台点来点去，全部可以用代码自动跑。

图：7个核心接口的完整业务链路

7个核心接口一览

接口	干嘛用的	方法
在售商品列表	拉取当前所有在售商品	GET
查询商品	查某个商品的详细信息、套餐内容、佣金	GET
查询商品的可选地区	看这个商品哪些城市能发货	GET
选号接口	给下单用户选手机号	POST
查询订单	查订单状态、物流、激活情况	POST
结算状态批量查询	批量查一批订单的佣金结算状态	POST
可结算订单列表	拉取能提现的订单清单	POST

整个链路：拉商品 → 展示给用户 → 查地区 → 选号码 → 提交订单 → 查状态 → 查佣金。

第一步：拿商品数据

在售商品列表（GET）

调一下就能拿到所有在售商品的基础信息：名称、月租、流量、头图、你的推广链接。

建议：每天定时拉一次做缓存。商品上下架会变，但没那么频繁。

Python

import requests

url = "https://ym.ksjhaoka.com/api/index/goods/index"

params = {

"store_id": ""你的店铺ID"",

"keyword": "",

"current": "1",

"size": "20"

}

resp = requests.get(url, params=params)

data = resp.json()

# 商品列表在 data["data"]["list"] 里for goods in data["data"]["list"]:

print(f"商品名：{goods['name']}，月租：{goods['tabs']}")

curl

curl -X GET \

"https://ym.ksjhaoka.com/api/index/goods/index?\

store_id=你的店铺ID¤t=1&size=20"

图：通过代码直接调用API获取数据

查询商品详情（GET）

用户点进某个商品时调这个接口，返回完整的套餐规则、优惠期、合约期、首充要求、禁发地区、佣金金额。

参数：id（商品ID）+ store_id（你的店铺ID，必传，用来算你的佣金）

Python

import requests

url = "https://ym.ksjhaoka.com/api/index/goods/show"

params = {

"id": ""42342450"", # 商品ID

"store_id": ""你的店铺ID"" # 你的店铺store_id

}

resp = requests.get(url, params=params)

data = resp.json()print(data)

curl

curl -X GET \

"https://ym.ksjhaoka.com/api/index/goods/show?id=42342450&\

store_id=你的店铺ID"

建议：用户点进商品详情时再调，不要一口气全拉，数据量太大。

查询可选地区（GET）

不同商品能发货的地区不一样。传入商品ID，返回省-市-区三级树，每个节点标了 disable 字段，false 表示能发，true 表示不能发。

图：不同商品的可发货地区不同，请通过接口实时获取

Python

import requests

url = "https://ym.ksjhaoka.com/api/index/region"

params = {

"goods_id": ""82341958"" # 商品ID

}

resp = requests.get(url, params=params)

data = resp.json()

# 遍历省份for province in data["data"]["data"]:

print(f"省份：{province['name']}")

for city in province.get("children", []):

status = "可发" if not city.get("disable") else "禁发"

print(f" {city['name']} - {status}")

curl

curl -X GET \

"https://ym.ksjhaoka.com/api/index/region?goods_id=82341958"

前端展示建议：地区选择器直接用这个数据渲染，禁发的置灰，用户点不了。

第二步：下单流程

选号接口（POST）

如果商品支持选号，用这个接口拉可选号码池。返回手机号列表，展示给用户挑。

注意：不是所有商品都支持选号，先查商品详情里的配置。

Python

import requests

url = "https://ym.ksjhaoka.com/api/index/pool"

payload = {

"goods_id": 82341946, # 商品ID（数字）

"attribution_province": 3163, # 省份ID（从地区接口获取）

"attribution_city": 3268, # 城市ID（从地区接口获取）

"keyword": "", # 可选，按号码片段搜索

"searchCondition": False,

"set_meal": "",

"pool_code": "",

"token": "",

"number_segment": ""all"" # 号段，all 表示全部

}

resp = requests.post(url, json=payload)

data = resp.json()print(data)

curl

curl -X POST https://ym.ksjhaoka.com/api/index/pool \

-H "Content-Type: application/json" \

-d '{

"goods_id": 82341946,

"attribution_province": 3163,

"attribution_city": 3268,

"keyword": "",

"searchCondition": false,

"set_meal": "",

"pool_code": "",

"token": "",

"number_segment": "all"

}'

第三步：查订单、追佣金

查询订单（POST）

按手机号、订单号查订单状态。返回字段包括：订单状态、物流信息、首充金额、失败原因。

Python

import requests

url = "https://ksjhaoka.com/api/index/ktt/query/order"

payload = {

"store_id": ""你的店铺ID"",

"order_no": ""order20260623161816995528"", # 订单号，可选

"api_key": ""你的API密钥"" # 从卡世界后台获取

}

resp = requests.post(url, data=payload)

data = resp.json()

for order in data["data"]:

print(f"订单：{order['order_no']}，状态：{order['statuss']}，佣金：{order['brokerage']}")

curl

curl -X POST https://ksjhaoka.com/api/index/ktt/query/order \

-d "store_id=你的店铺ID" \

-d "order_no=order20260623161816995528" \

-d "api_key=你的API密钥"

建议：跑一个定时任务，每天查一遍新订单的状态变化，同步到你自己的系统。

结算状态批量查询（POST）

一次查最多几百条订单的结算状态。返回每个订单的结算金额、结算状态、不结算原因。

Python

import requests

url = "https://ym.ksjhaoka.com/api/index/brokerage/settle_query"

payload = {

"store_id": ""你的店铺ID"",

"api_key": ""你的API密钥"",

"order_nos": [ # 订单号数组，最多几百条

""order20260623161446995528"",

""order20260623161816995528""

]

}

resp = requests.post(url, json=payload)

data = resp.json()

for item in data["data"]:

print(f"订单：{item['order_no']}，结算状态：{item['brokerage_status_text']}，佣金：{item['brokerage']}")

curl

curl -X POST https://ym.ksjhaoka.com/api/index/brokerage/settle_query \

-H "Content-Type: application/json" \

-d '{

"store_id": "你的店铺ID",

"api_key": "你的API密钥",

"order_nos": ["order20260623161446995528"]

}'

常见不结算原因：用户未首充、激活后秒注销、套餐变更、违规推广等。

可结算订单列表（POST）

直接拉取所有能提现的订单，用来做佣金提现页面。支持按状态筛选，返回订单明细和汇总金额。

Python

import requests

url = "https://ym.ksjhaoka.com/api/index/brokerage/settle_list"

payload = {

"store_id": ""你的店铺ID"",

"api_key": ""你的API密钥"",

"current": ""1"", # 页码

"size": ""20"", # 每页数量

"status": ""0"" # 0=待结算，1=已结算

}

resp = requests.post(url, data=payload)

data = resp.json()

print(f"总共有 {data['data']['pagination']['total']} 条可结算订单")for order in data["data"]["list"]:

print(f"订单：{order['order_no']}，佣金：{order['brokerage']}，状态：{order['brokerage_status_text']}")

curl

curl -X POST https://ym.ksjhaoka.com/api/index/brokerage/settle_list \

-d "store_id=你的店铺ID" \

-d "api_key=你的API密钥" \

-d "current=1" \

-d "size=20" \

-d "status=0"

认证方式

所有接口统一用 api_key 认证。

登录卡世界后台 → 个人中心 → API密钥，复制你的密钥。每次请求带上 api_key 参数。

注意：api_key 别写死在代码里，也别放前端，放服务端环境变量。

Python 最佳实践

import os

API_KEY = os.environ.get(""KASHIJIE_API_KEY"") # 从环境变量读取

STORE_ID = os.environ.get(""KASHIJIE_STORE_ID"")

常见问题

Q：接口有频率限制吗？

目前单接口 QPS 限制 10，正常业务完全够用。如果超了会返回 429，稍后重试即可。

Q：地区数据会更新吗？

会。运营商政策调整可能导致某些地区突然停发，建议每天同步一次地区数据。

Q：订单状态多久变一次？

发货：一般1-3个工作日 / 激活：用户收到货后自主激活 / 首充：激活后当天或次日 / 结算：首充后次月出账

Q：测试环境有吗？

有。上面每个接口都可以先把域名换成 Mock 地址调通，再切正式环境。Mock 地址在文档页面里复制。

Q：为什么有些接口域名是 ym.ksjhaoka.com，有些是 ksjhaoka.com？

历史原因，两个域名都指向同一套服务。建议统一用 ym.ksjhaoka.com，只有查询订单接口必须用 ksjhaoka.com。

完整对接流程图

对接步骤

1. 申请API密钥（后台个人中心）

|

v

2. 每天定时跑：在售商品列表 → 缓存到本地数据库

|

v

3. 用户浏览商品 → 从缓存读取商品列表

|

v

4. 用户点进商品详情 → 调查询商品详情 + 查地区接口

| |

v v

展示套餐规则 用户选地址时校验是否可发

|

v

5. 如果商品支持选号 → 调选号接口 → 展示号码池

|

v

6. 用户提交订单 → 跳卡世界主站完成下单

|

v

7. 每天定时跑：查询订单 → 同步状态到自己的系统

|

v

8. 次月跑：可结算订单列表 → 批量查结算状态 → 申请提现

文档地址、密钥申请、技术支持，全部在卡世界后台 → API中心。

有问题直接在代理群里 @技术客服，别自己憋着。

说两句

做号卡业务，信息同步效率决定你能赚多少。手动后台查订单、算佣金，一天撑死处理几十单。接口对接之后，系统自动跑，你只需要看数据大屏就行。

已经有不少代理商用这套接口搭了自己的分销系统，月单量过万的不在少数。技术门槛不高，一个后端+一个前端，一周就能跑起来。

本文档由卡世界技术团队整理发布

接口持续迭代中，建议收藏本文档链接，随时回来看最新版本

Kimi Agent