# PA05-41 - eSIM Account Activation (eSIMアカウント開通)

## Overview

Handles eSIM activation requests from OEM including new activations, MNP transfers, and reissues.

- Activation is **asynchronous** - not immediate; completion is notified via the "eSIM Request Completion Notification File"
- For file format details, refer to the "CSV File Format Definition (MVNO Edition)" sheet "eSIM依頼完了通知ファイル"
- When `aladinOperated` is `"10"` (operated) **and** `addKind` is not `"N"` (new), the API returns `400-356` (unsupported pattern)

---

## Request

### Method

`POST` (JSON format, URL-encoded)

### URL

```
https://[host]/emptool/api/mvno/esim/addAcnt/
```

### Authentication

Obtained via separate authentication API, included in request parameters.

### POST Parameters

| No  | Parameter | Name            | Required | Description       |
| --- | --------- | --------------- | -------- | ----------------- |
| 1   | json      | JSON Parameters | ◎        | Main request body |

### JSON Parameters

| No  | Parameter                | Name                       | Level | Type                   | Min | Max | Required | Description                                                                                                                                                                                    |
| --- | ------------------------ | -------------------------- | ----- | ---------------------- | --- | --- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1   | authKey                  | Authentication Key         | 1     | Alphanumeric           | -   | -   | ◎        | Obtained from OEM authentication                                                                                                                                                               |
| 2   | aladinOperated           | ALADIN Operated Flag       | 1     | Half-width numeric     | 2   | 2   | -        | `"10"`: Operated, `"20"`: Not operated. Defaults to `"20"` if omitted                                                                                                                          |
| 3   | masterAccount            | Master Account             | 1     | Alphanumeric + symbols | 1   | 64  | △        | IIC master account. Not required if: not using User Management Service, no planCode specified, or addKind is `"R"`                                                                             |
| 4   | masterPassword           | Master Password            | 1     | Alphanumeric + symbols | 1   | 256 | △        | IIC master password. Required when createType is `"new"`. Not required if: not using User Management Service, no planCode specified, or addKind is `"R"`                                       |
| 5   | createType               | Registration Type          | 1     | Half-width alpha       | 3   | 3   | △        | `"new"`: Create new master account, `"add"`: Add service account to existing. `"add"` not allowed without User Management Service. Not required if: no planCode specified, or addKind is `"R"` |
| 6   | eid                      | eSIM Identifier            | 1     | Half-width numeric     | 32  | 32  | ◎        | Target SIM's eSIM identifier (EID)                                                                                                                                                             |
| 7   | account                  | Account                    | 1     | Half-width numeric     | 11  | 14  | △        | Target SIM's phone number. Not required when aladinOperated is `"20"` and addKind is `"N"`. Required otherwise                                                                                 |
| 8   | simKind                  | SIM Type                   | 1     | Alphanumeric           | 2   | 2   | △        | `"E2"`: No SMS, `"E3"`: With SMS, `"E0"`: With voice. Not required when addKind is `"R"`. Required otherwise                                                                                   |
| 9   | contractLine             | Contract Line Type         | 1     | Alphanumeric           | 2   | 2   | △        | `"4G"`: 4G line, `"5G"`: 5G line. Not required when aladinOperated is `"10"` or addKind is `"R"`. Defaults to `"4G"` if omitted                                                                |
| 10  | repAccount               | Representative Number      | 1     | Half-width numeric     | 11  | 14  | △        | Parent phone number. Required when aladinOperated is `"10"` and addKind is `"N"`. Not required when addKind is `"R"`. Otherwise required for specific representative number activation         |
| 11  | addKind                  | Activation Type            | 1     | Half-width alpha       | 1   | 1   | ◎        | `"N"`: New, `"M"`: MNP transfer, `"R"`: Reissue                                                                                                                                                |
| 12  | reissue                  | Reissue Info               | 1     | Object                 | -   | -   | △        | Required when aladinOperated is `"20"` and addKind is `"R"`. Not required otherwise                                                                                                            |
| 13  | reissue.oldProductNumber | Old Product Number         | 2     | Alphanumeric           | 15  | 15  | △        | Product number of the SIM before reissue. First 2 chars uppercase alpha, remaining 13 digits (e.g., `AXxxxxxxxxxxxxx`). Only for physical SIM → eSIM                                           |
| 14  | reissue.oldEid           | Old eSIM Identifier        | 2     | Half-width numeric     | 32  | 32  | △        | EID of the eSIM before reissue. Only for eSIM → eSIM                                                                                                                                           |
| 15  | mnp                      | MNP Info                   | 1     | Object                 | -   | -   | △        | Required when aladinOperated is `"20"` and addKind is `"M"`. Not required otherwise                                                                                                            |
| 16  | mnp.reserveNumber        | MNP Reservation Number     | 2     | Half-width numeric     | 10  | 10  | ○        | MNP reservation number (no hyphens)                                                                                                                                                            |
| 17  | mnp.lastnameKanji        | Last Name (Kanji)          | 2     | Full-width characters  | 1   | 50  | ○        | UTF-8 range. For non-corporate: lastname + full-width space + firstname ≤ 50 chars. For corporate (gender `"C"`): lastname ≤ 50 chars. See [Character Rules](#character-rules)                 |
| 18  | mnp.firstnameKanji       | First Name (Kanji)         | 2     | Full-width characters  | \*  | \*  | △        | Required when gender is not `"C"` (corporate). See lastname for length rules                                                                                                                   |
| 19  | mnp.lastnameZenKana      | Last Name (Full Katakana)  | 2     | Full-width katakana    | 1   | 50  | ○        | UTF-8 range. For non-corporate: lastname + full-width space + firstname ≤ 50 chars. For corporate (gender `"C"`): lastname ≤ 50 chars. See [Character Rules](#character-rules)                 |
| 20  | mnp.firstnameZenKana     | First Name (Full Katakana) | 2     | Full-width katakana    | \*  | \*  | △        | Required when gender is not `"C"` (corporate). See lastname for length rules                                                                                                                   |
| 21  | mnp.gender               | Gender                     | 2     | Half-width alpha       | 1   | 1   | ○        | `"M"`: Male, `"W"`: Female, `"C"`: Corporate                                                                                                                                                   |
| 22  | mnp.birthday             | Date of Birth              | 2     | Half-width numeric     | 8   | 8   | △        | YYYYMMDD format. Required when gender is not `"C"` (corporate)                                                                                                                                 |
| 23  | shipDate                 | Ship Date                  | 1     | Half-width numeric     | 8   | 8   | △        | YYYYMMDD format. Past dates OK, future dates NG. Required when aladinOperated is `"10"`                                                                                                        |
| 24  | planCode                 | Plan Code                  | 1     | Alphanumeric + symbols | 1   | 32  | -        | Plan to apply. No plan = no connectivity. Not required when addKind is `"R"`                                                                                                                   |
| 25  | deliveryCode             | Delivery Code              | 1     | Alphanumeric           | 1   | 10  | -        | Arbitrary code set by each OEM                                                                                                                                                                 |

**Legend:** ◎ Required | ○ Required within level | △ Conditional

---

## Character Rules

### Kanji Fields

- Allowed: Characters within UTF-8 range that can be converted to Windows-31J, **excluding**:
  - Half-width space (`U+0020`)
  - Half-width alphanumeric (`U+0021`–`U+007E`)
  - Half-width katakana (`U+FF61`–`U+FF9F`)
- Full-width spaces: Allowed within string for corporate (`"C"`) only; never allowed at string edges

### Katakana Fields

- Allowed Unicode ranges only:
  - Full-width space: `U+3000`
  - Full-width digits: `U+FF10`–`U+FF19`
  - Full-width uppercase alpha: `U+FF21`–`U+FF3A`
  - Full-width katakana: `U+30A1`–`U+30EF`, `U+30F3` (ン), `U+30F4` (ヴ), `U+30FC` (ー)
- Full-width spaces: Allowed within string for corporate (`"C"`) only; never allowed at string edges

---

## Request Examples

### New Activation (ALADIN not operated, no User Management Service, with plan, no representative number)

```json
{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "createType": "new",
  "eid": "11112222333344445555666677778888",
  "simKind": "E2",
  "contractLine": "4G",
  "addKind": "N",
  "planCode": "100K_PLAN",
  "deliveryCode": "XXXX"
}
```

### New Activation (ALADIN not operated, no User Management Service, no plan, with representative number)

```json
{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "eid": "11112222333344445555666677778888",
  "simKind": "E0",
  "repAccount": "08000001111",
  "addKind": "N",
  "deliveryCode": "XXXX"
}
```

### MNP Transfer (ALADIN operated, with User Management Service, no representative number)

```json
{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "aladinOperated": "10",
  "masterAccount": "testAccount@test.ne.jp",
  "masterPassword": "testPass",
  "createType": "new",
  "eid": "11112222333344445555666677778888",
  "account": "08011112222",
  "simKind": "E0",
  "contractLine": "4G",
  "addKind": "M",
  "shipDate": "20170301",
  "planCode": "100K_PLAN",
  "deliveryCode": "XXXX"
}
```

### MNP Transfer (ALADIN operated, no User Management Service, with representative number)

```json
{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "aladinOperated": "10",
  "createType": "new",
  "eid": "11112222333344445555666677778888",
  "account": "08011112223",
  "simKind": "E3",
  "repAccount": "08000001111",
  "addKind": "M",
  "shipDate": "20170301",
  "planCode": "100K_PLAN"
}
```

### MNP Transfer (ALADIN not operated, with User Management Service, individual)

```json
{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "masterAccount": "testAccount@test.ne.jp",
  "masterPassword": "testPass",
  "createType": "new",
  "eid": "11112222333344445555666677778888",
  "account": "08011112222",
  "simKind": "E0",
  "contractLine": "5G",
  "addKind": "M",
  "mnp": {
    "reserveNumber": "1101201234",
    "lastnameKanji": "山田",
    "firstnameKanji": "太郎",
    "lastnameZenKana": "ヤマダ",
    "firstnameZenKana": "タロウ",
    "gender": "M",
    "birthday": "19900101"
  },
  "planCode": "100K_PLAN",
  "deliveryCode": "XXXX"
}
```

### MNP Transfer (ALADIN not operated, no User Management Service, corporate, with representative number)

```json
{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "createType": "new",
  "eid": "11112222333344445555666677778888",
  "account": "08011112223",
  "simKind": "E0",
  "repAccount": "08000001111",
  "addKind": "M",
  "mnp": {
    "reserveNumber": "1101201235",
    "lastnameKanji": "フリービット　株式会社",
    "lastnameZenKana": "フリービット　カブシキカイシャ",
    "gender": "C"
  },
  "planCode": "100K_PLAN"
}
```

### Reissue (ALADIN not operated, physical SIM → eSIM)

```json
{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "account": "08011112225",
  "eid": "11112222333344445555666677778888",
  "addKind": "R",
  "reissue": {
    "oldProductNumber": "CD0009999999004"
  }
}
```

---

## Response

### Format

JSON

### Parameters

| No  | Parameter         | Name               | Level | Type                   | Description               |
| --- | ----------------- | ------------------ | ----- | ---------------------- | ------------------------- |
| 1   | resultCode        | Result Code        | 1     | Numeric                | Processing result code    |
| 2   | status            | Status             | 1     | Object                 | Status details            |
| 3   | status.message    | Message            | 2     | Alphanumeric + symbols | Processing result message |
| 4   | status.statusCode | Detail Result Code | 2     | Numeric                | Detailed status code      |

---

## Response Codes

| Status | Status Code | Detail Code | Message     | Description                                                                    |
| ------ | ----------- | ----------- | ----------- | ------------------------------------------------------------------------------ |
| ○      | 200         | 100         | OK          | Success                                                                        |
| ×      | 400         | 201         | Bad Request | Parameter error - account (masterAccount/account) issue                        |
| ×      | 400         | 202         | Bad Request | Parameter error - master password issue                                        |
| ×      | 400         | 204         | Bad Request | Parameter error - other parameter issue                                        |
| ×      | 400         | 215         | Bad Request | Parameter error - plan code issue                                              |
| ×      | 400         | 228         | Bad Request | Parameter error - authentication key (authKey) issue                           |
| ×      | 400         | 253         | Bad Request | Parameter error - last name (kanji) issue                                      |
| ×      | 400         | 254         | Bad Request | Parameter error - first name (kanji) issue                                     |
| ×      | 400         | 255         | Bad Request | Parameter error - last name (full katakana) issue                              |
| ×      | 400         | 256         | Bad Request | Parameter error - first name (full katakana) issue                             |
| ×      | 400         | 257         | Bad Request | Parameter error - gender issue                                                 |
| ×      | 400         | 258         | Bad Request | Parameter error - date of birth issue                                          |
| ×      | 400         | 266         | Bad Request | Parameter error - product number (productNumber/oldProductNumber) issue        |
| ×      | 400         | 269         | Bad Request | Parameter error - representative number issue                                  |
| ×      | 400         | 274         | Bad Request | Parameter error - delivery code issue                                          |
| ×      | 400         | 276         | Bad Request | Parameter error - ship date issue                                              |
| ×      | 400         | 277         | Bad Request | Parameter error - SIM type issue                                               |
| ×      | 400         | 278         | Bad Request | Parameter error - ALADIN operated flag issue                                   |
| ×      | 400         | 279         | Bad Request | Parameter error - registration type issue                                      |
| ×      | 400         | 307         | Bad Request | Parameter error - MNP reservation number issue                                 |
| ×      | 400         | 333         | Bad Request | Parameter error - activation type issue                                        |
| ×      | 400         | 356         | Bad Request | Parameter error - unsupported pattern (ALADIN operated flag + activation type) |
| ×      | 400         | 360         | Bad Request | Parameter error - contract type issue                                          |
| ×      | 400         | 370         | Bad Request | Parameter error - eSIM identifier (eid/oldEid) issue                           |
| ×      | 403         | 205         | Auth Error  | Authentication key problem                                                     |
| ×      | 404         | 232         | Not Found   | Specified plan does not exist                                                  |
| ×      | 500         | 208         | NG          | Account (masterAccount/account) duplicate error                                |
| ×      | 500         | 210         | NG          | Account (masterAccount/account) not found error                                |
| ×      | 500         | 230         | NG          | Account is waiting for async processing; request not allowed                   |
| ×      | 500         | 275         | NG          | No available phone number inventory for the specified representative number    |
| ×      | 500         | 284         | NG          | Representative number is locked                                                |
| ×      | 500         | 287         | NG          | Representative number does not exist or is unavailable                         |
| ×      | 500         | 288         | NG          | Product number is unavailable (does not exist or already in use)               |
| ×      | 500         | 289         | NG          | SIM type does not match representative number's type                           |
| ×      | 500         | 304         | NG          | SIM type does not match representative number's type                           |
| ×      | 500         | 310         | NG          | MNP reservation number has duplication or other issues                         |
| ×      | 500         | 371         | NG          | eSIM identifier (eid) duplicate error                                          |
| ×      | 500         | 372         | NG          | eSIM identifier (eid) not found error                                          |
| ×      | 500         | 374         | NG          | Specified eSIM identifier has reached the monthly activation limit             |
| ×      | 500         | 900         | NG          | Unexpected error occurred                                                      |

---

## Response Example

```json
{
  "resultCode": 100,
  "status": {
    "message": "OK",
    "statusCode": 200
  }
}
```
