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>
142 lines
9.9 KiB
Markdown
142 lines
9.9 KiB
Markdown
# 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 |
|