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>
282 lines
17 KiB
Markdown
282 lines
17 KiB
Markdown
# PA05-05 - MVNO Voice Option Registration (MVNO音声オプション登録)
|
||
|
||
## Overview
|
||
|
||
Registers voice option features and identity verification information (identification data) for the requested account/MVNO service.
|
||
|
||
- Voice option registration is **asynchronous** - cannot be cancelled while processing
|
||
- Registers both voice call features (voicemail, call waiting, etc.) and subscriber identity information
|
||
|
||
---
|
||
|
||
## Request
|
||
|
||
### Method
|
||
|
||
`POST` (JSON format)
|
||
|
||
### URL
|
||
|
||
```
|
||
https://[host]/emptool/api/mvno/talkoption/addOrder/
|
||
```
|
||
|
||
### 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 | account | Account | 1 | Alphanumeric + symbols | - | - | ◎ | Target SIM phone number |
|
||
| 3 | userConfirmed | User Confirmed Flag | 1 | Half-width numeric | 2 | 2 | ◎ | `"10"`: Enabled, `"20"`: Disabled. Returns error if not enabled |
|
||
| 4 | aladinOperated | ALADIN Operated Flag | 1 | Half-width numeric | 2 | 2 | - | `"10"`: Operated, `"20"`: Not operated. Defaults to `"20"` if omitted |
|
||
| 5 | talkOption | Voice Options | 1 | Object | - | - | △ | Voice option settings. If not specified, pass empty `{}` or omit entirely |
|
||
| 6 | talkOption.voiceMail | Voicemail | 2 | Half-width numeric | 2 | 2 | △ | `"10"`: Enabled, `"20"`: Disabled. Defaults to `"20"` |
|
||
| 7 | talkOption.callWaiting | Call Waiting | 2 | Half-width numeric | 2 | 2 | △ | `"10"`: Enabled, `"20"`: Disabled. Defaults to `"20"` |
|
||
| 8 | talkOption.callTransfer | Call Transfer | 2 | Half-width numeric | 2 | 2 | △ | `"10"`: Enabled, `"20"`: Disabled. Defaults to `"20"` |
|
||
| 9 | talkOption.callTransferToWorld | International Call Transfer | 2 | Half-width numeric | 2 | 2 | △ | `"10"`: Enabled, `"20"`: Disabled. Defaults to `"20"` |
|
||
| 10 | talkOption.worldCall | WORLD CALL | 2 | Half-width numeric | 2 | 2 | △ | `"10"`: Amount specified, `"11"`: Unlimited, `"20"`: Disabled. Defaults to `"20"` |
|
||
| 11 | talkOption.worldCallCreditLimit | WORLD CALL Credit Limit | 2 | Half-width numeric | 4 | 7 | △ | Credit limit in JPY. Only applies when worldCall is `"10"`. Defaults to `5000`. Ignored when worldCall is `"11"` or `"20"`. See [WORLD CALL Allowed Amounts](#world-call-allowed-amounts) |
|
||
| 12 | talkOption.worldWing | WORLD WING | 2 | Half-width numeric | 2 | 2 | △ | `"10"`: Amount specified, `"11"`: Unlimited, `"20"`: Disabled. Defaults to `"20"` |
|
||
| 13 | talkOption.worldWingCreditLimit | WORLD WING Suspension Limit | 2 | Half-width numeric | 5 | 7 | △ | Suspension threshold in JPY. Only applies when worldWing is `"10"`. Defaults to `50000`. Ignored when worldWing is `"11"` or `"20"`. See [WORLD WING Allowed Amounts](#world-wing-allowed-amounts) |
|
||
| 14 | identificationData | Identification Data | 1 | Object | - | - | ◎ | Key information to determine voice option usage count. Empty `{}` returns error |
|
||
| 15 | identificationData.lastnameKanji | Last Name (Kanji) | 2 | Full-width characters | 1 | 255 | △ | URL-encoded full-width characters. Registered as blank if omitted. See [Character Rules](#character-rules) |
|
||
| 16 | identificationData.firstnameKanji | First Name (Kanji) | 2 | Full-width characters | 1 | 255 | △ | URL-encoded full-width characters. Registered as blank if omitted. See [Character Rules](#character-rules) |
|
||
| 17 | identificationData.lastnameZenKana | Last Name (Katakana) | 2 | Full-width katakana | 1 | 255 | ◎ | URL-encoded full-width characters. See [Character Rules](#character-rules) |
|
||
| 18 | identificationData.firstnameZenKana | First Name (Katakana) | 2 | Full-width katakana | 1 | 255 | △ | URL-encoded full-width characters. Not required when gender is `"C"` (corporate). Required otherwise. See [Character Rules](#character-rules) |
|
||
| 19 | identificationData.gender | Gender | 2 | Half-width alpha | 1 | 1 | ◎ | `"M"`: Male, `"W"`: Female, `"C"`: Corporate. Invalid values return error |
|
||
| 20 | identificationData.birthday | Date of Birth | 2 | Alphanumeric + symbols | 1 | 10 | △ | `"YYYYMMDD"` or `"YYYY/MM/DD"` format. Not required when gender is `"C"` (corporate); value is ignored even if provided |
|
||
|
||
**Legend:** ◎ Required | △ Conditional
|
||
|
||
---
|
||
|
||
## Character Rules
|
||
|
||
### Kanji Fields
|
||
|
||
- Nearly all characters in the Unicode table are allowed
|
||
- **Excluded**: Special characters and platform-dependent characters (機種依存文字)
|
||
|
||
### Katakana Fields
|
||
|
||
Allowed characters:
|
||
|
||
- Full-width katakana
|
||
- Full-width Roman letters (uppercase and lowercase)
|
||
- Full-width Arabic numerals
|
||
- The following symbols:
|
||
- `＆` (ampersand)
|
||
- `'` (apostrophe)
|
||
- `，` (comma)
|
||
- `－` (hyphen)
|
||
- `．` (period)
|
||
- `・` (middle dot)
|
||
- ` ` (full-width space)
|
||
|
||
---
|
||
|
||
## WORLD CALL Allowed Amounts
|
||
|
||
Only the following values (in JPY) are accepted. Any other value returns an error.
|
||
|
||
| | | | |
|
||
| ------ | ------ | ------- | --------- |
|
||
| 5,000 | 50,000 | 100,000 | 400,000 |
|
||
| 10,000 | 60,000 | 150,000 | 500,000 |
|
||
| 20,000 | 70,000 | 200,000 | 600,000 |
|
||
| 30,000 | 80,000 | 250,000 | 800,000 |
|
||
| 40,000 | 90,000 | 300,000 | 1,000,000 |
|
||
|
||
---
|
||
|
||
## WORLD WING Allowed Amounts
|
||
|
||
Only the following values (in JPY) are accepted. Any other value returns an error.
|
||
|
||
| | | |
|
||
| ------- | ------- | --------- |
|
||
| 50,000 | 500,000 | 1,000,000 |
|
||
| 100,000 | 600,000 | |
|
||
| 200,000 | 700,000 | |
|
||
| 300,000 | 800,000 | |
|
||
| 400,000 | 900,000 | |
|
||
|
||
---
|
||
|
||
## Request Examples
|
||
|
||
### No Voice Options (empty object)
|
||
|
||
```json
|
||
{
|
||
"authKey": "XXXXXXXXXX",
|
||
"account": "09012345678",
|
||
"userConfirmed": "10",
|
||
"aladinOperated": "10",
|
||
"talkOption": {},
|
||
"identificationData": {
|
||
"lastnameKanji": "山田",
|
||
"firstnameKanji": "太郎",
|
||
"lastnameZenKana": "ヤマダ",
|
||
"firstnameZenKana": "タロウ",
|
||
"gender": "M",
|
||
"birthday": "19900101"
|
||
}
|
||
}
|
||
```
|
||
|
||
### No Voice Options (omitted entirely)
|
||
|
||
```json
|
||
{
|
||
"authKey": "XXXXXXXXXX",
|
||
"account": "09012345678",
|
||
"userConfirmed": "10",
|
||
"aladinOperated": "10",
|
||
"identificationData": {
|
||
"lastnameKanji": "山田",
|
||
"firstnameKanji": "太郎",
|
||
"lastnameZenKana": "ヤマダ",
|
||
"firstnameZenKana": "タロウ",
|
||
"gender": "M",
|
||
"birthday": "19900101"
|
||
}
|
||
}
|
||
```
|
||
|
||
### With Voice Options (individual)
|
||
|
||
```json
|
||
{
|
||
"authKey": "XXXXXXXXXX",
|
||
"account": "09012345678",
|
||
"userConfirmed": "10",
|
||
"aladinOperated": "10",
|
||
"talkOption": {
|
||
"voiceMail": "10",
|
||
"callWaiting": "10",
|
||
"callTransfer": "10",
|
||
"callTransferToWorld": "20",
|
||
"worldCall": "10",
|
||
"worldCallCreditLimit": "10000",
|
||
"worldWing": "10",
|
||
"worldWingCreditLimit": ""
|
||
},
|
||
"identificationData": {
|
||
"lastnameKanji": "山田",
|
||
"firstnameKanji": "太郎",
|
||
"lastnameZenKana": "ヤマダ",
|
||
"firstnameZenKana": "タロウ",
|
||
"gender": "M",
|
||
"birthday": "19900101"
|
||
}
|
||
}
|
||
```
|
||
|
||
### With Voice Options (corporate)
|
||
|
||
```json
|
||
{
|
||
"authKey": "XXXXXXXXXX",
|
||
"account": "09012345678",
|
||
"userConfirmed": "10",
|
||
"aladinOperated": "10",
|
||
"talkOption": {
|
||
"voiceMail": "10",
|
||
"callWaiting": "10",
|
||
"callTransfer": "10",
|
||
"callTransferToWorld": "20",
|
||
"worldCall": "10",
|
||
"worldCallCreditLimit": "10000",
|
||
"worldWing": "10",
|
||
"worldWingCreditLimit": ""
|
||
},
|
||
"identificationData": {
|
||
"lastnameZenKana": "フリービット",
|
||
"firstnameZenKana": "",
|
||
"gender": "C"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 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 |
|
||
| ○ | 200 | 101 | OK | Request already satisfied (options already in desired state) |
|
||
| × | 400 | 201 | Bad Request | Parameter error - account (account/to/tempAccount) issue |
|
||
| × | 400 | 204 | Bad Request | Parameter error - other parameter issue |
|
||
| × | 400 | 228 | Bad Request | Parameter error - authentication key (authKey) issue |
|
||
| × | 400 | 242 | Bad Request | Parameter error - user confirmed flag issue |
|
||
| × | 400 | 243 | Bad Request | Parameter error - voice options (object) issue |
|
||
| × | 400 | 244 | Bad Request | Parameter error - voicemail option issue |
|
||
| × | 400 | 245 | Bad Request | Parameter error - call waiting option issue |
|
||
| × | 400 | 246 | Bad Request | Parameter error - call transfer option issue |
|
||
| × | 400 | 247 | Bad Request | Parameter error - international call transfer option issue |
|
||
| × | 400 | 248 | Bad Request | Parameter error - WORLD CALL option issue |
|
||
| × | 400 | 249 | Bad Request | Parameter error - WORLD CALL credit limit issue |
|
||
| × | 400 | 250 | Bad Request | Parameter error - WORLD WING option issue |
|
||
| × | 400 | 251 | Bad Request | Parameter error - WORLD WING suspension limit issue |
|
||
| × | 400 | 252 | Bad Request | Parameter error - identification data (object) 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 (katakana) issue |
|
||
| × | 400 | 256 | Bad Request | Parameter error - first name (katakana) issue |
|
||
| × | 400 | 257 | Bad Request | Parameter error - gender issue |
|
||
| × | 400 | 258 | Bad Request | Parameter error - date of birth issue |
|
||
| × | 400 | 278 | Bad Request | Parameter error - ALADIN operated flag issue |
|
||
| × | 403 | 205 | Auth Error | Authentication key problem |
|
||
| × | 404 | 263 | Not Found | Specified voice option does not exist |
|
||
| × | 500 | 210 | NG | Account not found error |
|
||
| × | 500 | 211 | NG | Account status does not allow request execution |
|
||
| × | 500 | 230 | NG | Account is waiting for async processing; request not allowed |
|
||
| × | 500 | 241 | NG | User confirmed flag is not enabled for voice option registration/change/cancellation |
|
||
| × | 500 | 260 | NG | MVNO account voice usage state is `20` (not in use); voice option addition not allowed |
|
||
| × | 500 | 261 | NG | Maximum voice SIM registrations per OEM exceeded (6 or more); voice option addition not allowed |
|
||
| × | 500 | 262 | NG | Voice option already registered. Use the change request API instead |
|
||
| × | 500 | 900 | NG | Unexpected error occurred |
|
||
|
||
---
|
||
|
||
## Response Example
|
||
|
||
```json
|
||
{
|
||
"resultCode": 100,
|
||
"status": {
|
||
"message": "OK",
|
||
"statusCode": 200
|
||
}
|
||
}
|
||
```
|