# 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 } } ```