# PA05-18 - MVNO Semi-Black Account Temporary Registration (MVNO半黒アカウント仮登録)

## Overview

Queues a semi-black SIM account for later activation, based on an OEM request. Registers account information into related systems.

- Settings are **NOT** applied immediately — they are saved to a **queue**
- To activate a SIM queued by this API, use **PA05-19** (MVNO Semi-Black Account Registration)
- Supports two MNP methods: semi-black SIM (`"10"`) and OTA (`"20"`)
- To overwrite existing MNP info (e.g., expired reservation), the entry must first be cancelled via **PA05-20** (MVNO Semi-Black Account Status Change) to status `"60"` (cancelled)

---

## Request

### Method

`POST` (JSON format)

### URL

```
https://[host]/emptool/api/mvno/semiblack/addTempAcnt/
```

### 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     | Half-width numeric | 11  | 14  | △        | Target SIM phone number. Can be omitted when mnp.method is `"20"` (OTA). Required otherwise                                                                                     |
| 3   | tempAccount           | Temporary Account      | 1     | Half-width numeric | 11  | 14  | △        | Target SIM temporary phone number (parent number). Required when mnp.method is `"20"` (OTA). Not required otherwise                                                             |
| 4   | 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`, `DNxxxxxxxxxxxxx`)                                  |
| 5   | repAccount            | Representative Number  | 1     | Half-width numeric | 11  | 14  | △        | Parent phone number for the target SIM                                                                                                                                          |
| 6   | simKind               | SIM Type               | 1     | Alphanumeric       | 2   | 2   | ◎        | SIM type. Format: `[size][capability]`. Size — `S`: Standard, `M`: Micro, `N`: Nano. Capability — `0`: Voice, `2`: No SMS, `3`: SMS. Examples: `S0`, `M2`, `N3`                 |
| 7   | expireDate            | SIM Expiry Date        | 1     | Half-width numeric | 8   | 8   | △        | YYYYMMDD format. Semi-black SIM card expiry. If specified: used as-is. If omitted: OTA (`"20"`) = no expiry; otherwise = system date + 15 days (inclusive)                      |
| 8   | mnp                   | MNP Info               | 1     | Object             | -   | -   | -        | MNP information                                                                                                                                                                 |
| 9   | mnp.method            | MNP Method             | 2     | Half-width numeric | 2   | 2   | ◎        | `"10"`: Semi-black SIM, `"20"`: OTA                                                                                                                                             |
| 10  | mnp.reserveNumber     | MNP Reservation Number | 2     | Half-width numeric | 10  | 10  | △        | MNP reservation number (no hyphens). Can be omitted when mnp.method is `"20"` (OTA). Required otherwise                                                                         |
| 11  | mnp.reserveExpireDate | MNP Reservation Expiry | 2     | Half-width numeric | 8   | 8   | △        | YYYYMMDD format. MNP reservation expiry date. Can be omitted when mnp.method is `"20"` (OTA). Required otherwise                                                                |
| 12  | mnp.overWrite         | Overwrite Flag         | 2     | Half-width numeric | 2   | 2   | △        | `"10"`: Enabled, `"20"`: Disabled. Defaults to `"20"` if omitted. Used when MNP reservation expires before arrival. **Requires prior cancellation via PA05-20 (status `"60"`)** |

**Legend:** ◎ Required | △ Conditional

---

## Request Example

```json
{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "account": "08011112222",
  "tempAccount": "08022223333",
  "productNumber": "ZZ0009999999999",
  "repAccount": "08000001111",
  "simKind": "N0",
  "expireDate": "20150901",
  "mnp": {
    "method": "10",
    "reserveNumber": "1101201234",
    "reserveExpireDate": "20150915"
  }
}
```

---

## 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/tempAccount) issue                                     |
| ×      | 400         | 266         | Bad Request | Parameter error - product number issue                                                    |
| ×      | 400         | 269         | Bad Request | Parameter error - representative number issue                                             |
| ×      | 400         | 277         | Bad Request | Parameter error - SIM type issue                                                          |
| ×      | 400         | 309         | Bad Request | Parameter error - SIM expiry date issue                                                   |
| ×      | 400         | 306         | Bad Request | Parameter error - MNP method issue                                                        |
| ×      | 400         | 307         | Bad Request | Parameter error - MNP reservation number issue                                            |
| ×      | 400         | 308         | Bad Request | Parameter error - MNP reservation expiry date issue                                       |
| ×      | 400         | 314         | Bad Request | Parameter error - overwrite flag issue                                                    |
| ×      | 403         | 205         | Auth Error  | Authentication key problem                                                                |
| ×      | 500         | 208         | NG          | Account (account/tempAccount) duplicate error                                             |
| ×      | 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         | 310         | NG          | MNP reservation number has duplication or other issues                                    |
| ×      | 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
  }
}
```

---

## Related APIs

| API     | Name                                  | Relationship                                         |
| ------- | ------------------------------------- | ---------------------------------------------------- |
| PA05-19 | MVNO Semi-Black Account Registration  | Activates SIMs queued by this API                    |
| PA05-20 | MVNO Semi-Black Account Status Change | Must cancel (status `"60"`) before overwrite is used |
