본문으로 건너뛰기
iRoamly Shop
개발자

API 문서

iRoamly Shop API 참조: 인증, 요금제, 구매 및 전달, 갱신 및 사용량.

개요

기본 설명

서버 전송 정보의 보안을 위해 다음 보안 메커니즘을 적용합니다:

  1. 1.모든 인터페이스는 HTTPS secure 보안 연결을 통해 통신합니다.
  2. 2.API 인증에 사용하는 발급된 AuthKey(최대 32자).
  3. 3.요청 해시 생성에 사용하는 발급된 AuthSecret(최대 50자).
  4. 4.요청 인증에는 SHA-256 해시를 사용합니다.
개요

인터페이스 규격

기본 경로:https://api.iroamly.shop/
요청 프로토콜:HTTPS
요청 메서드:GET / POST
데이터 전송 형식:application/json

요청 헤더 파라미터:

AuthKey: 고객 인증 키, 문자열(String) 유형

Certification: AuthKey+AuthSecret을 이 순서대로 이어 붙인 값의 SHA-256 해시를 담은 문자열.

/common/getPlanItem에는 AuthKey 또는 Certification 헤더가 필요하지 않습니다.

API 엔드포인트

지역별 요금제 목록 조회

요청 URL:https://api.iroamly.shop/common/getPlanItem
요청 메서드:GET

AuthKey 또는 Certification 헤더가 필요하지 않습니다.

요청 파라미터:

파라미터설명유형
regionISO2 코드, 국가 이름(대소문자 구분 없음) 또는 표준화된 형식(예: united-states)을 사용할 수 있습니다.String

응답 형식:

성공: HTTP 200. 요금제는 data.list로 반환됩니다.

항상 HTTP 200을 반환합니다. 데이터가 없으면 data.list는 빈 배열이고 msg는 Success입니다.

응답 필드 설명:

필드설명유형
plan요금제 이름(지역, 유형, 데이터 용량, 기간 포함).String
productCode구매 또는 조회에 사용하는 고유 요금제 ID.String
data데이터 용량(예: 10GB, Unlimited, 500MB).String
type요금제 유형(예: Total, Daily, Unlimited).String
plan_type요금제 분류(예: default).String
package_type패키지 유형(예: Data Only).String
duration일 단위 유효 기간(예: 10).String
speed네트워크 속도(예: 4G / 5G).String
operator지원 통신사(예: T-Mobile/AT&T).String
region공식 지역 이름(예: United States).String
region_index표준화된 지역 식별자(하이픈을 사용한 소문자, 예: united-states).String
credit요금제 가격(크레딧 단위, 미국 달러 아님).Float
remark추가 참고 사항(예: 속도 제한 규칙).String
created_at요금제 생성 타임스탬프(ISO 8601 형식).String
요청 예시
"https://api.iroamly.shop/common/getPlanItem?region=US"
반환 예시
{
  "code": 0,
  "data": {
    list:[
     {
       "plan": "United States-eSIM-10GB-10 Days-Total",
       "productCode": "iRoamly-unite-584535",
       "data": "10GB",
       "type": "Total",
       "package_type": "Data Only",
       "duration": "10",
       "speed": "4G / 5G",
       "operator": "T-Mobile/AT&T",
       "region": "United States",
       "region_index": "united-states",
       "credit": 6.43,
       "remark": "After accumulating 10GB, the speed will be reduced to 128 Kbps",
       "created_at": "2025-05-16T04:02:31Z"
     }
    ]
  }
}
API 엔드포인트

QR 코드 직접 구매

요청 URL:https://api.iroamly.shop/openapi/purchaseqrcode
요청 메서드:POST

요청 파라미터:

파라미터설명유형
emailQR 코드를 받을 메일 주소입니다. 비어 있으면 이메일을 보내지 않습니다.String
productList상품 모음Object[]

productList 필드:

필드설명유형
plan요금제 이름. plan 또는 productCode 중 하나를 입력하세요.String
productCode요금제 ID(지역별 요금제 목록 조회의 productCode). productCode 또는 plan 중 하나를 입력하세요.String
quantity수량Int
테스트 요금제:iRoamly-Test-10GB

다음 단계: QR 코드 조회(https://api.iroamly.shop/openapi/qrcodeQuery)로 QR 코드를 가져오세요

파라미터 예시
{
  "email": "2m827n32d@gmail.com",
  "productList": [
    {
      "plan": "United States-eSIM-10GB-10 Days-Total",
      "quantity": 2
    },
    {
      "plan": "Albania-10GB-15 Days-Total",
      "quantity": 1
    }
  ]
}
반환 예시
{
  "code": 1,
  "data": {
    "orderId": "Open-Global-DXDWFBKG578913",
    "redeem_list": [
      {
        "productCode": "",
        "plan": "United States-eSIM-10GB-10 Days-Total",
        "redeemCode": "tjMxpYfvk5dFMQg",
        "status": 0,
        "expire_at": "2026-03-01"
      },
      {
        "productCode": "",
        "plan": "United States-eSIM-10GB-10 Days-Total",
        "redeemCode": "gKPzYhseX1wRmSi",
        "status": 0,
        "expire_at": "2026-03-01"
      },
      {
        "productCode": "",
        "plan": "Albania-10GB-15 Days-Total",
        "redeemCode": "sLSHNkAv2ojbNBG",
        "status": 0,
        "expire_at": "2026-03-01"
      }
    ]
  },
  "msg": "success"
}
API 엔드포인트

교환 코드 구매

요청 URL:https://api.iroamly.shop/openapi/purchaseCode
요청 메서드:POST

요청 파라미터:

파라미터설명유형
email이메일String
productList상품 모음Object[]

productList 필드:

필드설명유형
plan요금제 이름. plan 또는 productCode 중 하나를 입력하세요.String
productCode요금제 ID(지역별 요금제 목록 조회의 productCode). productCode 또는 plan 중 하나를 입력하세요.String
quantity수량Int
테스트 요금제:iRoamly-Test-10GB
파라미터 예시
{
  "email": "2m827n32d@gmail.com",
  "productList": [
    {
      "plan": "United States-eSIM-10GB-10 Days-Total",
      "quantity": 2
    },
    {
      "plan": "Albania-10GB-15 Days-Total",
      "quantity": 1
    }
  ]
}
반환 예시
{
  "code": 1,
  "msg": "success",
  "orderId": "xxx-xxxx-sd9hn8df333" // Order number, can be used to query redeem code
}
API 엔드포인트

교환 코드 조회

요청 URL:https://api.iroamly.shop/openapi/codeQuery
요청 메서드:POST

요청 파라미터:

파라미터설명유형
orderId주문 번호String
파라미터 예시
{
  "orderId": "xxx-xxx-dh239jdu28",
}
반환 예시
{
  "code": 1,
  "msg": "success",
  "data": [
    {
      "productCode": "m8hed7h2fed",
      "redeemCode": "3cd2m3f23f3f3",
      "expire_at": "2024-06-30", // Expiry date
      "plan": "United States-eSIM-10GB-10 Days-Total",
      "status": 0
    },
    {
      "productCode": "v2jf28dj2w",
      "redeemCode": "d923j29ef2323",
      "expire_at": "2024-06-30",
      "plan": "Albania-10GB-15 Days-Total",
      "status": 2
    }
  ]
}
API 엔드포인트

QR 코드로 전환

(참고: 전환 후 QR 코드는 지정한 이메일 주소로 전송됩니다. 수량이 많을수록 처리 시간이 길어질 수 있습니다.)

요청 URL:https://api.iroamly.shop/openapi/redeemQRcode
요청 메서드:POST

요청 파라미터:

파라미터설명유형
email이메일String
codeList교환 코드 모음Object[]

productList 필드:

필드설명유형
redeemCode교환 코드String
파라미터 예시
{
  "email": "2m827n32d@gmail.com",
  "codeList": [
    {
      "redeemCode": "m8hed7h2fed",
    },
    {
      "redeemCode": "cn88beg9edj",
    }
  ]
}
반환 예시
{
  "code": 1,
  "msg": "success",
}
API 엔드포인트

QR 코드 조회

요청 URL:https://api.iroamly.shop/openapi/qrcodeQuery
요청 메서드:POST

요청 파라미터:

파라미터설명유형
redeemCode교환 코드String

응답 필드 설명:

필드설명유형
redeemCode교환 코드String
qrcodeQR 코드 이미지 URLString
status교환 코드 상태(교환 코드 상태 정의 참조)Int
qrcode_contentQR 코드 내용(LPA 활성화 문자열, 예: LPA:1$…)String
iscouldrenewaleSIM 갱신 가능 여부: 1 - 갱신 가능 0 - 갱신 불가Int
파라미터 예시
{
  "redeemCode": "m8hed7h2fed",
}
반환 예시
{
  "code": 1,
  "msg": "success",
  "redeemCode": "m8hed7h2fed",
  "qrcode": "https://dsfjigewafe/qrcode.jpg"
}
API 엔드포인트

갱신 요금제 상태 조회

요청 URL:https://api.iroamly.shop/openapi/getRenewPlanStatus
요청 메서드:POST

요청 파라미터:

파라미터설명유형
redeemCode교환 코드String

응답 필드 설명:

응답의 최상위 code는 교환 코드의 갱신 가능 여부를 나타냅니다: 0 - 갱신 가능, -1 - 갱신 불가. 갱신 옵션은 data.renewList에 나열됩니다:

필드설명유형
renewtype갱신 유형: 0 - 현재 요금제가 만료되면 활성화 1 - 즉시 활성화(남은 데이터 삭제) 2 - 지정한 시간에 활성화Int
starttime선택 가능한 활성화 기간의 시작: 선택할 수 있는 가장 이른 활성화 시간(갱신 유형 2).String
endtime선택 가능한 활성화 기간의 끝: 선택할 수 있는 가장 늦은 활성화 시간(갱신 유형 2).String
파라미터 예시
{
  "redeemCode": "3cd2m3f23f3f3",
}
반환 예시
{
  "code": 0,
  "data": {
    "renewList": [
      {
        "renewtype": 1,
        "starttime": "0001-01-01T00:00:00Z",
        "endtime": "0001-01-01T00:00:00Z"
      },
      {
        "renewtype": 2,
        "starttime": "2025-08-04 06:13:08",
        "endtime": "2025-09-20 14:23:51"
      }
    ],
    "lasttime": "0001-01-01T00:00:00Z"
  },
  "msg": "Success"
}
API 엔드포인트

코드 갱신

(참고: 갱신 시 선택한 요금제의 갱신 그룹은 원래 요금제의 갱신 그룹과 일치해야 합니다.)

요청 URL:https://api.iroamly.shop/openapi/renewcode
요청 메서드:POST

요청 파라미터:

파라미터설명유형
redeemCode갱신할 코드String
plan갱신 요금제String
renewtype갱신 유형: 0 - 현재 요금제가 만료되면 활성화 1 - 즉시 활성화(남은 데이터 삭제) 2 - 지정한 시간에 활성화Int
renewtime적용 날짜 및 시간(필수). 형식: YYYY-MM-DDTHH:mm:ssZString
파라미터 예시
{
  redeemCode: "DEF456UVW",
  plan: "basic_yearly",
  renewtype: 0,
  renewtime: "2024-12-31T23:59:59Z"
}
반환 예시
{
  code: 1,
  data: {
    orderId: "Open-Global-DXDWFBKG578913",
    plan: "United States-eSIM-10GB-10 Days-Total",
    redeemCode: "tjMxpYfvk5dFMQg",
    status: 0,
    expire_at: "2026-03-01"
  },
  msg: "success"
}
API 엔드포인트

요금제 통계 조회

요청 URL:https://api.iroamly.shop/openapi/getnetworkflow
요청 메서드:GET

요청 파라미터:

파라미터설명유형
redeemCode조회할 교환 코드.String

응답 필드 설명:

파라미터설명유형
status0 - 비활성 1 - 활성 2 - 만료 9 - 무효Int
flow_use청구 주기 내 사용한 데이터(MB 단위)String
flow_total청구 주기의 총 데이터(MB 단위 또는 unlimited)String
start_data요금제 시작 시간String
end_data요금제 종료 시간String
installDevice설치된 기기String
installCount설치 횟수String
installTime설치 시간String
올바른 예시
{
  code: 1,
  status: 0,
  flow_use: "300",
  flow_total: "1024",
  start_data: "2025-10-25T15:04:05Z07:00",
  end_data: "2025-11-25T15:04:05Z07:00",
  installDevice: "iPhone 15",
  installCount: "1",
  installTime: "2025-10-25T15:04:05Z06:00"
}
잘못된 예시
{
  code: -1,
  msg: "error message"
}
정의

응답 상태 코드 정의

코드설명
1성공
2요청 파라미터 인증 실패
3파라미터가 요구 사항대로 제공되지 않았습니다
4상품 코드가 존재하지 않음
5크레딧 부족
6교환 코드가 존재하지 않음
7교환 코드가 이미 교환되었거나 존재하지 않음
-1요청 실패

성공 시 code는 1입니다. 단, /common/getPlanItem과 /openapi/getRenewPlanStatus는 성공 시 code 0을 반환합니다.

정의

교환 코드 상태 정의

상태설명
0교환 안 됨
1교환 중
2교환됨
3교환 실패
코드 참조

교환 코드 구매(Python)

python
import requests
import json
import hashlib

# URL for the request
url = "https://api.iroamly.shop/openapi/purchaseCode"

# Provided AuthKey and AuthSecret, remember to replace them with real values
auth_key = "YOUR_AUTH_KEY_HERE"
auth_secret = "YOUR_AUTH_SECRET_HERE" 


# Calculating Certification
combined = auth_key + auth_secret
certification = hashlib.sha256(combined.encode()).hexdigest()

# Header parameters for the request
headers = {
    "Content-Type": "application/json",
    "AuthKey": auth_key,
    "Certification": certification
}

# Example data for the request body
data = {
    "email": "2m827n32d@gmail.com",
    "productList": [
        {
            "productCode": "m8hed7h2fed2398dsnh",
            "quantity": 2
        },
        {
            "productCode": "cn88beg9edjdfj2sj0a",
            "quantity": 1
        }
    ]
}

# Sending POST request
response = requests.post(url, headers=headers, data=json.dumps(data))

# Printing the response content
print(response.text)

# Example of response
{
    "code":1,
    "msg":"success",
    "orderId":"xxx-xxxx-sd9hn8df333"
}
코드 참조

교환 코드 조회(Python)

python
import requests
import json
import hashlib

# URL for the request
url = "https://api.iroamly.shop/openapi/codeQuery"

# Provided AuthKey and AuthSecret, remember to replace them with real values
auth_key = "YOUR_AUTH_KEY_HERE"
auth_secret = "YOUR_AUTH_SECRET_HERE" 


# Calculating Certification
combined = auth_key + auth_secret
certification = hashlib.sha256(combined.encode()).hexdigest()

# Header parameters for the request
headers = {
    "Content-Type": "application/json",
    "AuthKey": auth_key,
    "Certification": certification
}

# Example data for the request body
data = {
    "orderId":"xxx-xxx-dh239jdu28"
}

# Sending POST request
response = requests.post(url, headers=headers, data=json.dumps(data))

# Printing the response content
print(response.text)

# Example of response
{
 "code":1,
 "data":
    [
     {"productCode":"m8hed7h2fed2398dsnh","redeemCode":"nDb4TDCn6vMhbQv","status":0,"expire_at":"2024-07-04"},
     {"productCode":"m8hed7h2fed2398dsnh","redeemCode":"oA7AWAmo76BwoGj","status":0,"expire_at":"2024-07-04"},
     {"productCode":"cn88beg9edjdfj2sj0a","redeemCode":"XRdDeSxBVNbvCpU","status":0,"expire_at":"2024-07-04"}
    ],
 "msg":"success"
}
코드 참조

QR 코드로 전환(Python)

python
import requests
import json
import hashlib

# URL for the request
url = "https://api.iroamly.shop/openapi/redeemQRcode"

# Provided AuthKey and AuthSecret, remember to replace them with real values
auth_key = "YOUR_AUTH_KEY_HERE"
auth_secret = "YOUR_AUTH_SECRET_HERE" 


# Calculating Certification
combined = auth_key + auth_secret
certification = hashlib.sha256(combined.encode()).hexdigest()

# Header parameters for the request
headers = {
    "Content-Type": "application/json",
    "AuthKey": auth_key,
    "Certification": certification
}

# Example data for the request body
data = {
    "email": "2m827n32d@gmail.com",
    "codeList": [
        {
            "redeemCode": "nDb4TDCn6vMhbQv",
        },
        {
            "redeemCode": "XRdDeSxBVNbvCpU",
        }
    ]
}

# Sending POST request
response = requests.post(url, headers=headers, data=json.dumps(data))

# Printing the response content
print(response.text)

# Example of response
{"code":1,"msg":"success"}
코드 참조

QR 코드 조회(Python)

python
import requests
import json
import hashlib

# URL for the request
url = "https://api.iroamly.shop/openapi/qrcodeQuery"

# Provided AuthKey and AuthSecret, remember to replace them with real values
auth_key = "YOUR_AUTH_KEY_HERE"
auth_secret = "YOUR_AUTH_SECRET_HERE" 


# Calculating Certification
combined = auth_key + auth_secret
certification = hashlib.sha256(combined.encode()).hexdigest()

# Header parameters for the request
headers = {
    "Content-Type": "application/json",
    "AuthKey": auth_key,
    "Certification": certification
}

# Example data for the request body
data = {
    "redeemCode":"XRdDeSxBVNbvCpU"
}

# Sending POST request
response = requests.post(url, headers=headers, data=json.dumps(data))

# Printing the response content
print(response.text)

# Example of response
{
 "code":1,
 "qrcode":"https:/code.tokyoesim.com/20231220/1703048857317.65625d0a779f4598d55d77bda43ecd80.png",
 "msg":"success",
 "redeemCode":"XRdDeSxBVNbvCpU"
}