# Счета контакта

Эти методы работают со [счетами контакта](https://support.watbot.ru/chatbots/contacts/accounts-referrals#счета) — внутренним балансом в боте: бонусами, баллами, депозитом. Это те же счета, что пополняют и списывают блоки [«Пополнить счет контакта»](https://support.watbot.ru/chatbots/blocks/contact-data/top-up-balance) и [«Списать со счета контакта»](https://support.watbot.ru/chatbots/blocks/contact-data/debit-balance) и что видны в карточке контакта на вкладке «Счета». Например, платёжная система после оплаты на сайте может начислить контакту бонусы, а бот — показать баланс функцией `getBalance`.

У контакта на каждую валюту свой счёт. Операции через API попадают в журнал счёта как «Пополнение через API» и «Списание через API».

> [!WARNING]
> Счета контакта — внутренние балансы бота (бонусы, баллы, депозит), а не банковские счета: платформа не переводит по ним деньги и не является платёжным сервисом. Ведите в своей системе учёт операций, которые отправляете через API, — по нему можно сверить балансы.

> [!IMPORTANT]
> Суммы передаются и возвращаются **в минимальных единицах валюты** — копейках, центах — целым числом. `15000` на счёте в `RUB` — это 150 ₽. Для валют без дробной части, например `JPY`, единица одна. Одно пополнение или списание — не больше 10¹⁴ минимальных единиц (для рублей — триллион рублей); больше — ошибка `422`.

## getContactAccounts

Возвращает все счета контакта.

```endpoint
GET POST https://watbot.ru/api/v1/getContactAccounts
```

| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| `contact_id` | целое | да | Номер контакта |

```bash title="Запрос"
curl -G "https://watbot.ru/api/v1/getContactAccounts" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  --data-urlencode "contact_id=678"
```
```json title="Ответ 200"
{
  "data": [
    {
      "id": 4521,
      "currency": "RUB",
      "amount": 15000,
      "amount_note": "150 RUB",
      "created_at": "2026-09-14T10:22:05+03:00",
      "updated_at": "2026-10-01T18:40:12+03:00",
      "blocked_at": null
    }
  ]
}
```

| Поле | Описание |
|---|---|
| `id` | Номер счёта — его передают в остальные методы как `account_id` |
| `currency` | Код валюты по ISO 4217 |
| `amount` | Баланс в минимальных единицах валюты |
| `amount_note` | Баланс в обычных единицах с кодом валюты, для показа человеку |
| `created_at`, `updated_at` | Когда счёт открыт и когда менялся |
| `blocked_at` | Когда счёт заблокирован; `null` — не заблокирован. С заблокированного счёта нельзя списывать |

Счета идут в порядке открытия.

## addContactAccount

Открывает контакту счёт в валюте. Тот же метод доступен под именем `createContactAccount`.

```endpoint
POST https://watbot.ru/api/v1/addContactAccount
```

| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| `contact_id` | целое | да | Номер контакта |
| `currency` | строка | да | Код валюты по ISO 4217 заглавными буквами: `RUB`, `USD`, `EUR` |

```bash title="Запрос"
curl -X POST "https://watbot.ru/api/v1/addContactAccount" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678, "currency": "RUB"}'
```
```json title="Ответ 201"
{
  "data": {
    "id": 4521,
    "currency": "RUB",
    "amount": 0,
    "amount_note": "0 RUB",
    "created_at": "2026-10-03T12:00:00+03:00",
    "updated_at": "2026-10-03T12:00:00+03:00",
    "blocked_at": null
  }
}
```
```json title="Ответ 422"
{
  "message": "У контакта уже есть счёт в этой валюте.",
  "code": "currency_exists",
  "errors": {
    "currency": [
      "У контакта уже есть счёт в этой валюте."
    ]
  }
}
```

Особенности:

- Если у контакта уже есть счёт в этой валюте — `422`, ошибка в поле `currency`.
- Открывать счёт заранее не обязательно для блоков сценария: блок «Пополнить счет контакта» откроет его сам. Для методов пополнения через API счёт нужен — они работают по `account_id`.

## deleteContactAccount

Удаляет счёт контакта.

```endpoint
POST https://watbot.ru/api/v1/deleteContactAccount
```

| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| `account_id` | целое | да | Номер счёта |

```bash title="Запрос"
curl -X POST "https://watbot.ru/api/v1/deleteContactAccount" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"account_id": 4521}'
```
```json title="Ответ 422"
{
  "message": "Нельзя удалить счёт с балансом 150 RUB.",
  "code": "account_not_empty",
  "errors": {
    "account_id": [
      "Нельзя удалить счёт с балансом 150 RUB."
    ]
  }
}
```

Ответ — код `204` без тела.

Удалить можно только пустой счёт. Если на счёте есть деньги — `422` с ошибкой в поле `account_id`; сначала спишите остаток.

## addFundsToContactAccount

Пополняет счёт.

```endpoint
POST https://watbot.ru/api/v1/addFundsToContactAccount
```

| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| `account_id` | целое | да | Номер счёта |
| `amount` | целое | да | Сумма в минимальных единицах валюты, от 1 до 100 000 000 000 000 (10¹⁴) |
| `description` | строка | да | За что начисление, до 255 символов. Попадёт в журнал счёта |

```bash title="Запрос"
curl -X POST "https://watbot.ru/api/v1/addFundsToContactAccount" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"account_id": 4521, "amount": 15000, "description": "Бонус за заказ A-1024"}'
```
```json title="Ответ 200"
{
  "data": {
    "id": 4521,
    "currency": "RUB",
    "amount": 15000,
    "amount_note": "150 RUB",
    "created_at": "2026-10-03T12:00:00+03:00",
    "updated_at": "2026-10-03T12:05:41+03:00",
    "blocked_at": null
  }
}
```

Заблокированный счёт пополнять можно.

## withdrawFundsFromContactAccount

Списывает со счёта.

```endpoint
POST https://watbot.ru/api/v1/withdrawFundsFromContactAccount
```

| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| `account_id` | целое | да | Номер счёта |
| `amount` | целое | да | Сумма в минимальных единицах валюты, от 1 до 100 000 000 000 000 (10¹⁴) |
| `description` | строка | да | За что списание, до 255 символов. Попадёт в журнал счёта |

```bash title="Запрос"
curl -X POST "https://watbot.ru/api/v1/withdrawFundsFromContactAccount" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"account_id": 4521, "amount": 5000, "description": "Оплата доставки"}'
```
```json title="Ответ 200"
{
  "data": {
    "id": 4521,
    "currency": "RUB",
    "amount": 10000,
    "amount_note": "100 RUB",
    "created_at": "2026-10-03T12:00:00+03:00",
    "updated_at": "2026-10-03T12:07:15+03:00",
    "blocked_at": null
  }
}
```
```json title="Ответ 422"
{
  "message": "Недостаточно средств. Текущий баланс 100 RUB.",
  "code": "insufficient_funds",
  "errors": {
    "account_id": [
      "Недостаточно средств. Текущий баланс 100 RUB."
    ]
  }
}
```

Списание не уводит счёт в минус, в том числе при одновременных запросах. Если списать нельзя, метод ничего не меняет и отвечает `422` с ошибкой в поле `account_id`:

| `code` | Причина |
|---|---|
| `account_blocked` | Счёт заблокирован — разблокируйте его в карточке контакта |
| `insufficient_funds` | На счёте меньше, чем `amount`; в тексте — текущий баланс |

Сначала проверяется блокировка, потом остаток.

## Ошибки счетов

- Нет контакта или счёта с таким номером, контакт удалён или удалён его бот — `404`.
- Контакт или счёт из чужого бота — `403`.
- Ошибки самих методов — `422` с полями `message`, `code` и `errors`. Текст ошибки — на языке запроса (заголовок `Accept-Language`), поэтому в коде проверяйте `code`:

| `code` | Метод | Причина |
|---|---|---|
| `currency_exists` | `addContactAccount` | Счёт в этой валюте уже есть |
| `account_not_empty` | `deleteContactAccount` | На счёте остались деньги |
| `account_blocked` | `withdrawFundsFromContactAccount` | Счёт заблокирован |
| `insufficient_funds` | `withdrawFundsFromContactAccount` | Не хватает денег на счёте |

Общие ошибки API — в разделе [Ошибки](https://support.watbot.ru/api#ошибки).