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