be09c78491
Translated Freebit API specs for voice options, semi-black registration, state changes, OTA activation, contract changes, and eSIM activation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
296 lines
20 KiB
Markdown
296 lines
20 KiB
Markdown
# 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
|
||
}
|
||
}
|
||
```
|