首页 / Java 平台（cloud-java） / SIM/eSIM 供应商接入契约
SIM/eSIM 供应商接入契约
卡、套餐、IMEI 池、异步通知、CDR 与批处理任务的供应商适配边界和对账要求。
供应商接入边界
esim卡接口文档.md 收录了 EIOTCLUB 的外部文档入口，覆盖实体卡、Cloud eSIM、套餐、IMEI 池、异步通知、CDR 和批量任务。该文件是供应商能力索引，不包含稳定的请求/响应字段；实际接入必须以当期受控的供应商 OpenAPI、签名算法、错误码和回调文档冻结版本。
第三方订单状态、用量和回调是外部事实；平台内的设备绑定、用户订阅权益和支付订单是内部事实。不能因为供应商“套餐购买成功”就直接假设用户权益、设备网络或本地订单已完成。
能力分组
| 能力组 | 外部能力 | 平台适配器职责 |
|---|---|---|
| 卡与产品查询 | 单卡/批量卡、所属产品、可订购套餐、套餐记录、可切换运营商 | 分页、限流、字段标准化、外部 ID 映射、快照时间和查询失败降级。 |
| 套餐与订单 | 订购、退款、订单状态、可退款金额、套餐转移、Cloud eSIM 购买/退款 | 以内部请求 ID 发起，保存外部订单号；用异步回调/查询确认终态，不把同步受理当成功。 |
| IMEI 池与卡控制 | 机卡绑定/解绑、IMEI 池添加/解除、锁卡/解锁、取消当前会话、批量重置 | 执行前校验设备归属和权限；高风险操作双重审计、幂等、审批或限流。 |
| 用量与运营商 | 刷新用量、流量预警、CDR、运营商切换、卡片断网通知 | 区分实时查询、异步刷新和滞后 CDR；按卡/周期做去重与趋势告警。 |
| 批处理与回调 | 批量重置、任务状态查询、订购/退款/套餐生效/锁卡等通知 | 验签、重放保护、持久化原文摘要、幂等消费、可重放死信和定时补查。 |
状态、回调与对账
- 内部业务创建请求和幂等键，检查设备归属、内部订阅/套餐规则和操作权限。
- 适配器调用供应商，保存供应商名称、API 版本、外部请求/订单/任务 ID、受理时间和脱敏摘要。
- 若同步响应只是“受理”，状态进入
PENDING_EXTERNAL；等待经签名验证的回调或轮询查询终态。 - 终态到达后更新“供应商订单/卡状态”事实，并通过 Outbox 驱动内部用量、告警、设备配置或财务对账；消费者必须可幂等。
- 定时对账比较内部记录、回调记录、供应商订单查询和 CDR/用量快照，形成差异单并人工闭环。
推荐将外部状态标准化为 REQUESTED、ACCEPTED、PROCESSING、SUCCEEDED、FAILED、UNKNOWN、REVERSED，同时保存原始供应商状态值，避免丢失语义。
安全与验收
- 签名密钥由密钥管理服务托管；请求日志、回调日志和工单不得输出完整 ICCID、IMSI、Token、签名串或客户凭证。
- 回调必须校验签名、时间窗、来源和幂等键；主动查询只作为补偿，不能覆盖已经确认的终态而不留审计。
- 批量操作需要明确输入总数、成功/失败明细、可查询的外部任务 ID，以及重试不会重复扣费/订购的证明。
- 验收至少覆盖：重复回调、乱序回调、外部超时、外部成功但回调丢失、部分批量失败、CDR 延迟、退款反转和供应商不可用。
相关知识：sim SIM 卡、SIM 卡生命周期流程、数据一致性机制。