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>
328 lines
20 KiB
Markdown
328 lines
20 KiB
Markdown
# PA05-33 - OTA Account Activation (OTAアカウント開通)
|
||
|
||
## Overview
|
||
|
||
Activates a pre-created OTA-SIM based on an OEM request. Supports new activations, MNP transfers, and reissues.
|
||
|
||
- Activation is **asynchronous** — not immediate. Completion is notified via file output:
|
||
- **Activation Ready Notification File** — output when activation preparation is complete
|
||
- **Activation Complete Notification File** — output when activation is fully complete
|
||
- File specifications: see CSV File Format Definition (MVNO Edition)
|
||
- When `aladinOperated` is `"10"` (operated) **and** `addKind` is `"R"` (reissue), the API returns `400-356` (unsupported pattern). Reissue with ALADIN operated is handled via file integration instead.
|
||
|
||
---
|
||
|
||
## Request
|
||
|
||
### Method
|
||
|
||
`POST` (JSON format, URL-encoded)
|
||
|
||
### URL
|
||
|
||
```
|
||
https://[host]/emptool/api/mvno/ota/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"` (reissue) |
|
||
| 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, or addKind `"R"` |
|
||
| 5 | createType | Registration Type | 1 | Half-width alpha | 3 | 3 | △ | `"new"`: Create new master account, `"add"`: Add to existing. `"add"` not allowed without User Management Service. Not required for `"R"` |
|
||
| 6 | account | Account | 1 | Half-width numeric | 11 | 14 | ◎ | Target SIM phone number. If activating with same number as tempAccount, specify the tempAccount value |
|
||
| 7 | tempAccount | Temporary Account | 1 | Half-width numeric | 11 | 14 | ◎ | OTA-SIM temporary phone number |
|
||
| 8 | productNumber | Product Number | 1 | Alphanumeric | 15 | 15 | ◎ | Product number on back of OTA-SIM. First 2 chars uppercase alpha, remaining 13 digits (e.g., `AXxxxxxxxxxxxxx`) |
|
||
| 9 | repAccount | Representative Number | 1 | Half-width numeric | 11 | 14 | △ | Parent phone number. Required unless addKind is `"R"` (reissue) |
|
||
| 10 | size | SIM Size | 1 | Half-width alpha | 4 | 8 | ◎ | `"standard"`, `"nano"`, or `"micro"` |
|
||
| 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 addKind is `"R"`. Not required otherwise |
|
||
| 13 | reissue.oldSize | Original SIM Size | 2 | Half-width alpha | 4 | 8 | ○ | SIM size before reissue: `"standard"`, `"nano"`, or `"micro"` |
|
||
| 14 | reissue.oldProductNumber | Original Product Number | 2 | Alphanumeric | 15 | 15 | ○ | Product number of the SIM before reissue |
|
||
| 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.reserveExpireDate | MNP Reservation Expiry | 2 | Half-width numeric | 8 | 8 | ○ | YYYYMMDD format. Future dates only |
|
||
| 18 | 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 |
|
||
| 19 | mnp.firstnameKanji | First Name (Kanji) | 2 | Full-width characters | \* | \* | △ | Required when gender is not `"C"` (corporate). See lastname for length rules |
|
||
| 20 | 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 |
|
||
| 21 | mnp.firstnameZenKana | First Name (Full Katakana) | 2 | Full-width katakana | \* | \* | △ | Required when gender is not `"C"` (corporate). See lastname for length rules |
|
||
| 22 | mnp.gender | Gender | 2 | Half-width alpha | 1 | 1 | ○ | `"M"`: Male, `"W"`: Female, `"C"`: Corporate |
|
||
| 23 | mnp.birthday | Date of Birth | 2 | Half-width numeric | 8 | 8 | △ | YYYYMMDD format. Required when gender is not `"C"` (corporate) |
|
||
| 24 | shipDate | Ship Date | 1 | Half-width numeric | 8 | 8 | △ | YYYYMMDD format. Past dates OK, future dates NG. Required when aladinOperated is `"10"`. When `"10"` + addKind `"R"`, treated as reissue completion date |
|
||
| 25 | planCode | Plan Code | 1 | Alphanumeric + symbols | 1 | 32 | - | Plan to apply. No plan = no connectivity. Not required for addKind `"R"` |
|
||
| 26 | globalIp | Global IP (yes/no) | 1 | Half-width numeric | 2 | 2 | - | `"20"`: Disabled. If not specified, not processed. `"10"` (enabled) is **deprecated**. Not required for addKind `"R"` |
|
||
| 27 | 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:
|
||
|
||
- Must be within UTF-8 range **and** convertible to Windows-31J encoding
|
||
- **Excluded**: half-width space (0x0020), half-width alphanumeric (0x0021-0x007E), half-width katakana (0xFF61-0xFF9F)
|
||
- Corporate (`"C"`): full-width spaces allowed
|
||
- Non-corporate: full-width spaces **not** allowed
|
||
- Full-width spaces **not** allowed at start/end of string
|
||
|
||
### Katakana Fields
|
||
|
||
Allowed characters (Unicode ranges):
|
||
|
||
- Full-width space: 0x3000
|
||
- Full-width digits: 0xFF10-0xFF19
|
||
- Full-width uppercase alpha: 0xFF21-0xFF3A
|
||
- Full-width katakana: 0x30A1-0x30EF, 0x30F3 (ン), 0x30F4 (ヴ), 0x30FC (ー)
|
||
- Same corporate/non-corporate space rules as kanji fields
|
||
|
||
---
|
||
|
||
## Request Examples
|
||
|
||
### MNP Transfer (ALADIN operated, with User Management Service)
|
||
|
||
```json
|
||
{
|
||
"authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
|
||
"aladinOperated": "10",
|
||
"masterAccount": "testAccount@test.ne.jp",
|
||
"masterPassword": "testPass",
|
||
"createType": "new",
|
||
"account": "08011112222",
|
||
"tempAccount": "08022223333",
|
||
"productNumber": "ZZ0009999999001",
|
||
"repAccount": "08000001111",
|
||
"size": "standard",
|
||
"addKind": "M",
|
||
"shipDate": "20170301",
|
||
"planCode": "100K_PLAN",
|
||
"globalIp": "20",
|
||
"deliveryCode": "XXXX"
|
||
}
|
||
```
|
||
|
||
### MNP Transfer (ALADIN operated, no User Management Service)
|
||
|
||
```json
|
||
{
|
||
"authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
|
||
"aladinOperated": "10",
|
||
"createType": "new",
|
||
"account": "08011112223",
|
||
"tempAccount": "08022223334",
|
||
"productNumber": "ZZ0009999999002",
|
||
"repAccount": "08000001111",
|
||
"size": "nano",
|
||
"addKind": "M",
|
||
"shipDate": "20170301",
|
||
"planCode": "100K_PLAN",
|
||
"globalIp": "20"
|
||
}
|
||
```
|
||
|
||
### MNP Transfer (ALADIN not operated, with User Management Service, individual)
|
||
|
||
```json
|
||
{
|
||
"authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
|
||
"masterAccount": "testAccount@test.ne.jp",
|
||
"masterPassword": "testPass",
|
||
"createType": "new",
|
||
"account": "08011112222",
|
||
"tempAccount": "08022223333",
|
||
"productNumber": "ZZ0009999999001",
|
||
"repAccount": "08000001111",
|
||
"size": "nano",
|
||
"addKind": "M",
|
||
"mnp": {
|
||
"reserveNumber": "1101201234",
|
||
"reserveExpireDate": "20170323",
|
||
"lastnameKanji": "山田",
|
||
"firstnameKanji": "太郎",
|
||
"lastnameZenKana": "ヤマダ",
|
||
"firstnameZenKana": "タロウ",
|
||
"gender": "M",
|
||
"birthday": "19900101"
|
||
},
|
||
"planCode": "100K_PLAN",
|
||
"globalIp": "20",
|
||
"deliveryCode": "XXXX"
|
||
}
|
||
```
|
||
|
||
### MNP Transfer (ALADIN not operated, no User Management Service, corporate)
|
||
|
||
```json
|
||
{
|
||
"authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
|
||
"createType": "new",
|
||
"account": "08011112223",
|
||
"tempAccount": "08022223334",
|
||
"productNumber": "ZZ0009999999002",
|
||
"repAccount": "08000001111",
|
||
"size": "micro",
|
||
"addKind": "M",
|
||
"mnp": {
|
||
"reserveNumber": "1101201235",
|
||
"reserveExpireDate": "20170323",
|
||
"lastnameKanji": "フリービット 株式会社",
|
||
"lastnameZenKana": "フリービット カブシキカイシャ",
|
||
"gender": "C"
|
||
},
|
||
"planCode": "100K_PLAN",
|
||
"globalIp": "20"
|
||
}
|
||
```
|
||
|
||
### New Activation (ALADIN not operated, no User Management Service, with plan)
|
||
|
||
```json
|
||
{
|
||
"authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
|
||
"createType": "new",
|
||
"account": "08011112224",
|
||
"tempAccount": "08011112224",
|
||
"productNumber": "ZZ0009999999003",
|
||
"repAccount": "08000001111",
|
||
"size": "nano",
|
||
"addKind": "N",
|
||
"planCode": "100K_PLAN",
|
||
"deliveryCode": "XXXX"
|
||
}
|
||
```
|
||
|
||
### New Activation (ALADIN not operated, no User Management Service, no plan)
|
||
|
||
```json
|
||
{
|
||
"authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
|
||
"account": "08011112224",
|
||
"tempAccount": "08011112224",
|
||
"productNumber": "ZZ0009999999003",
|
||
"repAccount": "08000001111",
|
||
"size": "nano",
|
||
"addKind": "N",
|
||
"deliveryCode": "XXXX"
|
||
}
|
||
```
|
||
|
||
### Reissue (ALADIN not operated)
|
||
|
||
```json
|
||
{
|
||
"authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
|
||
"account": "08011112225",
|
||
"tempAccount": "08022223336",
|
||
"productNumber": "ZZ0009999999004",
|
||
"size": "nano",
|
||
"addKind": "R",
|
||
"reissue": {
|
||
"oldSize": "micro",
|
||
"oldProductNumber": "CD0009999999004"
|
||
},
|
||
"globalIp": "20"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 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/tempAccount) 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 issue |
|
||
| × | 400 | 231 | Bad Request | Parameter error - global IP 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 | 267 | Bad Request | Parameter error - SIM size (size/oldSize) 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 | 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 | 308 | Bad Request | Parameter error - MNP reservation expiry date issue |
|
||
| × | 400 | 333 | Bad Request | Parameter error - activation type issue |
|
||
| × | 400 | 356 | Bad Request | Parameter error - unsupported pattern (ALADIN operated flag + activation type) |
|
||
| × | 403 | 205 | Auth Error | Authentication key problem |
|
||
| × | 404 | 232 | Not Found | Specified plan does not exist |
|
||
| × | 500 | 208 | NG | Account (masterAccount/account/tempAccount) 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, already in use, etc.) |
|
||
| × | 500 | 310 | NG | MNP reservation number has duplication or other issues |
|
||
| × | 500 | 334 | NG | Temporary phone number does not match product number |
|
||
| × | 500 | 342 | NG | SIM size mismatch (does not match managed SIM size) |
|
||
| × | 500 | 900 | NG | Unexpected error occurred |
|
||
|
||
---
|
||
|
||
## Response Example
|
||
|
||
```json
|
||
{
|
||
"resultCode": 100,
|
||
"status": {
|
||
"message": "OK",
|
||
"statusCode": 200
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Related APIs
|
||
|
||
| API | Name | Relationship |
|
||
| ------- | ---------------------------------------------- | ---------------------------------------------------------------- |
|
||
| PA05-41 | eSIM Account Activation | Similar API for eSIM activations (also supports MNP and reissue) |
|
||
| PA05-18 | MVNO Semi-Black Account Temporary Registration | Pre-staging API for semi-black SIM MNP (queue-based) |
|
||
| PA05-19 | MVNO Semi-Black Account Registration | Synchronous activation for semi-black SIMs |
|