diff --git a/Multilingual-Implementation-Plan.docx b/Multilingual-Implementation-Plan.docx new file mode 100644 index 00000000..123e16ec Binary files /dev/null and b/Multilingual-Implementation-Plan.docx differ diff --git a/freebit-api-docs/PA02-01_account-registration.md b/freebit-api-docs/PA02-01_account-registration.md new file mode 100644 index 00000000..ca49b430 --- /dev/null +++ b/freebit-api-docs/PA02-01_account-registration.md @@ -0,0 +1,191 @@ +# PA02-01 - Account Registration (アカウント登録) + +## Overview + +Creates a new account for the requested service. + +- Account creation is **asynchronous** - may take up to 10 minutes from specified time +- When using User Management Service: + - Master account on PTv2 is required; other service accounts are optional + - Master account can be created new or use existing + - All created accounts are linked via the master account + +--- + +## Request + +### Method + +`POST` (JSON format) + +### URL + +``` +https://[host]/emptool/api/master/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 | +| 2 | version | Version Info | △ | Version number specified by freebit | + +### JSON Parameters + +| No | Parameter | Name | Level | Type | Required | Description | +| --- | ----------------------- | ------------------ | ----- | ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------- | +| 1 | authKey | Authentication Key | 1 | Alphanumeric | ◎ | Obtained from OEM authentication | +| 2 | masterAccount | Master Account | 1 | Alphanumeric + symbols | △ | IIC master account. Required when using User Management Service | +| 3 | masterPassword | Master Password | 1 | Alphanumeric + symbols | △ | IIC master password. Required when createType is "new" with User Management Service | +| 4 | startDate | Start Date | 1 | Alphanumeric | - | Date when account becomes active. Immediate if not specified | +| 5 | createType | Registration Type | 1 | Alphanumeric | ◎ | `"new"`: Create new master account, `"add"`: Add to existing. "add" not allowed without User Management Service | +| 6 | relationCode | Relation Code | 1 | Alphanumeric | △ | Required when using User Management Service | +| 7 | requestDatas | Request Data | 1 | Array | ◎ | List of service accounts to create | +| 8 | requestDatas[].kind | Service Type | 2 | Alphanumeric | ◎ | Service type (e.g., "MVNO", "MASTER") | +| 9 | requestDatas[].account | Account | 2 | Alphanumeric + symbols | ○ | Service account. For MVNO, specify phone number | +| 10 | requestDatas[].password | Login Password | 2 | Alphanumeric + symbols | △ | Service password. Not specified for MVNO | +| 11 | requestDatas[].planCode | Plan Code | 2 | Alphanumeric | △ | Plan to apply (MVNO) | + +### MVNO Service Options + +| No | Parameter | Name | Type | Min | Max | Required | Description | +| --- | --------- | ------------------ | ------------------ | --- | --- | -------- | ------------------------------------------- | +| 1 | globalIp | Global IP (yes/no) | Half-width numeric | 2 | 2 | △ | Whether to use global IP. Contract required | + +**Legend:** ◎ Required | ○ Required within level | △ Conditional + +--- + +## Request Examples + +### Without User Management Service + +```json +{ + "authKey": "XXXXXXXXXX", + "createType": "new", + "requestDatas": [ + { + "kind": "MVNO", + "account": "08038433843", + "planCode": "LTE3G_P01" + } + ] +} +``` + +### With User Management Service + +```json +{ + "authKey": "XXXXXXXXXX", + "masterAccount": "testAccount@test.ne.jp", + "masterPassword": "password123", + "createType": "new", + "relationCode": "BA-ABA-001", + "requestDatas": [ + { + "kind": "MVNO", + "account": "08038433843", + "planCode": "LTE3G_P01" + } + ] +} +``` + +--- + +## Response + +### Format + +JSON + +### Parameters + +| No | Parameter | Name | Level | Type | Description | +| --- | -------------------------- | ------------- | ----- | ---------------------- | ------------------------------------------------------------------------ | +| 1 | resultCode | Result Code | 1 | Numeric | Overall result code | +| 2 | status | Status | 1 | Object | Overall status | +| 3 | status.message | Message | 2 | Alphanumeric + symbols | Overall result message | +| 4 | status.statusCode | Status Code | 2 | Numeric | Overall status code | +| 5 | responseDatas | Response Data | 1 | Array | Processed service account information | +| 6 | responseDatas[].kind | Service Type | 2 | Alphanumeric + symbols | Service type | +| 7 | responseDatas[].resultCode | Result Code | 2 | Numeric | Per-account result code | +| 8 | responseDatas[].account | Account | 2 | Alphanumeric + symbols | For MVNO, phone number is returned | +| 9 | responseDatas[].ipv4 | IPv4 Address | 2 | Alphanumeric + symbols | Allocated IP if fixed IP specified. Empty ("") if not. Contract required | +| 10 | responseDatas[].ipv6 | IPv6 Address | 2 | Alphanumeric + symbols | Allocated IP if fixed IP specified. Empty ("") if not. Contract required | + +--- + +## Response Codes + +| Status | Status Code | Detail Code | Message | Description | +| ------ | ----------- | ----------- | ----------- | ------------------------------------------------------ | +| ○ | 200 | 100 | OK | Success | +| × | 400 | 200 | Bad Request | Parameter error - kind issue | +| × | 400 | 201 | Bad Request | Parameter error - account/to/tempAccount issue | +| × | 400 | 202 | Bad Request | Parameter error - password issue | +| × | 400 | 204 | Bad Request | Parameter error - other parameter issue | +| × | 400 | 220 | Bad Request | Specified plan does not exist | +| × | 500 | 208 | NG | Account duplicate error | +| × | 500 | 210 | NG | Account not found error | +| × | 500 | 212 | NG | Request failed due to error in another service account | +| × | 500 | 233 | NG | Specified service is not provided | +| × | 500 | 900 | NG | Unexpected error occurred | + +--- + +## Response Examples + +### Without User Management Service (Success) + +```json +{ + "resultCode": "100", + "status": { + "message": "OK", + "statusCode": "200" + }, + "responseDatas": [ + { + "kind": "MVNO", + "account": "09999999999", + "ipv4": "", + "ipv6": "", + "resultCode": "100" + } + ] +} +``` + +### With User Management Service (Success) + +```json +{ + "resultCode": "100", + "status": { + "message": "OK", + "statusCode": "200" + }, + "responseDatas": [ + { + "kind": "MASTER", + "account": "testAccount@test.ne.jp", + "resultCode": "100" + }, + { + "kind": "MVNO", + "account": "09999999999", + "ipv4": "", + "ipv6": "", + "resultCode": "100" + } + ] +} +``` diff --git a/freebit-api-docs/PA02-04_account-cancellation.md b/freebit-api-docs/PA02-04_account-cancellation.md new file mode 100644 index 00000000..571ccdf1 --- /dev/null +++ b/freebit-api-docs/PA02-04_account-cancellation.md @@ -0,0 +1,116 @@ +# PA02-04 - Account Cancellation (アカウント解約) + +## Overview + +Cancels the specified service account. + +- Account cancellation is **asynchronous** - may take up to 10 minutes from specified time +- **Master account cannot be cancelled** via this API + +--- + +## Request + +### Method + +`POST` (JSON format) + +### URL + +``` +https://[host]/emptool/api/master/cnclAcnt/ +``` + +### 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 | Required | Description | +| --- | --------- | ------------------ | ----- | ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------- | +| 1 | authKey | Authentication Key | 1 | Alphanumeric | ◎ | Obtained from OEM authentication | +| 2 | kind | Service Type | 1 | Alphanumeric + symbols | ◎ | Target service. Master account not allowed | +| 3 | account | Account | 1 | Alphanumeric + symbols | ◎ | Target account. For MVNO, specify phone number | +| 4 | runDate | Scheduled Date | 1 | Half-width numeric | - | Cancellation date. Format: `YYYYMMDD` (also accepts `YYYY/MM/DD`, `YYYY-MM-DD`). Immediate if not specified | + +**Legend:** ◎ Required + +--- + +## Request Example + +### Immediate Cancellation + +```json +{ + "authKey": "XXXXXXXXXX", + "kind": "MVNO", + "account": "08038433843" +} +``` + +### Scheduled Cancellation + +```json +{ + "authKey": "XXXXXXXXXX", + "kind": "MVNO", + "account": "08038433843", + "runDate": "20240331" +} +``` + +--- + +## Response + +### Format + +JSON + +### Parameters + +| No | Parameter | Name | Level | Type | Required | Description | +| --- | ----------------- | ----------- | ----- | ---------------------- | -------- | ------------------- | +| 1 | resultCode | Result Code | 1 | Numeric | ◎ | Overall result code | +| 2 | status | Status | 1 | Object | ◎ | - | +| 3 | status.message | Message | 2 | Alphanumeric + symbols | ◎ | Result message | +| 4 | status.statusCode | Status Code | 2 | Numeric | ◎ | Result code | + +--- + +## Response Codes + +| Status | Status Code | Detail Code | Message | Description | +| ------ | ----------- | ----------- | ----------- | --------------------------------------------- | +| ○ | 200 | 100 | OK | Success | +| ○ | 200 | 101 | OK | Already satisfies request (already cancelled) | +| × | 400 | 200 | Bad Request | Parameter error - kind issue | +| × | 400 | 201 | Bad Request | Parameter error - account issue | +| × | 400 | 204 | Bad Request | Parameter error - other parameter issue | +| × | 400 | 228 | Bad Request | Parameter error - authKey issue | +| × | 403 | 205 | Auth Error | Authentication key problem | +| × | 500 | 210 | NG | Account not found | +| × | 500 | 230 | NG | Account is waiting for async processing | +| × | 500 | 900 | NG | Unexpected error occurred | + +--- + +## Response Example + +```json +{ + "resultCode": "100", + "status": { + "message": "OK", + "statusCode": "200" + } +} +``` diff --git a/freebit-api-docs/PA03-02_account-detail-info.md b/freebit-api-docs/PA03-02_account-detail-info.md new file mode 100644 index 00000000..dc51409f --- /dev/null +++ b/freebit-api-docs/PA03-02_account-detail-info.md @@ -0,0 +1,240 @@ +# PA03-02 - Account Detail Information (アカウント詳細情報取得) + +## Overview + +Returns detailed information for the requested account/service. Only one account can be specified per request. + +- **Non-master account**: Returns service details + linked master account info +- **Master account**: Returns list of all linked accounts (without individual details) + +--- + +## Request + +### Method + +`POST` (JSON format) + +### 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 | Required | Description | +| --- | ---------------------- | ------------------ | ----- | ---------------------- | -------- | ----------------------------------------------------------------------------------------------- | +| 1 | authKey | Authentication Key | 1 | Alphanumeric | ◎ | Obtained from OEM authentication | +| 2 | displayPass | Display Password | 1 | Numeric | △ | Whether to return password. Not processed for MVNO. `10`: Return, `20`: Do not return (default) | +| 3 | version | Version | 1 | Alphanumeric | △ | Version number specified by freebit | +| 4 | requestDatas | Request Data | 1 | Array | ◎ | Target account info. List format but only 1 item recognized | +| 5 | requestDatas[].kind | Service Type | 2 | Alphanumeric + symbols | ◎ | Target service. `"MASTER"` for master account | +| 6 | requestDatas[].account | Account | 2 | Alphanumeric + symbols | ◎ | Target account. For MVNO, specify phone number | + +**Legend:** ◎ Required | ○ Required within level | △ Conditional + +--- + +## Request Examples + +### Get Master Account Info + +```json +{ + "authKey": "XXXXXXXXXX", + "requestDatas": [ + { + "kind": "MASTER", + "account": "testMaster@test.ne.jp" + } + ] +} +``` + +### Get MVNO Account Info + +```json +{ + "authKey": "XXXXXXXXXX", + "version": "2", + "requestDatas": [ + { + "kind": "MVNO", + "account": "08038433843" + } + ] +} +``` + +--- + +## Response + +### Format + +JSON + +### Base Parameters + +| No | Parameter | Name | Level | Type | Description | +| --- | ------------------------ | -------------- | ----- | ---------------------- | ------------------------------------------ | +| 1 | resultCode | Result Code | 1 | Numeric | Overall result code | +| 2 | status | Status | 1 | Object | - | +| 3 | status.message | Message | 2 | Alphanumeric + symbols | Result message | +| 4 | status.statusCode | Status Code | 2 | Numeric | Result code | +| 5 | masterAccount | Master Account | 1 | Alphanumeric + symbols | Master account linked to requested account | +| 6 | responseDatas | Response Data | 1 | Array/Object | Processed service account information | +| 7 | responseDatas.resultCode | Result Code | 2 | Numeric | Per-account result code | +| 8 | responseDatas.kind | Service Type | 2 | Alphanumeric + symbols | Service type | +| 9 | responseDatas.account | Account | 2 | Alphanumeric + symbols | Account identifier | +| 10 | responseDatas.state | State | 2 | Alphanumeric + symbols | Account state (see State Values) | +| 11 | responseDatas.startDate | Start Date | 2 | Alphanumeric | Activation date (YYYYMMDD) | +| 12 | responseDatas.async | Async Request | 2 | Object | Pending async request. Empty `{}` if none | +| 13 | responseDatas.async.func | Function | 3 | Alphabetic | Async operation type (see Async Functions) | +| 14 | responseDatas.async.date | Date | 3 | Alphabetic | Scheduled execution date (YYYYMMDD) | + +### State Values + +| Value | Description | +| --------- | ----------------------------- | +| waiting | Waiting for setup (MVNO only) | +| temporary | Temporary registration | +| active | In service | +| suspended | Suspended | +| obsolete | Cancelled | + +### Async Function Values + +| Value | Description | +| --------- | --------------- | +| regist | Registration | +| stop | Suspension | +| resume | Resumption | +| cancel | Cancellation | +| revival | Revival | +| plnset | Plan set | +| plnunset | Plan unset | +| change | Change | +| chgctract | Contract change | + +--- + +## MVNO-Specific Response Parameters + +| Parameter | Name | Type | Description | +| ------------ | ------------- | ---------------------- | ----------------------------------- | +| planCode | Plan Code | Alphanumeric + symbols | Empty ("") if no plan set | +| iccid | SIM Card ID | Numeric | SIM card identifier | +| imsi | SIM ID | Numeric | SIM identifier | +| contractLine | Contract Line | Alphanumeric | Line type (e.g., "4G") | +| size | SIM Size | Alphabetic | `standard`, `nano`, `micro` | +| sms | SMS Status | Numeric | `10`: Active, `20`: Inactive | +| talk | Voice Status | Numeric | `10`: Active, `20`: Inactive | +| ipv4 | IPv4 Address | Alphanumeric + symbols | Empty ("") if not using global IPv4 | +| ipv6 | IPv6 Address | Alphanumeric + symbols | Empty ("") if not using global IPv6 | +| quota | Quota | Numeric | Data quota value | + +### Voice Option Parameters (Level 3) + +| Parameter | Name | Type | Description | +| -------------------- | ---------------------- | ---------------------- | ------------------------------------------------------- | +| state | State | Alphanumeric + symbols | `waiting`, `temporary`, `active`, `obsolete` | +| voiceMail | Voicemail | Numeric | `10`: Enabled, `20`: Disabled | +| callWaiting | Call Waiting | Numeric | `10`: Enabled, `20`: Disabled | +| callTransfer | Call Transfer | Numeric | `10`: Enabled, `20`: Disabled | +| callTransferToWorld | International Transfer | Numeric | `10`: Enabled, `20`: Disabled | +| worldCall | WORLD CALL | Numeric | `10`: Amount specified, `11`: Unlimited, `20`: Disabled | +| worldCallCreditLimit | WORLD CALL Limit | Numeric | Amount (when worldCall is `10`) | +| worldWing | WORLD WING | Numeric | `10`: Amount specified, `11`: Unlimited, `20`: Disabled | +| worldWingCreditLimit | WORLD WING Limit | Numeric | Amount 50000-1000000 (when worldWing is `10`) | +| async | Async Request | Object | Voice option async request | + +--- + +## Response Codes + +| Status | Status Code | Detail Code | Message | Description | +| ------ | ----------- | ----------- | ----------- | --------------------------------------- | +| ○ | 200 | 100 | OK | Success | +| × | 400 | 200 | Bad Request | Parameter error - kind issue | +| × | 400 | 201 | Bad Request | Parameter error - account issue | +| × | 400 | 204 | Bad Request | Parameter error - other parameter issue | +| × | 400 | 226 | Bad Request | Parameter error - displayPass issue | +| × | 400 | 227 | Bad Request | Parameter error - requestDatas issue | +| × | 400 | 228 | Bad Request | Parameter error - authKey issue | +| × | 400 | 236 | Bad Request | Parameter error - version issue | +| × | 403 | 205 | Auth Error | Authentication key problem | +| × | 500 | 210 | NG | Account not found | +| × | 500 | 211 | NG | Account status does not allow request | + +--- + +## Response Examples + +### Master Account Query + +```json +{ + "resultCode": 100, + "status": { + "message": "OK", + "statusCode": 200 + }, + "masterAccount": "testMaster@test.ne.jp", + "responseDatas": [ + { + "kind": "MASTER", + "account": "testAccount@test.ne.jp", + "state": "active", + "startDate": 20120401, + "relationCode": "testuser", + "resultCode": 100 + }, + { + "kind": "MVNO", + "account": 8038433843, + "state": "suspended", + "resultCode": 100 + } + ] +} +``` + +### MVNO Account Query (with async) + +```json +{ + "resultCode": 100, + "status": { + "message": "OK", + "statusCode": 200 + }, + "masterAccount": "testMaster@test.ne.jp", + "responseDatas": { + "kind": "MVNO", + "account": 8038433843, + "state": "active", + "planCode": "LTE3G_P01", + "startDate": 20130901, + "iccid": 8981199993109195000, + "imsi": 990103120337753, + "contractLine": "4G", + "size": "standard", + "sms": 10, + "talk": 10, + "ipv4": "", + "ipv6": "", + "quota": 3161.31, + "async": { + "func": "regist", + "date": 20131201 + }, + "resultCode": "100" + } +} +``` diff --git a/freebit-api-docs/PA04-04_spec-quota-add.md b/freebit-api-docs/PA04-04_spec-quota-add.md new file mode 100644 index 00000000..90838c56 --- /dev/null +++ b/freebit-api-docs/PA04-04_spec-quota-add.md @@ -0,0 +1,119 @@ +# PA04-04 - Spec/Quota Addition (スペック・クォータ追加) + +## Overview + +Adds account spec to the specified service account. + +- "Spec" meaning varies by service type +- Available for **MVNO service** only +- Works for **regular SIM** and **share groups** +- NOT available for SIMs belonging to a share group + +--- + +## Request + +### Method + +`POST` (JSON format) + +### JSON Parameters + +| No | Parameter | Name | Level | Type | Min | Max | Required | Description | +| --- | --------- | ------------------ | ----- | --------------------------------- | --- | --- | -------- | ---------------------------------------------------------------------------- | +| 1 | authKey | Authentication Key | 1 | Alphanumeric | - | - | ◎ | Obtained from OEM authentication | +| 2 | kind | Service Type | 1 | Alphanumeric + symbols | - | - | ○ | Target service. Only MVNO allowed | +| 3 | account | Account | 1 | Alphanumeric + symbols | - | - | ◎ | Target account. For MVNO: phone number (regular SIM) or share group code | +| 4 | quota | Quota | 1 | Half-width numeric | 1 | 6 | ◎ | Capacity to add in **MB** (1 - 512000 MB) | +| 5 | quotaCode | Quota Code | 1 | Half-width alphanumeric + symbols | 1 | 512 | △ | Optional identifier. Returned in PA05-02 quota history | +| 6 | expire | Expiration Date | 1 | Half-width numeric | 8 | 8 | △ | Expiration date for quota (YYYYMMDD). Ignored if expiration not configurable | + +**Legend:** ◎ Required | ○ Required within level | △ Optional + +--- + +## Request Examples + +### Add 100MB to Regular SIM + +```json +{ + "authKey": "XXXXXXXXXX", + "kind": "MVNO", + "account": "09012345678", + "quota": "100" +} +``` + +### Add 10000MB to Share Group (with code and expiration) + +```json +{ + "authKey": "XXXXXXXXXX", + "kind": "MVNO", + "account": "QUMB_00000000001", + "quota": "10000", + "quotaCode": "campaign-100", + "expire": "20131231" +} +``` + +--- + +## Response + +### Format + +JSON + +### Parameters + +| No | Parameter | Name | Level | Type | Description | +| --- | ----------------- | ----------- | ----- | ---------------------- | ------------------- | +| 1 | resultCode | Result Code | 1 | Numeric | Overall result code | +| 2 | status | Status | 1 | Object | - | +| 3 | status.message | Message | 2 | Alphanumeric + symbols | Result message | +| 4 | status.statusCode | Status Code | 2 | Numeric | Result code | + +--- + +## Response Codes + +| Status | Status Code | Detail Code | Message | Description | +| ------ | ----------- | ----------- | ----------- | ------------------------------------------- | +| ○ | 200 | 100 | OK | Success | +| × | 400 | 200 | Bad Request | Parameter error - kind issue | +| × | 400 | 201 | Bad Request | Parameter error - account issue | +| × | 400 | 204 | Bad Request | Parameter error - other parameter issue | +| × | 400 | 221 | Bad Request | Parameter error - quota issue | +| × | 400 | 237 | Bad Request | Parameter error - quotaCode issue | +| × | 403 | 205 | Auth Error | Authentication key problem | +| × | 404 | 323 | Not Found | Share group not found | +| × | 500 | 210 | NG | Account not found | +| × | 500 | 211 | NG | Account status does not allow request | +| × | 500 | 230 | NG | Account is waiting for async processing | +| × | 500 | 233 | NG | Specified service is not provided | +| × | 500 | 234 | NG | Addition to specified spec not allowed | +| × | 500 | 322 | NG | Share group status does not allow request | +| × | 500 | 325 | NG | Share group is waiting for async processing | +| × | 500 | 900 | NG | Unexpected error occurred | + +--- + +## Response Example + +```json +{ + "resultCode": "100", + "status": { + "message": "OK", + "statusCode": "200" + } +} +``` + +--- + +## Related APIs + +- **PA05-02**: MVNO Quota Addition History - retrieves quota addition history including quotaCode diff --git a/freebit-api-docs/PA05-01_mvno-traffic-info.md b/freebit-api-docs/PA05-01_mvno-traffic-info.md new file mode 100644 index 00000000..abfce592 --- /dev/null +++ b/freebit-api-docs/PA05-01_mvno-traffic-info.md @@ -0,0 +1,142 @@ +# PA05-01 - MVNO Traffic Information (MVNO通信情報取得) + +## Overview + +Returns current plan traffic information for the requested MVNO service account. + +- Only **one account** can be specified per request +- Cannot retrieve traffic info if no plan is set +- Available for **regular SIM** and **share groups** only +- NOT available for SIMs belonging to a share group + +--- + +## Usage Notes & Restrictions + +> **Warning**: This API is for per-SIM (phone number) or per-share-group (share group code) queries. +> +> - **Do NOT use for bulk retrieval** of multiple SIMs under an operator +> - Bulk queries cause high server load and affect other operators +> - For bulk SIM data, contact freebit for CSV/TXT export options + +--- + +## Request + +### Method + +`POST` (JSON format) + +### URL + +``` +https://[host]/emptool/api/mvno/getTrafficInfo/ +``` + +### JSON Parameters + +| No | Parameter | Name | Level | Type | Required | Description | +| --- | --------- | ------------------ | ----- | ---------------------- | -------- | --------------------------------------- | +| 1 | authKey | Authentication Key | 1 | Alphanumeric | ◎ | Obtained from OEM authentication | +| 2 | account | Account | 1 | Alphanumeric + symbols | ◎ | Target phone number or share group code | + +**Legend:** ◎ Required | △ Conditional + +--- + +## Request Examples + +### MVNO Account Traffic + +```json +{ + "authKey": "XXXXXXXXXX", + "account": "09012345678" +} +``` + +### Share Group Traffic + +```json +{ + "authKey": "XXXXXXXXXX", + "account": "AAA0_00000000001" +} +``` + +--- + +## Response + +### Format + +JSON + +### Parameters + +| No | Parameter | Name | Level | Type | Description | +| --- | -------------------- | ------------ | ----- | ---------------------- | ------------------------------------------------------------------- | +| 1 | resultCode | Result Code | 1 | Numeric | Overall result code | +| 2 | status | Status | 1 | Object | - | +| 3 | status.message | Message | 2 | Alphanumeric + symbols | Result message | +| 4 | status.statusCode | Status Code | 2 | Numeric | Result code | +| 5 | account | Account | 1 | Alphanumeric + symbols | Queried account | +| 6 | traffic | Traffic Info | 1 | Object | Traffic data for target date | +| 7 | traffic.today | Today | 2 | Numeric | Traffic used today (KB). `0` if no traffic | +| 8 | traffic.inRecentDays | Recent Days | 2 | String | Comma-separated daily traffic (KB). **Empty ("") for share groups** | +| 9 | traffic.blackList | Blacklist | 2 | Numeric | `10`: Blacklisted, `20`: Not blacklisted | + +--- + +## Response Codes + +| Status | Status Code | Detail Code | Message | Description | +| ------ | ----------- | ----------- | ----------- | --------------------------------------- | +| ○ | 200 | 100 | OK | Success | +| × | 400 | 201 | Bad Request | Parameter error - account issue | +| × | 400 | 204 | Bad Request | Parameter error - other parameter issue | +| × | 403 | 205 | Auth Error | Authentication key problem | +| × | 404 | 323 | Not Found | Share group not found | +| × | 500 | 210 | NG | Account not found | +| × | 500 | 211 | NG | Account status does not allow request | +| × | 500 | 240 | NG | Specified phone number issue | + +--- + +## Response Examples + +### MVNO Account + +```json +{ + "resultCode": "100", + "status": { + "message": "OK", + "statusCode": "200" + }, + "account": "09012345678", + "traffic": { + "today": "100", + "inRecentDays": "100,200,300", + "blackList": "10" + } +} +``` + +### Share Group + +```json +{ + "resultCode": "100", + "status": { + "message": "OK", + "statusCode": "200" + }, + "account": "AAA0_00000000001", + "traffic": { + "today": "100", + "inRecentDays": "", + "blackList": "10" + } +} +``` diff --git a/freebit-api-docs/PA05-21_mvno-plan-change.md b/freebit-api-docs/PA05-21_mvno-plan-change.md new file mode 100644 index 00000000..6dc5ce11 --- /dev/null +++ b/freebit-api-docs/PA05-21_mvno-plan-change.md @@ -0,0 +1,95 @@ +# PA05-21 - MVNO Plan Change (MVNOプラン変更) + +## Overview + +Changes (removes & sets) the plan configured on the requested account/MVNO service account. + +- Can be used for accounts currently in service +- Execution can be immediate or scheduled for a specified date/time + +--- + +## Request + +### Method + +`POST` (JSON format) + +### URL + +``` +https:// +``` + +### Parameters + +| No | Parameter | Name | Type | Min | Max | Required | Description | +| --- | --------- | ------------------ | ---------------------- | --- | --- | -------- | --------------------------------------------------------------------------------------------------- | +| 1 | authKey | Authentication Key | Alphanumeric | - | - | ◎ | Obtained from OEM authentication | +| 2 | account | Account | Alphanumeric + symbols | - | - | ◎ | Target SIM phone number | +| 3 | planCode | Plan Code | Half-width numeric | 1 | 32 | ◎ | Specify the plan to apply | +| 4 | globalIp | Global IP (yes/no) | Half-width numeric | 2 | 2 | △ | Whether to use global IP. Contract required. `20`: Disabled. If not specified, processing continues | +| 5 | runTime | Execution Time | Half-width numeric | - | - | - | Scheduled execution date (YYYYMMDD format) | + +### Request Example + +```json +{ + "authKey": "XXXXXXXXXX", + "account": "09012345678", + "planCode": "LTE3G_P01", + "globalIp": "20", + "runTime": "20150227" +} +``` + +--- + +## Response + +### Format + +JSON + +### Parameters + +| No | Parameter | Name | Type | Description | +| --- | ----------------- | ------------------ | --------------------------------- | ----------------------------------------------------------------------------------------------- | +| 1 | resultCode | Result Code | Numeric | Processing result code | +| 2 | status | Status | Object | Status details | +| 3 | status.message | Message | Alphanumeric + symbols | Processing result message | +| 4 | status.statusCode | Detail Result Code | Numeric | Detailed processing result code | +| 5 | ipv4 | IPv4 Address | Half-width numeric + symbols | Allocated IP address if fixed IP was specified. Empty ("") if not specified. Contract required. | +| 6 | ipv6 | IPv6 Address | Half-width alphanumeric + symbols | Allocated IP address if fixed IP was specified. Empty ("") if not specified. Contract required. | + +--- + +## Response Codes + +| Status | Status Code | Detail Code | Message | Description | +| ------ | ----------- | ----------- | ----------- | ----------------------------------------------- | +| ○ | 200 | 100 | OK | Success | +| × | 400 | 220 | Bad Request | Parameter error - planCode issue | +| × | 400 | 231 | Bad Request | Parameter error - globalIp issue | +| × | 403 | 205 | Auth Error | Authentication key problem | +| × | 500 | 210 | NG | Account not found | +| × | 500 | 211 | NG | Account status does not allow request execution | +| × | 500 | 230 | NG | Account is waiting for async processing | +| × | 500 | 330 | NG | Account belongs to a share group | +| × | 500 | 900 | NG | Unexpected error occurred | + +--- + +## Response Example + +```json +{ + "resultCode": 100, + "status": { + "message": "OK", + "statusCode": 100 + }, + "ipv4": "", + "ipv6": "" +} +```