# 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"
  }
}
```