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>
138 lines
7.6 KiB
Markdown
138 lines
7.6 KiB
Markdown
# 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 |
|