> ## Documentation Index
> Fetch the complete documentation index at: https://developers.mioesim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with the MIOeSIM API

> Make your first MIOeSIM API call in minutes: authenticate, browse eSIM products, and place a working order that returns real activation codes and ICCIDs.

This guide walks you through the minimum steps required to go from zero to a placed order: obtain credentials, authenticate, browse the product catalog, and submit an order. By the end you will have a working integration pattern you can extend for your platform.

<Steps>
  <Step title="Get your credentials">
    Contact MIOeSIM to request a reseller account. You will receive:

    * A **phone number** (your login username)
    * A **password**
    * A **secret key** used to sign every request

    Keep these credentials secure. Do not commit them to source control.
  </Step>

  <Step title="Authenticate and obtain a token">
    Before calling any endpoint, you must obtain a session token by calling `POST /api_order/login`. The request requires a `sign` computed from your credentials (see [Authentication](/authentication) for the full algorithm).

    **Compute the sign for the login request:**

    For a login call with `phonenumber=13800000000` and `password=mypassword`, sort the params alphabetically, concatenate, append the secret key, then MD5 hash the result:

    ```
    password=mypasswordphonenumber=13800000000
    ```

    Append the secret key and hash:

    ```
    password=mypasswordphonenumber=138000000001234567890qwertyuiopasdfghjklzxc
    → MD5 → <sign value>
    ```

    **Make the login request:**

    ```bash theme={null}
    curl --request POST \
      --url "https://bpm.mioesim.com/api_order/login" \
      --header "Content-Type: application/json" \
      --data '{
        "phonenumber": "13800000000",
        "password": "mypassword",
        "sign": "<computed-sign>"
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "code": 1,
      "message": "Successful",
      "data": {
        "token": "29281-9EFE5E410BEF5300DD15E3830BD65601"
      }
    }
    ```

    <Note>
      Tokens are valid for **2 hours**. Cache the token locally and refresh it before it expires to avoid unnecessary re-authentication on every request.
    </Note>
  </Step>

  <Step title="Browse available products (SKUs)">
    Call `GET /api_esim/getSkus` to retrieve the list of available eSIM products. Include your token and a request signature as query parameters.

    ```bash theme={null}
    curl "https://bpm.mioesim.com/api_esim/getSkus?token=29281-9EFE5E410BEF5300DD15E3830BD65601&sign=<computed-sign>"
    ```

    **Example response (truncated):**

    ```json theme={null}
    {
      "code": "0",
      "message": "success",
      "data": [
        { "skuid": 156, "display": "Africa", "countryCode": "99918" },
        { "skuid": 124, "display": "Asia 30", "countryCode": "99115" },
        { "skuid": 26,  "display": "Japan",   "countryCode": "392" }
      ]
    }
    ```

    Note the `skuid` values — you will need one to fetch packages in the next step.
  </Step>

  <Step title="Get packages for a SKU">
    Call `GET /api_esim/getPackages` with a `skuId` to list available data plans and pricing for that product.

    ```bash theme={null}
    curl "https://bpm.mioesim.com/api_esim/getPackages?token=29281-9EFE5E410BEF5300DD15E3830BD65601&skuId=26&sign=<computed-sign>"
    ```

    **Example response (truncated):**

    ```json theme={null}
    {
      "code": "0",
      "message": "success",
      "data": {
        "skuid": 26,
        "displayEn": "Japan",
        "esimPackageDtoList": [
          {
            "flows": 1, "days": 3, "unit": "GB",
            "price": 4.49, "priceid": 441,
            "flowType": 0, "supportDaypass": 0,
            "apiCode": "392-0-3-1-G"
          }
        ],
        "supportCountry": ["Japan"]
      }
    }
    ```

    Note the `priceid` — you need it to place an order.

    <Tip>
      Call `GET /api_esim/verifyResource` before placing an order to confirm that the requested package has sufficient card inventory.
    </Tip>
  </Step>

  <Step title="Place an order">
    Call `POST /api_esim/addEsimOrder` with your token, the `skuId`, `priceId`, quantity, and `backInfo=1` to receive full card details in the response.

    ```bash theme={null}
    curl -X POST https://bpm.mioesim.com/api_esim/addEsimOrder \
      -d "token=29281-9EFE5E410BEF5300DD15E3830BD65601" \
      -d "skuId=26" \
      -d "priceId=441" \
      -d "count=1" \
      -d "backInfo=1" \
      -d "sign=<computed-sign>"
    ```

    **Response:**

    ```json theme={null}
    {
      "code": "0",
      "message": "success",
      "data": {
        "orderNum": "EP20240124000013",
        "display": "Japan",
        "status": 0,
        "cardApiDtoList": [
          {
            "iccid": "934801019851134300",
            "sm_dp_address": "ais.prod.ondemandconnectivity.com",
            "activationCode": "SEW7JEBMFGPRVSPD",
            "code": "LPA:1$ais.prod.ondemandconnectivity.com$SEW7JEBMFGPRVSPD",
            "activateBefore": "2024-02-24(GMT+8)",
            "data": "1GB",
            "validity": 3,
            "pdfUrl": null,
            "apn": "internet"
          }
        ]
      }
    }
    ```

    Deliver the `code` (LPA string) to your customer — they enter it in their device settings to install the eSIM. On iOS, generate a QR code from the `sm_dp_address` and `activationCode`. Use `pdfUrl` (when present) to send a ready-made PDF with the QR code.
  </Step>
</Steps>