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