# USIM 下游分销商接入与操作指南

## 1 · 申请与采购

注册账户并验证邮箱，在代理商入口提交申请。管理员审批后，可按获准的模式采购批量卡密或 API SIM 套餐。价格、数量及有效期以确认订单为准。

批量卡密适合交付独立接码凭证；API SIM 套餐适合通过自有服务器提供接收服务。报价有效期内完成付款，按订单约定开通。付款后显示号码待分配时，请保留订单并联系支持，无需再次付款。

## 2 · 卡密交付与客户使用

基础卡密 - CDK Starter 与增强卡密 - CDK Plus 的价格、可提取条数、接码窗口及未激活有效期，请查看资费页并以订单为准。增强卡密使用同一个号码，不限制发送方：可以向 Gmail、X、TikTok 等不同平台同时请求，也可向同一平台多次请求；所有发送方共用总额度，短信是否送达取决于对应平台。首次提取完成整张卡密交付，其余额度为赠送。

客户在首页填写卡密、获取号码，再向目标平台发起短信请求。分配号码后开始接码窗口倒计时，提取验证码不会重置。短信到达后先显示发送方，正文保持隐藏，点击提取验证码并确认后完成交付；取消确认不收费。请在有效期内使用。

首次提取后，在页面显示的选择期限内，已登录并验证邮箱的客户可按购买时保存的 PAYG 报价冻结点数，预约同号续用。原卡密时段和赠送次数不变，不会自动续费。

## 3 · 费用、付款与订单

按次接码 PAYG 先冻结当前报价的点数，接码窗口内确认提取验证码时才扣除；未提取到期按有效期规则释放。卡密和批发报价以当前产品及确认订单为准。

每笔新充值点数自成功入账起独立计算有效期，充值确认页显示天数，账户明细显示各笔到期日。可用余额与冻结余额分别展示。付款后请在订单页面查看进度；人工核款渠道需管理员核实实际到账。

已确认到账但交付待处理的订单可由支持人员恢复处理，请勿重复付款。补发卡密、点数纠错由授权管理员核对原订单处理。

## 4 · 开通 API 套餐

选择获准的套餐、SIM 数量和租期，核对报价后付款。开通后在代理商中心查看号码、到期时间及密钥管理。数量、短信额度与价格以购买快照为准。

在已开通套餐旁生成 API Key，明文仅显示一次。将密钥保存在自有服务器受限环境配置中；不要放入浏览器、URL、公开仓库或日志。密钥绑定套餐，更换密钥不会延长租期。

USIM_API_BASE=https://api.usim.dev/api/v1。套餐密钥仅用于获准的号码与短信查询，不能操作个人钱包。

## 5 · 开发者接入

由自有后端验证客户及订单后调用 USIM，只返回该客户获准访问的数据。读取号码：GET /api/v1/rental/subscriptions/{id}/numbers；读取短信：GET /api/v1/rental/subscriptions/{id}/messages?after={delivery_id}。

先持久保存消息并去重，再推进游标；建议每 5 秒轮询。短信源端 received_at 决定归属。接口版本是技术路径的一部分。

开发自有主题或站点时，用 GET /api/platform/rules 获取当前商品点数、条数、接码窗口与点数有效期，勿在页面固定商业参数。已创建任务使用响应中的 receive_policy 与 continuation_policy；已有订单和卡密使用购买快照，不用当前资费覆盖原权益。

个人接码通过 /api/v2/sessions 创建任务，messages 仅返回发送方预览；明确确认收费后调用 messages/{message}/reveal，提交 confirm_charge:true。不得通过 CSS 隐藏已取得的正文冒充未提取。

写请求使用 Idempotency-Key，网络重试保持同键同内容。下游任务 Webhook 使用 X-Webhook-Id、X-Webhook-Timestamp、X-Webhook-Signature；签名为 v1= 加 HMAC-SHA256(timestamp + '.' + 原始正文) 的十六进制结果。校验五分钟窗口、常量时间比较、按事件去重，持久接收后再返回 2xx。API SIM 套餐使用游标查询。

```javascript
const response = await fetch(process.env.USIM_API_BASE + '/rental/subscriptions/' + encodeURIComponent(process.env.USIM_SUBSCRIPTION_ID) + '/numbers', {
  headers: { Authorization: 'Bearer ' + process.env.USIM_API_KEY, Accept: 'application/json' },
  signal: AbortSignal.timeout(10000), redirect: 'error', cache: 'no-store'
});
if (!response.ok) throw new Error('USIM HTTP ' + response.status);
const numbers = (await response.json()).data;
```

```php
$url = rtrim(getenv('USIM_API_BASE'), '/') . '/rental/subscriptions/' . rawurlencode(getenv('USIM_SUBSCRIPTION_ID')) . '/numbers';
$ch = curl_init($url);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10, CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('USIM_API_KEY'), 'Accept: application/json']]);
$body = curl_exec($ch);
if ($body === false || curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200) throw new RuntimeException('USIM request failed');
$numbers = json_decode($body, true, 32, JSON_THROW_ON_ERROR)['data'];
curl_close($ch);
```

## 6 · 运维、权限与异常处理

401 检查凭据，403 检查作用域与有效期，409 检查状态或幂等冲突，422 修正参数，429 与临时 5xx 按 Retry-After 或有界指数退避重试。付款回跳、客户端声称已付款不能作为到账依据。

测试无效或过期凭据、其他组织 ID、重复写入和断网重试。号码仅能在授权范围及租期内使用。撤销旧密钥前先部署新密钥。

## 7 · 支持与交付核对

保留订单号、套餐 ID、请求 ID、发生时间和错误代码，通过工单提交问题。请勿上传完整密钥、支付密码或不必要的短信正文。

卡密导出和密钥明文应安全保存。发现到账未交付或号码待分配，请提交对应订单，工作人员核实后处理。