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