가이드

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가 따로 있어야 하며, 애플리케이션은 이 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/ko/dev/api의 API 문서에서 두 환경을 오갈 수 있습니다.

사용자 만들기, 견적 받기, 구매 및 결제, eSIM 받기, 설치와 사용량 확인으로 이어지는 Atli API 주요 흐름 지도와 정식 계정, 카드 저장과 그룹 카드, 충전, 할인, 공유로 갈라지는 선택 분기

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 게스트 계정을 만들 수 있습니다. crypto.randomUUID() 같은 함수로 사용자마다 고유한 UUID를 생성해 그 사용자의 계정 레코드에 안전하게 저장하세요.

기기 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 크레딧으로 표시됩니다. 주문 하나에는 한 종류의 할인만 적용됩니다. 내 링크로 연결된 추천 할인이 가장 먼저이고, 견적이 스스로 고를 바우처보다 우선합니다. 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를 마운트하세요. 게시 가능 키(publishable key)는 내 서버가 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가 호스팅하는 결제 페이지로 안내할 수 있습니다. 링크는 구매 응답에 들어 있던 봉인된 값 세 개로 만드세요. 구매 응답에 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/ko/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}`;

아니면 이 모든 일을 하는 링크 하나를 사용자에게 건네세요. https://heyatli.com/my/esim에서 lpa에는 base64url로 인코딩한 qr_string을, iccid에는 eSIM의 ICCID를 넣으면 됩니다. 이 페이지는 QR 코드, 원탭 링크 두 개, eSIM을 직접 입력할 때 쓰는 정보를 보여 주고, 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/ko/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 Group의 멤버는 group_id로 견적을 받아 그룹 카드로 구매할 수 있습니다. partners.heyatli.com/ko/dev/api에는 이 흐름들이 코드와 함께 단계별로 정리되어 있습니다.

자주 묻는 질문

Atli API에 API 키가 있나요?
아니요. 토큰은 애플리케이션이 아니라 사람을 식별합니다. 내 서버가 사용자마다 기기 ID나 OAuth로 로그인한 뒤 그 사용자로서 API를 호출합니다.
Stripe 계정이 따로 있어야 하나요?
아니요. 주문은 Atli의 Stripe 계정으로 결제됩니다. 내 결제 폼은 GET /stripe/config에서 받은 Atli의 게시 가능 키를 쓰고, 카드 정보는 내 서버나 API를 거치지 않고 곧바로 Stripe로 갑니다.
고객이 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로 테스트하세요. 유효기간은 미래 날짜 아무것이나, 보안 코드는 아무 숫자나 넣으면 됩니다. 샌드박스에는 별도의 계정이 있습니다.