Assist_Design/freebit-api-docs/PA05-05_mvno-voice-option-registration.md

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
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
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
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
17	identificationData.lastnameZenKana	Last Name (Katakana)	2	Full-width katakana	1	255	◎	URL-encoded full-width characters. See 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
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)

{
  "authKey": "XXXXXXXXXX",
  "account": "09012345678",
  "userConfirmed": "10",
  "aladinOperated": "10",
  "talkOption": {},
  "identificationData": {
    "lastnameKanji": "山田",
    "firstnameKanji": "太郎",
    "lastnameZenKana": "ヤマダ",
    "firstnameZenKana": "タロウ",
    "gender": "M",
    "birthday": "19900101"
  }
}

No Voice Options (omitted entirely)

{
  "authKey": "XXXXXXXXXX",
  "account": "09012345678",
  "userConfirmed": "10",
  "aladinOperated": "10",
  "identificationData": {
    "lastnameKanji": "山田",
    "firstnameKanji": "太郎",
    "lastnameZenKana": "ヤマダ",
    "firstnameZenKana": "タロウ",
    "gender": "M",
    "birthday": "19900101"
  }
}

With Voice Options (individual)

{
  "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)

{
  "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

{
  "resultCode": 100,
  "status": {
    "message": "OK",
    "statusCode": 200
  }
}