ガイド

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 が必要で、あなたのアプリケーションで安全に保管する必要があります。

サンドボックス、本番、OpenAPI ファイル

サンドボックス本番
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

サンドボックスでは本番とは別のアカウントとテスト決済を使うので、実際の請求は発生しません。サンドボックスの eSIM はテスト用の通信事業者のものなのでスマホにはインストールできず、サンドボックスでの売上が報酬の対象になることもありません。このガイドでアカウントや注文を作成するコード例は、すべてサンドボックスのエンドポイントを使っています。本番では、API のベース URL を https://api.heyatli.com に変更してください。partners.heyatli.com/ja/dev/api のリファレンスでは、両者を切り替えて表示できます。

Atli API の主な流れの図。ユーザーの作成、見積もり、購入と支払い、eSIM の受け取り、インストールと使用量の確認に加え、通常のアカウント、保存済みのカードとグループのカード、チャージ、割引、シェアへの任意の分岐

API のエラーは一貫した形式で返り、code、英語の message、Atli のサポートと問題を調べるときに使う trace_id が含まれます。アプリケーションでエラーをどう処理し、どのようなメッセージを表示するかは、code をもとに判断してください。message フィールドはログに残しておけます。

サインイン、見積もり、バウチャーの利用、eSIM の同期にはレート制限があり、拒否されたリクエストには 429 と、待つべき秒数を示す Retry-After が返ります。

個々の HTTP リクエストを書く代わりに、OpenAPI の仕様から型付きの API クライアントを生成できます。

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 にアクセスできる人は誰でもそのユーザーとして認証できるため、デバイス ID は機密性の高い認証情報として扱ってください。

サーバーから、この 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 }
}

ユーザー認証が必要な呼び出しでは、毎回 token を Authorization: Bearer YOUR_TOKEN として送ります。有効期間は15分です。切れる少し前に、POST /refresh と refresh_token で更新してください。更新のレスポンスでは、新しいトークンの名前が token ではなく access_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 が返す一覧と照らし合わせてください。

auto_apply_best_voucher はユーザーが持つ利用可能なバウチャーのうち最も価値の高いものを適用し、points_to_redeem ではユーザーがポイントを利用できます。このポイントは、Atli のアプリでは Atliクレジットとして表示されます。ひとつの注文に使える割引は1種類だけです。あなたのリンクから付いた紹介割引が最優先で、見積もりが自分で選ぶバウチャーよりも先に来ます。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 と一緒にページに渡します。キーはサンドボックスと本番で異なるのでハードコードせず、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 の決済ページで支払う

WhatsApp のボット、Telegram のボット、音声アプリケーション、AI アシスタントなど、Stripe の決済フォームを表示できない連携では、ユーザーを Atli がホストする決済ページに案内できます。リンクは、購入で返された封印済みの3つの値から作ります。購入で 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 は絶対にリンクに入れないでください。
  • サンドボックスの値は 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/ja/dev/payment-widget では、新しく作ったサンドボックスのゲストでテスト決済を開けます。

ステップ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 を QR コードとして描画します。スマホに直接 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}`;

あるいは、これを全部こなすリンクを1つだけユーザーに渡す方法もあります。https://heyatli.com/my/esim に、lpa として base64url にした qr_string を、iccid として eSIM の ICCID を付けます。このページには QR コード、ワンタップでインストールできる2つのリンク、手動で入力するための情報が表示され、ICCID があればプランとデータ残量も表示されます。Atli のアカウントは要りません。/ja/my/esim のようにパスに言語を入れることができ、サンドボックスの eSIM には staging.heyatli.com を使います。リンクがあれば誰でも eSIM をインストールできるので、その eSIM を使う本人にだけ送ってください。

その後にユーザーに表示される画面は、iPhone と Android のガイドで説明しています。

GET /esims は、ユーザーの eSIM を、インストール情報、プラン、最後の同期時点でのデータ使用量とともに一覧で返します。POST /esims/{id}/sync は、ネットワークに最新の数値を問い合わせます。同期のリクエストは毎回通信事業者に問い合わせるため、レート制限の対象になります。一定の間隔で自動的にポーリングするのではなく、必要なときに最新の使用量を取得してください。

自分の Atli アカウントでサインインしてもらう

ゲストではなく本人の Atli アカウントを使うアプリ向けに、Atli は OAuth 2.1 を提供しています。PKCE(S256)付きの認可コードフローで、リフレッシュトークンのローテーションとトークンの無効化に対応しています。ユーザーの認証とアクセスの許可は heyatli.com で行われるため、あなたのアプリケーションがユーザーの Atli パスワードを扱うことはありません。

クライアントは partners.heyatli.com/ja/dev/oauth/clients で登録します。クライアントはアカウントごとに10個まで持てます。スマホアプリ向けの public と、シークレットを安全に保管できるサーバー向けの confidential です。API は、Atli が信頼済みとしたクライアントでない限り、ほかのウェブサイトからのブラウザのリクエストを拒否するので、ウェブページが自分でトークンを取得する呼び出しはできません。ウェブアプリにはサーバーと 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/ja/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 が自動で完了させるので、eSIM が現れるまで GET /fulfillment/status-updates のポーリングを続けます。
本物のお金を使わずにテストするには?
サンドボックス(api-staging.heyatli.com)で、Stripe のテストカード 4242 4242 4242 4242 を使います。有効期限は未来の日付、セキュリティコードは何でもかまいません。サンドボックスには本番とは別のアカウントがあります。