# PA05-20 - MVNO Semi-Black Account Status Change (MVNO半黒アカウント状態変更)

## Overview

Updates the status of a semi-black SIM identified by its product number, in freebit's managed systems.

- Used to manage the lifecycle of semi-black SIMs (cancel, mark as lost, returned, etc.)
- For white SIM inventory processing, use **PA05-15** (MVNO White SIM Status Change) instead
- Setting status to `"60"` (cancelled) is a prerequisite for using the overwrite flag in **PA05-18**

---

## Request

### Method

`POST` (JSON format)

### URL

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

### 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   | 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`) |
| 3   | account           | Account                | 1     | Half-width numeric | 11  | 14  | ◎        | Target SIM phone number. Can be omitted when mnp.method is `"20"` (OTA). Required otherwise                                                    |
| 4   | mnp               | MNP Info               | 1     | Object             | -   | -   | -        | MNP information                                                                                                                                |
| 5   | mnp.method        | MNP Method             | 2     | Half-width numeric | 2   | 2   | ◎        | `"10"`: Semi-black SIM, `"20"`: OTA                                                                                                            |
| 6   | 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                                        |
| 7   | state             | State                  | 1     | Half-width numeric | 1   | 2   | ◎        | Target SIM usage state (see State Values below)                                                                                                |

**Legend:** ◎ Required | △ Conditional

### State Values

| Code | Name                    | Description                                                                      |
| ---- | ----------------------- | -------------------------------------------------------------------------------- |
| 5    | OEM Received            | SIM received into OEM inventory                                                  |
| 10   | Semi-black (= Temp Reg) | Temporary registration state                                                     |
| 20   | Burn Failure / Reissue  | SIM burn failed, needs reissue                                                   |
| 30   | Lost / Reissue          | SIM lost, needs reissue                                                          |
| 40   | Used                    | SIM has been used/consumed                                                       |
| 50   | Damaged                 | SIM is physically damaged                                                        |
| 60   | Cancelled               | Cancelled (e.g., MNP reservation invalid). **Required before PA05-18 overwrite** |
| 70   | OEM Collected           | SIM collected/recovered by OEM                                                   |
| 71   | OEM Uncollectable       | SIM cannot be collected by OEM                                                   |
| 80   | Returned to FB          | SIM returned to freebit                                                          |

---

## Request Example

```json
{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "productNumber": "ZZ0009999999999",
  "account": "08011112222",
  "mnp": {
    "method": "10",
    "reserveNumber": "1101201234"
  },
  "state": "10"
}
```

---

## 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         | 306         | Bad Request | Parameter error - MNP method issue                    |
| ×      | 400         | 307         | Bad Request | Parameter error - MNP reservation number issue        |
| ×      | 400         | 280         | Bad Request | Parameter error - state value issue                   |
| ×      | 403         | 205         | Auth Error  | Authentication key problem                            |
| ×      | 404         | 281         | Not Found   | Specified product number does not exist               |
| ×      | 500         | 282         | NG          | State transition not allowed (invalid state change)   |
| ×      | 500         | 900         | NG          | Unexpected error occurred                             |

---

## Response Example

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

---

## Related APIs

| API     | Name                                           | Relationship                                                  |
| ------- | ---------------------------------------------- | ------------------------------------------------------------- |
| PA05-15 | MVNO White SIM Status Change                   | Similar API for white SIMs (inventory processing)             |
| PA05-18 | MVNO Semi-Black Account Temporary Registration | Queues SIMs; overwrite flag requires this API to cancel first |
| PA05-19 | MVNO Semi-Black Account Registration           | Activates SIMs after temp registration                        |