
合作伙伴可以使用 heyatli.com 和 Atli 小组件所用的同一套 Atli eSIM API。你可以为网站、应用或机器人构建自己的目的地列表、套餐选择、结账和安装界面。Atli 提供套餐目录,通过自己的 Stripe 账户处理付款,并发放 eSIM。
这个 API 不使用应用级的 API 密钥,身份验证通过每个用户各自的令牌完成。你的服务器用唯一的设备 ID 或通过 OAuth 替每个用户登录,再代表这个用户发出 API 请求。每个访客账户都需要自己的设备 ID,你的应用必须安全地保存它。
Sandbox、生产环境和 OpenAPI 文件
| Sandbox | 生产环境 | |
|---|---|---|
| API | https://api-staging.heyatli.com | https://api.heyatli.com |
| OpenAPI 文件 | https://api-staging.heyatli.com/openapi.yaml | https://api.heyatli.com/openapi.yaml |
| 付款页面 | https://staging.heyatli.com/pay | https://heyatli.com/pay |
Sandbox 使用独立的账户和测试付款,不会产生真实扣款。它的 eSIM 来自测试运营商,无法安装到手机上,Sandbox 上的销售也永远不计分成。本指南中所有创建账户和订单的示例都使用 Sandbox 端点。切换到生产环境时,把 API 的基础 URL 改为 https://api.heyatli.com。partners.heyatli.com/zh/dev/api 上的参考文档可以在两者之间切换。

API 错误采用统一的格式,包含 code、英文的 message,以及与 Atli 支持团队排查问题时使用的 trace_id。用 code 来决定你的应用如何处理错误、显示什么样的提示。message 字段可以保留在你的日志中。
登录、报价、兑换优惠券和 eSIM 同步都有频率限制,被拒绝的请求会返回 429,并在 Retry-After 中给出以秒为单位的等待时间。
你可以从 OpenAPI 规范生成一个带类型的 API 客户端,不必逐个编写 HTTP 请求:
docker run --rm -v "$PWD:/out" \
openapitools/openapi-generator-cli generate \
-i https://api.heyatli.com/openapi.yaml \
-g typescript-fetch -o /out/atli-sdk把 typescript-fetch 换成 python、java、csharp、php 或 swift6 即可。Go 需要用 go --additional-properties=enumClassPrefix=true。
第 1 步:创建用户
你可以为每个用户创建一个 Atli 访客账户,无需用户注册。为每个用户生成一个唯一的 UUID(比如用 crypto.randomUUID()),并安全地保存在这个用户的账户记录里。
请把设备 ID 当作敏感凭据对待,因为任何拿到它的人都能以这个用户的身份登录。
从你的服务器用它登录。Atli 没见过的 ID 会创建一个访客账户,已知的 ID 则重新登录:
curl https://api-staging.heyatli.com/login \
-H 'Content-Type: application/json' \
-d '{ "device_id": "YOUR_DEVICE_ID" }'{
"token": "eyJhbGci…",
"refresh_token": "…",
"expires_in": 900,
"session_id": "…",
"user": { "id": "…", "email": null }
}每个需要用户身份的调用,都要以 Authorization: Bearer YOUR_TOKEN 的形式带上 token。它的有效期是 15 分钟。在到期前不久,用 POST /refresh 和 refresh_token 续期。刷新接口返回的新令牌字段叫 access_token,不叫 token。请确保你的集成读取的是正确的字段,以免最初的令牌过期时出现身份验证失败。每次都要保存新的刷新令牌,因为每次刷新都会返回一个新的,并让旧的作废。如果两个都丢了,就用设备 ID 重新登录。
访客可以购买和使用 eSIM。但有些分享 eSIM 和优惠券需要正式账户,API 会拒绝访客使用,并返回 gift_sign_in_required 之类的错误码。要给访客绑定邮箱,把它的令牌和 device_id 发给 POST /auth/email/otp,再用 POST /auth/email/verify 确认。用 WhatsApp 或 Telegram 登录也能以同样的方式升级访客账户。无论哪种方式,访客已有的 eSIM 和账户数据都会保留。如果漏了 device_id,或者用的邮箱已经有 Atli 账户,这个人就会进到另一个账户里。
第 2 步:把用户关联到你的合作伙伴代码
在每个新用户第一次报价之前,把他关联到你的代码:
curl https://api-staging.heyatli.com/user/referral/redeem \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "code": "YOUR_PARTNER_CODE" }'result 字段表示调用结果:ok 表示用户已成功关联,already 表示对方已有推荐人,notnew 表示对方以前购买过,own 表示这是你自己的推荐代码,notfound 表示找不到该代码。只有没有推荐人、也没有购买记录的人才能被关联,而且只能关联一次。创建用户之后,马上调用这个接口。
关联是永久的。如果你的代码带折扣,用户的第一张 eSIM 会自动享受,不需要你再次发送代码。这层关联能给你带来什么收益,见推广联盟指南。
第 3 步:展示套餐并获取报价
GET /explore/plans 返回完整的目录,包括可购买的目的地、套餐、价格和流量额度。它不需要令牌,所以你的服务器在任何人有账户之前就能列出套餐。要从你的服务器调用它,因为 API 会用 403 拒绝来自其他网站的浏览器请求。传入 currency,再用 destination(JP、europe)或 category(local、regional、global)筛选:
curl 'https://api-staging.heyatli.com/explore/plans?currency=EUR&destination=JP'套餐的 id 就是你要购买的 product_id。报价时带上 store: true,就能拿到一个 quote_id:
curl https://api-staging.heyatli.com/plan/quote \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "product_id": "THE_PACKAGE_ID",
"currency": "EUR",
"store": true }'{
"subtotal_cents": 1500,
"total_discount_cents": 150,
"net_total_cents": 1350,
"currency": "EUR",
"quote_id": "…",
"expires_at": "…"
}把 net_total_cents 作为最终价格展示。保存的报价在 30 分钟后过期,所以要在用户进入结账时再生成报价。每个用户同一时间只保留一份报价,新的会替换旧的。
target_esim_id 用来给用户已有的某张 eSIM 充值。不传的话,套餐会加到用户的默认 eSIM 上。如果用户还没有 eSIM,或者默认 eSIM 的网络不卖这个套餐,套餐就会放到一张新的 eSIM 上。对于用自己的 Atli 账户登录的用户,报价里的 new_esim 会说明是哪种情况。访客的报价不包含这个字段。对访客来说,在展示安装步骤之前,先把完成订单上的 eSIM 和 GET /esims 列出的 eSIM 对比一下。
auto_apply_best_voucher 会使用用户持有的、符合条件且价值最高的优惠券,points_to_redeem 让用户兑换积分,这些积分在 Atli 的应用中显示为 Atli Credits。一笔订单只能用一种折扣。通过你的链接得到的推荐折扣优先,报价自己会挑的任何优惠券都比不过它。用 voucher_code 指定的优惠券会取代推荐折扣;同时指定优惠券和 referral_code 会失败,并返回 cannot_combine_voucher_and_referral。只有两种折扣都不适用时,积分才会计入。
第 4 步:创建订单并收款
用 quote_id 购买保存的报价。订单的套餐、折扣和价格都取自这份报价。如果此后总价变动超过 1%,购买会失败并返回 price_changed,这时重新报价即可。
每份报价只能用于一笔订单。如果购买请求被再次提交,无论是误操作还是超时后的重试,API 都会返回已有的订单,而不会重复创建。请求里还必须带上 idempotency_key;不使用保存的报价、直接按 product_id 购买时,它可以防止重复下单。
curl https://api-staging.heyatli.com/plan/purchase \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "quote_id": "THE_QUOTE_ID",
"idempotency_key": "A_NEW_UUID" }'{
"order_id": "…",
"client_secret": "pi_…_secret_…",
"sealed_secret": "eyJhbGciOiJFQ0RILUVTIi…",
"key_id": "…",
"seal_signature": "…",
"options": "{\"message\":\"Plan for Japan\",\"lang\":\"en\"}",
"options_signature": "…",
"total_amount_cents": 1350,
"status": "pending_payment"
}client_secret 属于 Atli 账户上的一个 Stripe PaymentIntent。用它挂载 Stripe 的 Payment Element。可发布密钥由你的服务器从 GET /stripe/config 读取,再和 client_secret 一起交给页面。不要硬编码这个密钥,因为 Sandbox 和生产环境的密钥不同;也不要在页面里获取它,因为 API 会拒绝来自其他网站的浏览器请求:
const stripe = Stripe(publishable_key);
const elements = stripe.elements({ clientSecret: order.client_secret });
elements.create('payment').mount('#pay');
const { error } = await stripe.confirmPayment({
elements,
confirmParams: { return_url: window.location.href },
redirect: 'if_required',
});client_secret 只能传给正在付款的那个用户的会话,也不要写进日志。Stripe 确认付款后,通知 Atli 发放 eSIM:
curl https://api-staging.heyatli.com/plan/fulfill-payment \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "order_id": "THE_ORDER_ID" }'如果这个调用失败,不要再次扣款。已付款的订单,Atli 会自行完成。
款项通过 Atli 的 Stripe 账户收取,所以客户银行卡账单上显示的是 Atli 的名字,退款和争议也由 Atli 处理。如果想在你自己的表单里提供 Apple Pay 和 Google Pay,等你的集成有了实际销量之后,写信到 [email protected]。已保存的卡也走同一个购买接口:加上 payment_method_id 就用那张卡扣款,加上 save_card: true 则保存新卡供下次使用。
在 Atli 付款页面上付款
对于无法显示 Stripe 付款表单的集成,比如 WhatsApp 机器人、Telegram 机器人、语音应用或 AI 助手,可以把用户引导到 Atli 托管的付款页面。用购买接口返回的三个密封值生成这个链接。如果购买接口还返回了 options 和 options_signature,也一并传过去,付款页面就会在银行卡表单上方显示一行字,比如“Plan for Japan”,用的是你在请求里指定的语言:
const link = new URL('https://staging.heyatli.com/pay');
link.search = new URLSearchParams({
type: 'payment_intent',
sealed_secret: order.sealed_secret,
key_id: order.key_id,
seal_signature: order.seal_signature,
...(order.options && {
options: Buffer.from(order.options).toString('base64url'),
options_signature: order.options_signature,
}),
}).toString();付款页面会显示订单总额,并支持银行卡、Apple Pay 和 Google Pay 付款。然后用 order_id 调用 POST /plan/fulfill-payment,并反复调用,直到订单变为已付款。只有这个调用才能确认付款,因为付款页面会把仍在处理中的付款显示为成功。
生成付款链接时,请遵守以下要求:
sealed_secret、key_id、seal_signature和options_signature按 API 返回的原样传递,编码交给URLSearchParams处理。options是例外:不要改动其中的 JSON,直接对它做 base64url 编码。绝不要把明文的client_secret放进链接。- Sandbox 的值只能在
staging.heyatli.com/pay打开,生产环境的值只能在heyatli.com/pay打开。 - 这个链接是为某个人的订单付款用的。只发给账户本人,也不要写进日志。
- 不要把链接存起来以后再用。新的购买会取消之前待付款的订单及其链接。
brand=none会隐藏 Atli 标志。lang和theme设置页面的语言和外观。跳转参数只接受 heyatli.com 或其子域名上的https地址,所以要提醒用户付完款后回到你的聊天里。- 页面上的“取消”按钮不会关闭订单。要取消订单,调用
POST /orders/{id}/cancel。
同一个页面也可以只保存卡而不付款:用 POST /user/payment-methods/setup-intent 创建设置,把 type 设为 setup_intent 来生成链接,再用 POST /user/payment-methods/confirm 保存。partners.heyatli.com/zh/dev/payment-widget 可以用一个全新的 Sandbox 访客打开一次测试付款。
第 5 步:展示 eSIM 及其安装链接
付款后,eSIM 不一定能马上安装。查询订单状态,直到 esim 对象包含安装信息。订单处理期间,向用户显示相应的状态提示:
curl 'https://api-staging.heyatli.com/fulfillment/status-updates?order_id=THE_ORDER_ID' \
-H 'Authorization: Bearer YOUR_TOKEN'{
"order_id": "…",
"status": "completed",
"esim": {
"id": "…",
"iccid": "…",
"lpa_address": "…",
"activation_code": "…",
"qr_string": "…"
}
}paid 状态表示付款已确认,completed 表示 eSIM 及其套餐已经开通。用户借助另一台设备安装时,把 qr_string 渲染成二维码。对于直接在手机上安装 eSIM 的用户,提供 iPhone 或 Android 的安装链接,它们会打开手机自带的 eSIM 设置:
const lpa = `LPA:1$${esim.lpa_address}$${esim.activation_code}`;
const carddata = encodeURIComponent(lpa);
const iphone = `https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=${carddata}`;
const android = `https://esimsetup.android.com/esim_qrcode_provisioning?carddata=${carddata}`;也可以只给用户一个链接,把这些都交给它:https://heyatli.com/my/esim,其中 lpa 设为 base64url 编码的 qr_string,iccid 设为这张 eSIM 的 ICCID。页面会显示二维码、两个一键安装链接和手动输入所需的信息;带上 ICCID 时,还会显示套餐和剩余流量。用户不需要 Atli 账户。可以在路径里加上语言,比如 /ja/my/esim;Sandbox 的 eSIM 要用 staging.heyatli.com。任何拿到链接的人都能安装这张 eSIM,所以只发给要使用它的人。
用户接下来会看到什么,见我们的 iPhone 和 Android 安装指南。
GET /esims 会列出用户的 eSIM,包括安装信息、套餐以及截至上次同步的已用流量。POST /esims/{id}/sync 会向网络请求最新数据。每次同步请求都会访问网络运营商,并受频率限制。需要时再请求最新的用量信息,不要按固定间隔自动轮询。
让用户用自己的 Atli 账户登录
如果你的应用要让用户使用自己的 Atli 账户,而不是访客账户,Atli 提供 OAuth 2.1:带 PKCE(S256)的授权码流程、轮换的刷新令牌和令牌撤销。用户通过 heyatli.com 进行身份验证并授权访问,因此你的应用不会接触到他们的 Atli 密码。
在 partners.heyatli.com/zh/dev/oauth/clients 注册客户端。一个账户最多可以拥有 10 个客户端:public 客户端用于手机应用,confidential 客户端用于能保管密钥的服务器。网页不能自己发起令牌请求,因为除非 Atli 把客户端标记为受信任,API 会拒绝来自其他网站的浏览器请求,所以网页应用要配一个服务器和一个 confidential 客户端。只有你自己拥有的客户端才能获取 API 的令牌,而你的账户需要有邮箱地址才能拥有客户端。
从授权服务器的元数据中获取 OAuth 端点,不要把它们硬编码在代码里:
curl https://api.heyatli.com/.well-known/oauth-authorization-server访问令牌的有效期是 15 分钟。每次刷新都会返回一个新的刷新令牌,必须用它替换你的应用安全存储中的旧令牌。Atli 为你的账户开启自动关联之后,通过你的客户端登录的用户就能自动关联到你。在此之前,按第 2 步的做法,用 POST /user/referral/redeem 和他们的访问令牌自己完成关联。
分享、优惠券和群组
要购买可分享的 eSIM,请在报价时带上 is_gift: true,并把 max_claims 设为 1 到 20 之间的值。订单完成后,从 GET /gifts/sent 获取 claim_url。POST /rewards/voucher/redeem 会把优惠券加到用户的账户里。Atli Groups 群组的成员可以带上 group_id 报价,并用群组的卡购买。partners.heyatli.com/zh/dev/api 逐步讲解了这些流程中的每一个,并附有代码。
常见问题
Atli API 有 API 密钥吗?
我需要自己的 Stripe 账户吗?
GET /stripe/config 拿到的 Atli 可发布密钥,银行卡信息直接发给 Stripe,不会经过你的服务器,也不会经过 API。客户能用 Apple Pay 或 Google Pay 付款吗?
怎样给用户已有的 eSIM 加流量?
target_esim_id 设为那张 eSIM,然后照常购买。套餐会加到用户已有的 eSIM 上,所以不需要安装任何新东西。如果那张 eSIM 的网络不卖这个套餐,API 会拒绝,并返回 incompatible_esim。付款成功了,但发放 eSIM 的调用失败了,怎么办?
GET /fulfillment/status-updates,直到 eSIM 出现即可。在哪里可以不花真钱测试?
api-staging.heyatli.com。用 Stripe 的测试卡 4242 4242 4242 4242,有效期填任意未来日期,安全码随意填写。Sandbox 有自己独立的账户。


