> For the complete documentation index, see [llms.txt](https://docs.mmoweb.biz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mmoweb.biz/rest-api/master-akkaunt/poluchenie-master-akkaunta.md).

# Получение мастер-аккаунта

#### Описание

Endpoint возвращает данные одного мастер-аккаунта проекта, к которому привязан ваш Application Token.

Аккаунт можно найти по одному из трёх идентификаторов: `user_id`, `email` или `phone`. Набор полей в ответе совпадает с полями элемента списка из endpoint'а [Список мастер-аккаунтов](/rest-api/master-akkaunt/spisok-master-akkauntov.md), поэтому оба endpoint'а можно обрабатывать одной моделью данных.

Вы можете использовать данный endpoint для:

* Проверки существования аккаунта перед начислением баланса или выдачей предметов
* Получения `user_id` по email или телефону из внешней системы
* Отображения профиля игрока в CRM, службе поддержки или боте

> Endpoint возвращает персональные данные пользователя (email, телефон, IP). Выдавайте право `Получение мастер аккаунта (v2)` только тем ключам, которым оно действительно необходимо.

***

#### Endpoint

```
GET https://api.mmoweb.biz/v2/master-account
```

**Требуемое разрешение ключа:** `Получение мастер аккаунта (v2)`

***

#### Параметры

Все параметры передаются в строке запроса (query string). Необходимо передать **хотя бы один** идентификатор.

| Параметр  | Тип     | Обязателен                               | Формат                                                 | Описание                      |
| --------- | ------- | ---------------------------------------- | ------------------------------------------------------ | ----------------------------- |
| `user_id` | integer | Да, если не переданы `email` и `phone`   | Целое число `≥ 1`                                      | Идентификатор мастер-аккаунта |
| `email`   | string  | Да, если не переданы `user_id` и `phone` | Валидный email без пробелов                            | Email мастер-аккаунта         |
| `phone`   | string  | Да, если не переданы `user_id` и `email` | Только цифры, от 7 до 18 символов, первая цифра не `0` | Телефон мастер-аккаунта       |

> **Приоритет идентификаторов.** Если передано несколько параметров, используется первый непустой в порядке `user_id` → `email` → `phone`, остальные игнорируются. Например, при запросе `?user_id=123&email=user@example.com` поиск выполняется только по `user_id`.

> **Формат телефона.** Передавайте телефон одной строкой цифр: код страны и номер, без `+`, пробелов, скобок и дефисов. Например, `+7 (900) 123-45-67` передаётся как `79001234567`. Код страны обязателен и должен совпадать с тем, что указан у пользователя.

***

#### Кодировка

**Запрос**

* Значения параметров передаются в кодировке UTF-8 и должны быть URL-кодированы (percent-encoding), как и любые данные в query string.
* Символ `+` в email обязательно кодируйте как `%2B`. Незакодированный `+` в query string читается как пробел, и такой email не пройдёт проверку.
* Символ `@` допускается как в исходном виде, так и в виде `%40`.
* Пробелы в значениях не допускаются, в том числе по краям.

| Исходное значение        | Значение в query string                                    |
| ------------------------ | ---------------------------------------------------------- |
| `user@example.com`       | `email=user%40example.com` или `email=user@example.com`    |
| `user+promo@example.com` | `email=user%2Bpromo%40example.com`                         |
| `+7 (900) 123-45-67`     | `phone=79001234567` (после очистки от нецифровых символов) |

Стандартные средства формирования query string кодируют значения автоматически: `URLSearchParams` в JavaScript, `http_build_query()` в PHP, `--data-urlencode` в cURL.

**Ответ**

Ответ возвращается в формате JSON в кодировке UTF-8 с заголовком `Content-Type: application/json`.

***

#### Примеры

**Поиск по user\_id**

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET "https://api.mmoweb.biz/v2/master-account?user_id=123" \
  -H "Authorization: Bearer APPLICATION_TOKEN_HERE"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const token = 'APPLICATION_TOKEN_HERE';

const params = new URLSearchParams({ user_id: 123 });

fetch(`https://api.mmoweb.biz/v2/master-account?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$token = 'APPLICATION_TOKEN_HERE';

$url = 'https://api.mmoweb.biz/v2/master-account?' . http_build_query([
  'user_id' => 123
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . $token
  ]
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

echo "HTTP Status: " . $httpCode . "\n";
echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
?>
```

{% endtab %}
{% endtabs %}

**Поиск по email**

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET -G "https://api.mmoweb.biz/v2/master-account" \
  --data-urlencode "email=user+promo@example.com" \
  -H "Authorization: Bearer APPLICATION_TOKEN_HERE"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const token = 'APPLICATION_TOKEN_HERE';

const params = new URLSearchParams({ email: 'user+promo@example.com' });

fetch(`https://api.mmoweb.biz/v2/master-account?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$token = 'APPLICATION_TOKEN_HERE';

$url = 'https://api.mmoweb.biz/v2/master-account?' . http_build_query([
  'email' => 'user+promo@example.com'
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . $token
  ]
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

echo "HTTP Status: " . $httpCode . "\n";
echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
?>
```

{% endtab %}
{% endtabs %}

**Поиск по телефону**

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET "https://api.mmoweb.biz/v2/master-account?phone=79001234567" \
  -H "Authorization: Bearer APPLICATION_TOKEN_HERE"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const token = 'APPLICATION_TOKEN_HERE';

const rawPhone = '+7 (900) 123-45-67';
const phone = rawPhone.replace(/\D/g, '');

const params = new URLSearchParams({ phone });

fetch(`https://api.mmoweb.biz/v2/master-account?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$token = 'APPLICATION_TOKEN_HERE';

$rawPhone = '+7 (900) 123-45-67';
$phone = preg_replace('/\D/', '', $rawPhone);

$url = 'https://api.mmoweb.biz/v2/master-account?' . http_build_query([
  'phone' => $phone
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . $token
  ]
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

echo "HTTP Status: " . $httpCode . "\n";
echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
?>
```

{% endtab %}
{% endtabs %}

***

#### Ответы

**Успешный ответ (200 OK)**

```json
{
  "success": true,
  "account": {
    "id": 123,
    "email": "user@example.com",
    "phone": "79001234567",
    "shield": 0,
    "affiliate": 0,
    "select_lid": 1,
    "select_sid": 3,
    "project_id": 5,
    "status": 0,
    "desc_status": "",
    "created_at": "2026-01-01 10:00:00",
    "last_login": "2026-02-01 12:30:00",
    "last_ip": "203.0.113.10",
    "email_valid": 1,
    "lang": "ru",
    "iso": "RU",
    "telegram": ""
  }
}
```

**Поля аккаунта:**

| Поле          | Тип            | Описание                                                                         |
| ------------- | -------------- | -------------------------------------------------------------------------------- |
| `id`          | integer        | Идентификатор мастер-аккаунта                                                    |
| `email`       | string \| null | Email                                                                            |
| `phone`       | string \| null | Телефон. `"0"` означает, что телефон не указан                                   |
| `shield`      | integer        | Включена ли дополнительная защита аккаунта (`1` — да, `0` — нет)                 |
| `affiliate`   | integer        | Идентификатор пригласившего аккаунта, `0` — реферал не установлен                |
| `select_lid`  | integer        | Идентификатор выбранного логин-сервера                                           |
| `select_sid`  | integer        | Идентификатор выбранного игрового сервера                                        |
| `project_id`  | integer        | Идентификатор проекта                                                            |
| `status`      | integer        | Статус аккаунта (`0` — активный, `1` — email не подтверждён, `2` — заблокирован) |
| `desc_status` | string \| null | Сообщение, которое видит пользователь при блокировке                             |
| `created_at`  | string         | Дата регистрации в формате `YYYY-MM-DD HH:MM:SS`                                 |
| `last_login`  | string \| null | Дата последнего входа в формате `YYYY-MM-DD HH:MM:SS`                            |
| `last_ip`     | string \| null | IP-адрес последнего входа                                                        |
| `email_valid` | integer        | Подтверждён ли email (`1` — да, `0` — нет)                                       |
| `lang`        | string \| null | Язык интерфейса пользователя                                                     |
| `iso`         | string \| null | ISO-код страны                                                                   |
| `telegram`    | string \| null | Telegram пользователя                                                            |

**Не передан идентификатор (400 Bad Request)**

```json
{
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": "user_id, email or phone is required"
}
```

> **Когда встречается:** в запросе нет ни одного из параметров `user_id`, `email`, `phone`, либо все они пустые

**Неверный формат параметра (400 Bad Request)**

```json
{
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": {
    "phone": "The phone field is not in the correct format."
  }
}
```

> **Когда встречается:** `user_id` не является целым числом `≥ 1`, `email` не является валидным адресом либо `phone` содержит символы кроме цифр, начинается с `0` или не подходит по длине. В `message` возвращается объект, где ключ — имя параметра, а значение — описание ошибки

**Аккаунт не найден (404 Not Found)**

```json
{
  "success": false,
  "code": "USER_NOT_FOUND"
}
```

> **Когда встречается:** в проекте нет мастер-аккаунта с указанным идентификатором

**Недостаточно прав (403 Forbidden)**

```json
{
  "success": false,
  "code": "ACCESS_DENIED"
}
```

> **Когда встречается:** у Application Token не включено разрешение `Получение мастер аккаунта (v2)`

***

#### Коды ошибок

| Код                | HTTP Status | Описание                                                 | Что делать                                                                                        |
| ------------------ | ----------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `VALIDATION_ERROR` | 400         | Не передан идентификатор или он не соответствует формату | Передайте один из `user_id`, `email`, `phone` в формате из раздела «Параметры»                    |
| `USER_NOT_FOUND`   | 404         | Аккаунт с таким идентификатором не найден в проекте      | Проверьте идентификатор; для телефона убедитесь, что код страны указан так же, как у пользователя |
| `ACCESS_DENIED`    | 403         | У токена нет разрешения на этот endpoint                 | Включите разрешение `Получение мастер аккаунта (v2)` для ключа в панели администратора            |

Ошибки аутентификации (`EMPTY_TOKEN`, `INVALID_TOKEN`, `TOKEN_NOT_FOUND`, `TOKEN_DISABLED`) общие для всех endpoint'ов API v2 и описаны во введении.

***

#### Важные особенности

**Только текущий проект**

Токен привязан к одному проекту. Endpoint ищет аккаунт только среди мастер-аккаунтов этого проекта, параметра для выбора проекта нет. Для аккаунта другого проекта вернётся `USER_NOT_FOUND`.

**Один запрос — один аккаунт**

Endpoint всегда возвращает ровно один аккаунт или ошибку `USER_NOT_FOUND`. Для получения нескольких аккаунтов используйте [Список мастер-аккаунтов](/rest-api/master-akkaunt/spisok-master-akkauntov.md).

**Телефон — только цифры**

Запрос с `+`, пробелами, скобками или дефисами в `phone` отклоняется с `VALIDATION_ERROR`. Очищайте номер от нецифровых символов на своей стороне перед вызовом, как показано в примерах. Значение `0` не принимается: по нему нельзя найти аккаунт без телефона.

**Сравнение email**

Регистр букв в email не учитывается: `User@Example.com` и `user@example.com` находят один и тот же аккаунт. Алиасы вида `user+promo@example.com` и `user@example.com` считаются разными адресами.

***

#### Рекомендации

**Безопасность:**

* Храните Application Token на сервере и никогда не передавайте его в браузер или мобильное приложение
* Не логируйте ответ endpoint'а целиком: он содержит персональные данные пользователя
* Используйте HTTPS для всех запросов

**Надёжность:**

* Предпочитайте поиск по `user_id`: он однозначен и не зависит от формата email или телефона
* Обрабатывайте `USER_NOT_FOUND` как штатный результат, а не как сбой
* Реализуйте retry logic с экспоненциальной задержкой при ошибках 5xx и сетевых сбоях

**Интеграция:**

* Формируйте query string стандартными средствами языка, чтобы не ошибиться с кодированием `+` и `@`
* Сохраняйте `user_id` на своей стороне после первого успешного поиска по email или телефону
* Убедитесь, что токен приложения имеет разрешение `Получение мастер аккаунта (v2)`