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>
143 lines
10 KiB
Markdown
143 lines
10 KiB
Markdown
# PA05-19 - MVNO Semi-Black Account Registration (MVNO半黒アカウント本登録)
|
||
|
||
## Overview
|
||
|
||
Performs full registration of a pre-provisioned semi-black SIM into related systems, based on an OEM request.
|
||
|
||
- Settings are applied **immediately** (synchronous, unlike most other activation APIs)
|
||
- The SIM must have been previously pre-registered (仮登録) before calling this API
|
||
- Supports two MNP methods: semi-black SIM (`"10"`) and OTA (`"20"`)
|
||
|
||
---
|
||
|
||
## Request
|
||
|
||
### Method
|
||
|
||
`POST` (JSON format)
|
||
|
||
### URL
|
||
|
||
```
|
||
https://[host]/emptool/api/mvno/semiblack/addAcnt/
|
||
```
|
||
|
||
### 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 | aladinOperated | ALADIN Operated Flag | 1 | Half-width numeric | 2 | 2 | - | `"10"`: Operated, `"20"`: Not operated. Defaults to `"20"` if omitted |
|
||
| 3 | masterAccount | Master Account | 1 | Alphanumeric + symbols | 1 | 64 | △ | IIC master account. Not required if: not using User Management Service, or no planCode specified |
|
||
| 4 | masterPassword | Master Password | 1 | Alphanumeric + symbols | 1 | 256 | △ | IIC master password. Required when createType is `"new"`. Not required if: not using User Management Service, or no planCode specified |
|
||
| 5 | createType | Registration Type | 1 | Alphanumeric | - | - | ◎ | `"new"`: Create new master account, `"add"`: Add to existing. `"add"` not allowed without User Management Service |
|
||
| 6 | account | Account | 1 | Half-width numeric | 11 | 14 | ◎ | Target SIM phone number. Can be omitted when mnp.method is `"20"` (OTA). Required otherwise |
|
||
| 7 | tempAccount | Temporary Account | 1 | Half-width numeric | 11 | 14 | △ | Target SIM temporary phone number. Required when mnp.method is `"20"` (OTA). Not required otherwise |
|
||
| 8 | productNumber | Product Number | 1 | Alphanumeric | 15 | 15 | ◎ | Product number printed on the back of the SIM. First 2 chars uppercase alpha, remaining 13 digits (e.g., `AXxxxxxxxxxxxxx`) |
|
||
| 9 | mnp | MNP Info | 1 | Object | - | - | - | MNP information |
|
||
| 10 | mnp.method | MNP Method | 2 | Half-width numeric | 2 | 2 | ◎ | `"10"`: Semi-black SIM, `"20"`: OTA |
|
||
| 11 | shipDate | Ship Date | 1 | Half-width numeric | 8 | 8 | ◎ | YYYYMMDD format. Past dates OK, future dates NG |
|
||
| 12 | globalIp | Global IP (yes/no) | 1 | Half-width numeric | 2 | 2 | - | `"20"`: Disabled. If not specified, not processed. Note: `"10"` (enabled) has been **deprecated**. Requires contract with freebit |
|
||
| 13 | planCode | Plan Code | 1 | Alphanumeric | 1 | 32 | ◎ | Plan to apply |
|
||
| 14 | deliveryCode | Delivery Code | 1 | Alphanumeric | 1 | 10 | - | Arbitrary code set by each OEM |
|
||
|
||
**Legend:** ◎ Required | △ Conditional
|
||
|
||
---
|
||
|
||
## Request Example
|
||
|
||
```json
|
||
{
|
||
"authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
|
||
"aladinOperated": "10",
|
||
"masterAccount": "testAccount@test.ne.jp",
|
||
"masterPassword": "testPass",
|
||
"createType": "new",
|
||
"account": "08011112222",
|
||
"tempAccount": "08022223333",
|
||
"productNumber": "ZZ0009999999999",
|
||
"mnp": {
|
||
"method": "10"
|
||
},
|
||
"shipDate": "20150915",
|
||
"globalIp": "20",
|
||
"planCode": "100K_PLAN",
|
||
"deliveryCode": "XXX001"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 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 |
|
||
| × | 400 | 201 | Bad Request | Parameter error - account (account/to/tempAccount) issue |
|
||
| × | 400 | 202 | Bad Request | Parameter error - master password issue |
|
||
| × | 400 | 204 | Bad Request | Parameter error - other parameter issue |
|
||
| × | 400 | 215 | Bad Request | Parameter error - plan code (planCode) issue |
|
||
| × | 400 | 228 | Bad Request | Parameter error - authentication key (authKey) issue |
|
||
| × | 400 | 231 | Bad Request | Parameter error - global IP (globalIp) issue |
|
||
| × | 400 | 266 | Bad Request | Parameter error - product number issue |
|
||
| × | 400 | 269 | Bad Request | Parameter error - representative number issue |
|
||
| × | 400 | 274 | Bad Request | Parameter error - delivery code issue |
|
||
| × | 400 | 276 | Bad Request | Parameter error - ship date issue |
|
||
| × | 400 | 279 | Bad Request | Parameter error - registration type issue |
|
||
| × | 400 | 306 | Bad Request | Parameter error - MNP method issue |
|
||
| × | 403 | 205 | Auth Error | Authentication key problem |
|
||
| × | 404 | 232 | Not Found | Specified plan does not exist |
|
||
| × | 500 | 208 | NG | Account (masterAccount/account) duplicate error |
|
||
| × | 500 | 210 | NG | Account (masterAccount) 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 | 275 | NG | No available phone number inventory for the specified representative number |
|
||
| × | 500 | 284 | NG | Representative number is locked |
|
||
| × | 500 | 287 | NG | Representative number does not exist or is unavailable |
|
||
| × | 500 | 288 | NG | Product number does not exist, is already in use, or has not been received into inventory |
|
||
| × | 500 | 289 | NG | SIM type does not match representative number's type |
|
||
| × | 500 | 313 | NG | MNP reservation number expiry falls within the grace period; request cannot be accepted |
|
||
| × | 500 | 900 | NG | Unexpected error occurred |
|
||
|
||
---
|
||
|
||
## Response Example
|
||
|
||
```json
|
||
{
|
||
"resultCode": 100,
|
||
"status": {
|
||
"message": "OK",
|
||
"statusCode": 200
|
||
}
|
||
}
|
||
```
|