eSIM Exchange Business Integration API Specification v1.2

1. Standard Description

1.1 Basic Explanation

To ensure the security of server transmission information, the following security mechanisms are adopted:

• 1. All interfaces use HTTPS secure links.
• 2. Officially assigned customer authentication AuthKey, used for authorization and encryption, with a maximum length of 32.
• 3. Officially assigned encryption key AuthSecret, used for encryption, with a maximum length of 50.
• 4. Ensures the security of requests through SHA-256.

1.2 Interface Standards

Request Protocol: HTTPS

Request Method: GET / POST

Data Transfer Format: application/json

Request Header Parameters:

AuthKey: Customer authentication key, type String

Certification: Encrypted string, type String (Result of SHA-256 encryption of accumulated AuthKey+AuthSecret)

2. Interface List

2.1 Purchase Redeem Code

Request URL: https://api.iroamly.shop/openapi/purchaseCode

Request Method: POST

Request Parameters:

email: Email, type: String

productList: Product collection, type: Object[]

productList Fields:

productCode: Product code, type: String

quantity: Quantity, type: Int

Example Parameters:

Copy code
{
  "email": "[email protected]",
  "productList": [
    {
      "productCode": "m8hed7h2fed",
      "quantity": 2
    },
    {
      "productCode": "cn88beg9edj",
      "quantity": 1
    }
  ]
}

Example Return:

Copy code
{
  "code": 1,
  "msg": "success",
  "orderId": "xxx-xxxx-sd9hn8df333" // Order number, can be used to query redeem code
}

2.2 Query Redeem Code

Request URL: https://api.iroamly.shop/openapi/codeQuery

Request Method: POST

Request Parameters:

orderId: Order number, type: String

Example Parameters:

Copy code
{
  "orderId": "xxx-xxx-dh239jdu28",
}

Example Return:

Copy code
{
  "code": 1,
  "msg": "success",
  "data": [
    {
      "productCode": "m8hed7h2fed",
      "redeemCode": "3cd2m3f23f3f3",
      "expire_at": "2024-06-30", // Expiry date
      "status": 0
    },
    {
      "productCode": "v2jf28dj2w",
      "redeemCode": "d923j29ef2323",
      "expire_at": "2024-06-30",
      "status": 2
    }
  ]
}

2.3 Redeem QR Code

(Note: Will be sent to the specified email, the more you redeem, the longer the waiting time)

Request URL: https://api.iroamly.shop/openapi/redeemQRcode

Request Method: POST

Request Parameters:

email: Email, type: String

codeList: Collection of redeem codes, type: Object[]

codeList Fields:

redeemCode: Redeem code, type: String

Example Parameters:

Copy code
{
  "email": "[email protected]",
  "codeList": [
    {
      "redeemCode": "m8hed7h2fed",
    },
    {
      "redeemCode": "cn88beg9edj",
    }
  ]
}

Example Return:

Copy code
{
  "code": 1,
  "msg": "success",
}

2.4 Query QR Code

Request URL: https://api.iroamly.shop/openapi/qrcodeQuery

Request Method: POST

Request Parameters:

code: Redeem code, type: String

Example Parameters:

Copy code
{
  "redeemCode": "m8hed7h2fed",
}

Example Return:

Copy code
{
  "code": 1,
  "msg": "success",
  "redeemCode": "m8hed7h2fed",
  "qrcode": "https://dsfjigewafe/qrcode.jpg"
}

3. Response Status Code Definitions

• - Code: 1, Description: Success
• - Code: 2, Description: Request parameter authentication failed
• - Code: 3, Description: Parameters not filled as required
• - Code: 4, Description: Product code does not exist
• - Code: 5, Description: Insufficient balance
• - Code: 6, Description: Query information does not exist
• - Code: 7, Description: Redeem code has been redeemed or does not exist
• - Code: -1, Description: Request failed

4. Redeem Code Status Definitions

• - 0: Not redeemed
• - 1: Redeeming
• - 2: Redeemed
• - 3: Redemption failed