esimaccess-api

eSIM Access API 技能

与 eSIM Access API 交互，全面管理 eSIM 生命周期。

何时使用此技能

在用户遇到以下情况时使用此技能：

• 询问 eSIM 操作：订购、充值、取消、状态查询
• 提到 ICCID、订单号、二维码或数据用量
• 想查询账户余额或列出可用的数据套餐
• 询问漫游、旅行数据套餐或移动网络连接
• 需要管理 eSIM 配置文件（暂停、恢复、撤销）
• 想为 eSIM 状态通知配置 webhook
• 询问如何取消并重新签发 eSIM（退款／更换工作流）
• 提及 eSIM Access API 或 api.esimaccess.com

示例提示词

• “查询我的 eSIM Access 余额”
• “日本有哪些可用套餐？”
• “订购一份美国的 5GB 套餐”
• “查询订单 B26041021130002 的状态”
• “ICCID 89852240810733629810 已使用多少数据？”
• “为我的 eSIM 再充值 5GB”
• “取消这张未使用的 eSIM 并退款”
• “设置订单通知 webhook”

快速参考

• 基础 URL：https://api.esimaccess.com/api/v1/open
• 身份验证：HMAC-SHA256 签名请求头 — accessCode 同时用作 API 标识符和签名密钥（参见 references/api-reference.md）
• 价格：API 值 / 10,000 = 美元（例如，18000 = $1.80）
• 流量：字节（1073741824 = 1 GB）
• 凭据：从 https://console.esimaccess.com/developer/index 获取 accessCode

操作

读取（安全）

操作	端点	用途
check_balance	/balance/query	以美元计的账户余额
list_regions	/package/list	所有支持的国家／地区
list_packages	/package/list	按国家／地区或代码查询产品
list_topup_packages	/package/list	ICCID 的充值选项
check_order_status	/esim/query	订单详情 + ICCID
check_esim_status	/esim/query	完整的 eSIM 配置文件信息
check_data_usage	/esim/usage/query	数据用量统计
query_webhook	/webhook/query	当前 webhook 配置

写入（会产生费用或修改状态）

操作	端点	用途
create_order	/esim/order	购买新的 eSIM
apply_topup	/esim/topup	为现有 eSIM 添加流量
cancel_esim	/esim/cancel	取消未使用的 eSIM（退款）
suspend_profile	/esim/suspend	暂时停用
unsuspend_profile	/esim/unsuspend	重新启用已暂停的配置文件
revoke_profile	/esim/revoke	永久停用（不退款）
send_sms	/esim/sendSms	向 eSIM 发送短信
setup_webhook	/webhook/save	配置通知 URL

复合工作流

操作	用途
refund_and_reissue	取消未使用的 eSIM，确认退款，并订购同一套餐的替换卡

关键规则

1. 订购流程：create_order 会返回 orderNo。每隔 3 秒轮询一次 check_order_status（重试 4 次）以获取 ICCID。ORDER_STATUS webhook 可作为备用方式。
2. 充值：使用 esimTranNo（而非 ICCID）。supportTopUpType === 2 表示符合条件。过期后无法充值。
3. 取消与撤销：取消适用于未使用的 eSIM（RELEASED/GOT_RESOURCE），并会退款。撤销适用于已激活的 eSIM，不退款。
4. 用量查询：需要 esimTranNo，而非 ICCID。如有需要，先通过 /esim/query 查询 ICCID。
5. 短信：使用 message 字段（而非 content）。仅适用于已激活的 eSIM。

使用任意语言进行身份验证

references/api-reference.md 文件包含 Node.js 和 Python 的 HMAC-SHA256 身份验证示例。请让 AI 根据其中记录的签名算法，使用你偏好的语言生成身份验证代码。

测试

node scripts/test-esim-api.mjs <accessCode>

安装

任何 AI Agent（通过 Skills CLI）

npx skills add esimaccess/esimaccess-api

手动安装

从 https://app.esimaccess.com/public/skill/ 下载，并放入 Agent 的 skills 目录。

文件

文件	用途
SKILL.md	本文件 - 技能定义
scripts/test-esim-api.mjs	15 个端到端 API 测试
references/api-reference.md	完整的 API 文档：端点、身份验证、状态、Webhook、错误代码