ankhbayar/Assist_Design
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity
Assist_Design/freebit-api-docs/PA05-06_mvno-voice-option-change.md

168 lines
11 KiB
Markdown
Raw Normal View History

docs: add Freebit API specification docs (PA05-05/06/18/19/20/33/38/41) 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>
2026-02-17 18:06:10 +09:00
# PA05-06 - MVNO Voice Option Change (MVNO音声オプション変更依頼)
## Overview
Changes the voice option features for the requested account/MVNO service.
- Voice option changes are **asynchronous** - cannot be cancelled while processing
- Unlike registration (PA05-05), this API does **not** accept identification data - only voice option changes
- Omitted options are treated as "no change" (not reset to defaults)
- The `talkOption` object is **required** and must not be empty
---
## Request
### Method
`POST` (JSON format)
### URL
```
https://[host]/emptool/api/mvno/talkoption/changeOrder/
```
### 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. **Must not be empty** - empty `{}` returns error |
| 6 | talkOption.voiceMail | Voicemail | 2 | Half-width numeric | 2 | 2 | △ | `"10"`: Enabled, `"20"`: Disabled. Omitted = no change |
| 7 | talkOption.callWaiting | Call Waiting | 2 | Half-width numeric | 2 | 2 | △ | `"10"`: Enabled, `"20"`: Disabled. Omitted = no change |
| 8 | talkOption.callTransfer | Call Transfer | 2 | Half-width numeric | 2 | 2 | △ | `"10"`: Enabled, `"20"`: Disabled. Omitted = no change |
| 9 | talkOption.callTransferToWorld | International Call Transfer | 2 | Half-width numeric | 2 | 2 | △ | `"10"`: Enabled, `"20"`: Disabled. Omitted = no change |
| 10 | talkOption.worldCall | WORLD CALL | 2 | Half-width numeric | 2 | 2 | △ | `"10"`: Amount specified, `"11"`: Unlimited, `"20"`: Disabled. Omitted = no change |
| 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. Omitted = no change |
| 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) |
**Legend:** ◎ Required | △ Conditional
---
## 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 Example
```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": "20000"
}
}
```
---
## 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 | 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 change not allowed |
| × | 500 | 900 | NG | Unexpected error occurred |
---
## Response Example
```json
{
"resultCode": 100,
"status": {
"message": "OK",
"statusCode": 200
}
}
```
Reference in New Issue Copy Permalink