指南

如何将 Atli eSIM API 集成到你的网站或应用中

没有 API 密钥:你的每个用户都会有一个 Atli 访客账户。内容包括如何把它关联到你的合作伙伴代码、报价、收款和交付 eSIM。

一条请求 Atli API 购买端点的 curl 命令,旁边是一部显示 Atli 付款页面的手机,还有在行李箱旁拿着手机的带翅膀的蓝色 Atli 吉祥物

合作伙伴可以使用 heyatli.com 和 Atli 小组件所用的同一套 Atli eSIM API。你可以为网站、应用或机器人构建自己的目的地列表、套餐选择、结账和安装界面。Atli 提供套餐目录,通过自己的 Stripe 账户处理付款,并发放 eSIM。

这个 API 不使用应用级的 API 密钥,身份验证通过每个用户各自的令牌完成。你的服务器用唯一的设备 ID 或通过 OAuth 替每个用户登录,再代表这个用户发出 API 请求。每个访客账户都需要自己的设备 ID,你的应用必须安全地保存它。

Sandbox、生产环境和 OpenAPI 文件

Sandbox生产环境
APIhttps://api-staging.heyatli.comhttps://api.heyatli.com
OpenAPI 文件https://api-staging.heyatli.com/openapi.yamlhttps://api.heyatli.com/openapi.yaml
付款页面https://staging.heyatli.com/payhttps://heyatli.com/pay

Sandbox 使用独立的账户和测试付款,不会产生真实扣款。它的 eSIM 来自测试运营商,无法安装到手机上,Sandbox 上的销售也永远不计分成。本指南中所有创建账户和订单的示例都使用 Sandbox 端点。切换到生产环境时,把 API 的基础 URL 改为 https://api.heyatli.com。partners.heyatli.com/zh/dev/api 上的参考文档可以在两者之间切换。

Atli API 主要流程图:创建用户、获取报价、购买并付款、获取 eSIM、安装和追踪用量,另有正式账户、已保存的卡和群组卡、充值、折扣和分享等可选分支

API 错误采用统一的格式,包含 code、英文的 message,以及与 Atli 支持团队排查问题时使用的 trace_id。用 code 来决定你的应用如何处理错误、显示什么样的提示。message 字段可以保留在你的日志中。

登录、报价、兑换优惠券和 eSIM 同步都有频率限制,被拒绝的请求会返回 429,并在 Retry-After 中给出以秒为单位的等待时间。

你可以从 OpenAPI 规范生成一个带类型的 API 客户端,不必逐个编写 HTTP 请求:

Bash
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 则重新登录:

Bash
curl https://api-staging.heyatli.com/login \
  -H 'Content-Type: application/json' \
  -d '{ "device_id": "YOUR_DEVICE_ID" }'
JSON
{
  "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 步:把用户关联到你的合作伙伴代码

在每个新用户第一次报价之前,把他关联到你的代码:

Bash
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)筛选:

Bash
curl 'https://api-staging.heyatli.com/explore/plans?currency=EUR&destination=JP'

套餐的 id 就是你要购买的 product_id。报价时带上 store: true,就能拿到一个 quote_id:

Bash
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 }'
JSON
{
  "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 购买时,它可以防止重复下单。

Bash
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" }'
JSON
{
  "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 会拒绝来自其他网站的浏览器请求:

JavaScript
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:

Bash
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”,用的是你在请求里指定的语言:

JavaScript
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 对象包含安装信息。订单处理期间,向用户显示相应的状态提示:

Bash
curl 'https://api-staging.heyatli.com/fulfillment/status-updates?order_id=THE_ORDER_ID' \
  -H 'Authorization: Bearer YOUR_TOKEN'
JSON
{
  "order_id": "…",
  "status": "completed",
  "esim": {
    "id": "…",
    "iccid": "…",
    "lpa_address": "…",
    "activation_code": "…",
    "qr_string": "…"
  }
}

paid 状态表示付款已确认,completed 表示 eSIM 及其套餐已经开通。用户借助另一台设备安装时,把 qr_string 渲染成二维码。对于直接在手机上安装 eSIM 的用户,提供 iPhone 或 Android 的安装链接,它们会打开手机自带的 eSIM 设置:

JavaScript
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 端点,不要把它们硬编码在代码里:

Bash
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 密钥吗?
没有。令牌标识的是一个人,而不是一个应用。你的服务器用设备 ID 或通过 OAuth 替每个用户登录,然后以这个用户的身份调用 API。
我需要自己的 Stripe 账户吗?
不需要。订单通过 Atli 的 Stripe 账户扣款。你的表单使用从 GET /stripe/config 拿到的 Atli 可发布密钥,银行卡信息直接发给 Stripe,不会经过你的服务器,也不会经过 API。
客户能用 Apple Pay 或 Google Pay 付款吗?
能。Atli 的付款页面两种都支持。如果要在你自己的 Stripe 表单里提供,等你的集成有了实际销量之后,写信到 [email protected]。
怎样给用户已有的 eSIM 加流量?
为新套餐报价时,把 target_esim_id 设为那张 eSIM,然后照常购买。套餐会加到用户已有的 eSIM 上,所以不需要安装任何新东西。如果那张 eSIM 的网络不卖这个套餐,API 会拒绝,并返回 incompatible_esim。
付款成功了,但发放 eSIM 的调用失败了,怎么办?
不要再次扣款。已付款的订单 Atli 会自行完成,继续轮询 GET /fulfillment/status-updates,直到 eSIM 出现即可。
在哪里可以不花真钱测试?
在 Sandbox 上,地址是 api-staging.heyatli.com。用 Stripe 的测试卡 4242 4242 4242 4242,有效期填任意未来日期,安全码随意填写。Sandbox 有自己独立的账户。