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