API 文档

下载 API 文档(Markdown)

kartesim 通过两项服务为合作伙伴提供真实电话号码:长期的 号码租用 和按次计费的 OTP 会话。两者均可通过 HANDLER_API 协议和 Native REST API 使用。

OTP 会话按次

请求一个临时号码,等待 SMS,收到 OTP 验证码,一个 API 调用周期即可完成。按会话计费,如果你在验证码到达前取消则退款。

号码租用SIM 卡

按日、按周或按月租用专属电话号码。该号码收到的所有 SMS 都会实时转发到你的账户。

租用由你的客户经理开通。联系我们来开通你的租用。生效后,你的电话号码会出现在合作伙伴门户中,并可通过 API 查询。OTP 会话可通过 API 自助使用,无需任何设置。

身份验证

所有 API 请求都需要你的合作伙伴 API 密钥。传递方式取决于你使用的协议。

Handler API:查询参数

GET /api/stubs/handler_api.php
  ?api_key=YOUR_KEY
  &action=getBalance

Native REST API:HTTP 请求头

curl https://www.kartesim.com/api/v1/otp/request \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram"}'

请妥善保管你的 API 密钥。你的密钥可在合作伙伴门户的 API 下查看。使用那里的 重新生成密钥 按钮可立即轮换密钥。

Handler API 参考

Base URL:/api/stubs/handler_api.php。所有请求均使用 GET。所有响应均为纯文本。

GET/api/stubs/handler_api.php?action=getBalance

返回你当前的预付余额(USD)。

参数

名称	类型	必填	说明
api_key	string	必填	你的 API 密钥
action	string	必填	必须为 "getBalance"

响应

45.00你的余额(USD)

999999无限余额账户返回的固定占位值,不是真实余额,也不随使用量变化

BAD_KEYAPI 密钥无效或已撤销

请求示例

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getBalance'

响应示例

45.00

GET/api/stubs/handler_api.php?action=getCountries

列出支持的国家及其数字代码。

参数

名称	类型	必填	说明
api_key	string	必填	你的 API 密钥
action	string	必填	必须为 "getCountries"

响应

JSON array[{ "id": 7, "name": "Russia" }, ...]

请求示例

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getCountries'

响应示例

[
  { "id": 7,   "name": "Russia" },
  { "id": 212, "name": "Morocco" }
]

GET/api/stubs/handler_api.php?action=getPrices

获取各国家和服务的当前价格及可用的在线库存。

参数

名称	类型	必填	说明
api_key	string	必填	你的 API 密钥
action	string	必填	必须为 "getPrices"
country	number	可选	按数字国家 ID 筛选
hide_empty	integer	可选	设为 1 可从响应中排除库存为零的国家

响应

JSON object{ "countryId": { "serviceId": { "cost": 0.1, "count": 10 } } }

请求示例

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getPrices&hide_empty=1'

响应示例

{
  "212": {
    "wa": { "cost": 0.15, "count": 12 },
    "tg": { "cost": 0.15, "count": 12 }
  }
}

GET/api/stubs/handler_api.php?action=getNumber

请求一个用于 OTP 验证的临时电话号码。返回会话 ID 和分配的号码。如果没有 SMS 到达,会话在 10 分钟后过期。

参数

名称	类型	必填	说明
api_key	string	必填	你的 API 密钥
action	string	必填	必须为 "getNumber"
service	string	可选	服务名称(例如"telegram"、"whatsapp"),仅供参考
country	integer	可选	国家区号(例如摩洛哥为 212)。省略或使用 0 表示任意国家。

响应

ACCESS_NUMBER:id:number会话已创建:id 用于 getStatus/setStatus,number 为分配的电话号码

NO_NUMBERS没有符合你请求的在线端口

NO_BALANCE余额不足以支付 OTP 费用

请求示例

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getNumber&service=telegram&country=212'

响应示例

ACCESS_NUMBER:cma4x9k3b0000abc123:212661234567

GET/api/stubs/handler_api.php?action=getStatus

轮询活动会话的 OTP 验证码。每 5–10 秒轮询一次,直到收到 STATUS_OK 或 STATUS_CANCEL。

参数

名称	类型	必填	说明
api_key	string	必填	你的 API 密钥
action	string	必填	必须为 "getStatus"
id	string	必填	ACCESS_NUMBER 响应中的会话 ID

响应

STATUS_WAIT_CODE会话处于活动状态,尚未收到 SMS。请继续轮询。

STATUS_OK:84729已收到 OTP,验证码在冒号之后

STATUS_CANCEL会话已过期或已取消

请求示例

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getStatus&id=cma4x9k3b0000abc123'

响应示例

STATUS_OK:84729

GET/api/stubs/handler_api.php?action=setStatus

确认已收到 OTP(status=1),或取消会话并获得全额退款(status=8)。只有 PENDING 会话可以取消。

参数

名称	类型	必填	说明
api_key	string	必填	你的 API 密钥
action	string	必填	必须为 "setStatus"
id	string	必填	要操作的会话 ID
status	integer	必填	1 = 确认已收到,8 = 取消并退款

响应

ACCESS_READY已确认:会话已确认收到

ACCESS_CANCEL已取消:余额已退还

BAD_ACTION会话未找到或已完成

请求示例

# Cancel and refund
curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=setStatus&id=cma4x9k3b0000abc123&status=8'

响应示例

ACCESS_CANCEL

Native REST API

对于现代化的接入,请使用我们的 Native REST API,而不是旧版 Handler API。通过 x-api-key HTTP 请求头传递你的 API 密钥。

OTP 会话

按次

OTP 会话让你请求一个临时电话号码、接收一次性验证码并释放号码,全部通过 API 完成。每个会话在创建时计费一次。如果你在验证码到达前取消,将全额退还费用。

POST/api/v1/otp/request

请求一个用于 OTP 验证的临时电话号码。返回 sessionId 和分配的号码。立即收取 OTP_PER_USE 费用。

参数

名称	类型	必填	说明
country	integer	可选	用于筛选的国家区号(例如 212)。省略表示任意国家。
service	string	可选	服务名称,例如"telegram",保存在会话上供你参考
webhookUrl	string	可选	OTP 到达时接收 POST 的 HTTPS URL(代替轮询)
expiresIn	integer	可选	会话 TTL,单位为秒(60–1800,默认 600)

响应

200 OK会话已创建:响应体包含 sessionId、number 和 expiresAt

402 Payment Required余额不足

503 Service Unavailable没有可用的在线号码

请求示例

curl -X POST https://www.kartesim.com/api/v1/otp/request \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram", "country": 212}'

响应示例

{ "sessionId": "cma4x9k3b0000abc123", "number": "212661234567", "status": "PENDING", "expiresAt": "2026-06-01T00:20:00.000Z" }

GET/api/v1/otp/:sessionId

轮询 OTP 会话的状态和验证码。SMS 到达后返回提取出的 OTP 验证码。每 5–10 秒轮询一次。

响应

200 OK — PENDINGstatus: "PENDING", otp: null — 仍在等待

200 OK — RECEIVEDstatus: "RECEIVED", otp: "84729" — 验证码已就绪

200 OK — EXPIREDstatus: "EXPIRED" — 超时时间内没有 SMS

200 OK — CANCELLEDstatus: "CANCELLED" — 你取消了会话

请求示例

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/otp/cma4x9k3b0000abc123

响应示例

{ "sessionId": "cma4x9k3b0000abc123", "status": "RECEIVED", "number": "212661234567", "otp": "84729", "smsBody": "Your code is 84729" }

POST/api/v1/otp/:sessionId/cancel

取消一个 PENDING 会话。全额退还 OTP 费用。已收到 OTP 的会话无法取消。

响应

200 OKstatus: "CANCELLED", refunded: 0.10 — 余额已退还

409 Conflict会话不处于 PENDING 状态,无法取消

404 Not Found会话未找到或属于其他账户

请求示例

curl -X POST -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/otp/cma4x9k3b0000abc123/cancel

响应示例

{ "sessionId": "cma4x9k3b0000abc123", "status": "CANCELLED", "refunded": "0.1000" }

POST你的 webhook URL(服务器推送)

OTP 到达时,我们会向你在创建会话时提供的 webhookUrl 发送 POST。这是轮询之外的另一种方式:你的服务器会自动收到 OTP,无需调用 getStatus。

Payload

POST 到你的 webhookUrl

{
  "event":      "otp.received",
  "sessionId":  "cma4x9k3b0000abc123",
  "status":     "RECEIVED",
  "number":     "212661234567",
  "otp":        "84729",
  "smsBody":    "Your Telegram code is 84729",
  "receivedAt": "2026-06-21T12:00:00.000Z"
}

安全

生产环境中你的 webhook URL 必须是 HTTPS,HTTP URL 会被拒绝。
我们会发送 X-Webhook-Signature: sha256=... 请求头(HMAC-SHA256)。请验证它以确认请求真实。
遇到 5xx 时,我们会在 2 秒后重试一次。你的端点应尽快返回 200。
你的端点必须是幂等的,重试时可能出现重复投递。

GET/api/partner/rentals

获取你账户下所有有效的号码租用。

响应

200 OK有效号码租用的 JSON 数组

401 UnauthorizedAPI 密钥无效或缺失

请求示例

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/rentals

响应示例

[
  {
    "id": "cuid...",
    "phoneNumber": "1234567890",
    "countryCode": 1,
    "expiresAt": "2026-06-25T10:00:00.000Z",
    "daysRemaining": 26
  }
]

GET/api/partner/sms?simNumber=1234567890

获取你租用的号码收到的最新 SMS 消息。可选择按指定的 simNumber 筛选。

参数

名称	类型	必填	说明
simNumber	string	可选	筛选指定租用号码的 SMS

响应

200 OK近期 SMS 消息的 JSON 数组

401 UnauthorizedAPI 密钥无效或缺失

请求示例

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/sms

响应示例

[
  {
    "id": "cuid...",
    "simNumber": "1234567890",
    "fromNumber": "Twilio",
    "body": "Your verification code is 49201",
    "receivedAt": "2026-05-29T15:30:00.000Z"
  }
]

号码租用

号码租用让你在固定租期内独占使用一张真实的 SIM 卡。该号码收到的每条 SMS 都会实时送达你的账户。你可以直接通过 API 或合作伙伴门户租用号码。

周期	时长	说明
按日	24 小时	最适合短期验证活动
按周	7 天	最适合持续使用一个稳定的号码
按月	30 天	最适合长期专属号码使用

工作原理

调用 GET /api/v1/numbers/available 浏览可用号码(已打码)。
选择号码和计费周期,然后调用 POST /api/v1/numbers/rent 即可立即租用。
你的余额会立即扣除。响应中会返回完整的未打码电话号码。
你租用的号码收到的所有 SMS 都会实时显示在 SMS 记录 下。
到期时号码会自动释放。未使用的时间不予退款。

GET/api/v1/numbers/available

浏览可供租用的号码。号码已打码(例如+212 6** *** **7),让你在下单前可以看到国家和运营商。可选择按国家代码筛选。

参数

名称	类型	必填	说明
country	number	可选	ITU 国家代码(例如 212)。省略或使用 0 表示任意国家。

响应

200 OK包含可用号码列表和总数的 JSON

401 UnauthorizedAPI 密钥无效或缺失

429 Too Many Requests超出速率限制(30 req/min)

请求示例

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/numbers/available?country=212

响应示例

{
  "available": [
    {
      "phoneId":      "clx...",
      "maskedNumber": "+212 6** *** **7",
      "countryCode":  212,
      "country":      "Morocco",
      "carrier":      "Orange",
      "pricing": { "daily": null, "weekly": 2.50, "monthly": 8.00 }
    }
  ],
  "total": 1
}

POST/api/v1/numbers/rent

自助租用号码。以原子操作扣除你的余额并创建独占租用。成功时返回完整的(未打码)电话号码。

参数

名称	类型	必填	说明
phoneId	string	必填	来自 /api/v1/numbers/available 的端口 ID
billingCycle	string	必填	DAILY \| WEEKLY \| MONTHLY
cycles	number	可选	预付的计费周期数(1–12,默认 1)
autoRenew	boolean	可选	到期时自动续租(默认 false)

响应

200 OK租用已创建:响应中包含完整电话号码

402 Payment Required余额不足,或该周期未配置价格

409 Conflict号码刚被其他合作伙伴租用,请换一个号码重试

401 UnauthorizedAPI 密钥无效或缺失

请求示例

curl -X POST -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"phoneId":"clx...","billingCycle":"MONTHLY","cycles":1}' \
  https://www.kartesim.com/api/v1/numbers/rent

响应示例

{
  "rentalId":     "cly...",
  "phoneNumber":  "+212661234567",
  "countryCode":  212,
  "carrier":      "Orange",
  "billingCycle": "MONTHLY",
  "pricePerCycle": 8.00,
  "cycles":        1,
  "totalCharged":  8.00,
  "autoRenew":     false,
  "startedAt":    "2026-06-21T20:00:00.000Z",
  "expiresAt":    "2026-07-21T20:00:00.000Z"
}

GET/api/partner/rentals

获取你账户下所有有效的号码租用。

响应

200 OK有效号码租用的 JSON 数组

401 UnauthorizedAPI 密钥无效或缺失

请求示例

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/rentals

响应示例

[
  {
    "id": "cuid...",
    "phoneNumber": "+212661234567",
    "maskedNumber": "+212 6** *** **7",
    "countryCode": 212,
    "expiresAt": "2026-06-25T10:00:00.000Z",
    "daysRemaining": 26
  }
]

号码专属于你的账户。在你的租期内,号码绝不会被共享或重新分配。整个租期所需的余额在租用时收取。如果你请求的号码在浏览和租用之间被占用,你会收到 409,请换一个号码重试。

支持的国家

使用 getCountries 获取当前列表。常用国家代码:

代码	国家	代码	国家
0	任意(自动分配)	7	俄罗斯
212	摩洛哥	33	法国
1	美国	44	英国
49	德国	34	西班牙
966	沙特阿拉伯	971	阿拉伯联合酋长国
20	埃及	216	突尼斯

错误参考

响应	含义
BAD_KEY	API 密钥无效、已撤销或缺失
BAD_ACTION	未知的 action 或缺少必填参数
TOO_MANY_REQUESTS	超出速率限制:每分钟 120 次请求
NO_NUMBERS	没有符合你 OTP 请求的在线端口
NO_BALANCE	余额不足,无法创建 OTP 会话
STATUS_WAIT_CODE	尚未收到 OTP,请继续轮询
STATUS_OK:code	已收到 OTP,数字验证码在冒号之后
STATUS_CANCEL	会话已过期或已取消
ACCESS_NUMBER:id:num	OTP 会话已创建,后面是会话 ID 和电话号码
ACCESS_CANCEL	会话已取消,余额已退还
ACCESS_READY	会话已确认收到/已确认

kartesim 合作伙伴文档。如需申请 API 密钥或咨询租用,请联系你的客户经理。