> 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/balans/poluchenie-balansa.md).

# Получение баланса

### Описание

Endpoint позволяет получить текущий баланс мастер-аккаунта пользователя. Можно запросить основной баланс, бонусный баланс или оба одновременно.

***

### Endpoint

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

***

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

Все параметры передаются в query-строке запроса.

| Параметр       | Тип     | Обязателен | Описание                                                                  |
| -------------- | ------- | ---------- | ------------------------------------------------------------------------- |
| `server_id`    | integer | Да         | Идентификатор сервера или `0` для общего баланса мастер-аккаунта          |
| `user_id`      | integer | Да \*      | Идентификатор пользователя. Обязателен, если не указан `email`            |
| `email`        | string  | Да \*      | Email пользователя. Обязателен, если не указан `user_id`                  |
| `balance_type` | string  | Нет        | Тип баланса: `main` или `bonus`. Если не указан, возвращаются оба баланса |

{% hint style="warning" %}
Необходимо передать либо `user_id`, либо `email`
{% endhint %}

> **На что влияет server\_id:**
>
> * `server_id=0` — возвращается **общий баланс** мастер-аккаунта
> * `server_id > 0` — возвращается **баланс на конкретном сервере**

***

### Примеры

#### Получить оба баланса по user\_id

```bash
curl -G "https://api.mmoweb.biz/v2/master-account/balance" \
  -H "Authorization: Bearer APPLICATION_TOKEN_HERE" \
  --data-urlencode "user_id=123" \
  --data-urlencode "server_id=1"
```

#### Получить основной баланс по email

```bash
curl -G "https://api.mmoweb.biz/v2/master-account/balance" \
  -H "Authorization: Bearer APPLICATION_TOKEN_HERE" \
  --data-urlencode "email=user@example.com" \
  --data-urlencode "balance_type=main" \
  --data-urlencode "server_id=1"
```

#### JavaScript (fetch)

```javascript
const token = 'APPLICATION_TOKEN_HERE';
const params = new URLSearchParams({
  user_id: '123',
  balance_type: 'main',
  server_id: '1'
});

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

#### PHP

```php
<?php
$token = 'APPLICATION_TOKEN_HERE';
$params = [
  'user_id' => 123,
  'server_id' => 1
];

$url = 'https://api.mmoweb.biz/v2/master-account/balance?' . http_build_query($params);

$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);
?>
```

***

### Ответы

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

```json
{
  "success": true,
  "main_balance": "1500.50",
  "bonus_balance": "250.00"
}
```

Если указан `balance_type=main`:

```json
{
  "success": true,
  "main_balance": "1500.50"
}
```

Если указан `balance_type=bonus`:

```json
{
  "success": true,
  "bonus_balance": "250.00"
}
```

#### Ошибка валидации (400 Bad Request)

```json
{
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": {
    "email": "Email field must contain a valid email address.",
    "user_id": "User Id field is required when Email field is empty."
  }
}
```

#### Пользователь не найден (404 Not Found)

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

#### Сервер не найден (404 Not Found)

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

***

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

| Код                | HTTP Status | Описание                                    | Решение                                                                                      |
| ------------------ | ----------- | ------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `VALIDATION_ERROR` | 400         | Один или несколько параметров некорректны   | Проверьте параметры запроса, убедитесь что передан user\_id или email, и что server\_id >= 0 |
| `USER_NOT_FOUND`   | 404         | Пользователь не найден в системе            | Проверьте корректность user\_id или email                                                    |
| `SERVER_NOT_FOUND` | 404         | Сервер не найден или не принадлежит проекту | Проверьте корректность server\_id                                                            |

> Дополнительные коды ошибок, связанные с аутентификацией и авторизацией, описаны в разделе [Аутентификация](/rest-api/autentifikaciya.md).

***

### Примечания

* Балансы возвращаются в виде строк для избежания потери точности при работе с дробными числами
* Если `balance_type` не указан, возвращаются оба типа баланса
* Параметр `server_id` обязателен и должен быть целым числом >= 0