# Рахунки контакту

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

На кожну валюту в контакту свій рахунок. Операції через API потрапляють до журналу рахунку як «Поповнення через API» і «Списання через API».

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

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

## getContactAccounts

Повертає всі рахунки контакту.

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

| Параметр | Тип | Обов'язковий | Опис |
|---|---|---|---|
| `contact_id` | ціле число | так | Номер контакту |

```bash title="Запит"
curl -G "https://watbot.org/api/v1/getContactAccounts" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  --data-urlencode "contact_id=678"
```
```json title="Відповідь 200"
{
  "data": [
    {
      "id": 4521,
      "currency": "UAH",
      "amount": 15000,
      "amount_note": "150 UAH",
      "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.org/api/v1/addContactAccount
```

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

```bash title="Запит"
curl -X POST "https://watbot.org/api/v1/addContactAccount" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678, "currency": "UAH"}'
```
```json title="Відповідь 201"
{
  "data": {
    "id": 4521,
    "currency": "UAH",
    "amount": 0,
    "amount_note": "0 UAH",
    "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.org/api/v1/deleteContactAccount
```

| Параметр | Тип | Обов'язковий | Опис |
|---|---|---|---|
| `account_id` | ціле число | так | Номер рахунку |

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

Відповідь — код `204` без тіла.

Видалити можна лише порожній рахунок. Якщо на рахунку є гроші — `422` з помилкою в полі `account_id`; спершу спишіть залишок.

## addFundsToContactAccount

Поповнює рахунок.

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

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

```bash title="Запит"
curl -X POST "https://watbot.org/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": "UAH",
    "amount": 15000,
    "amount_note": "150 UAH",
    "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.org/api/v1/withdrawFundsFromContactAccount
```

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

```bash title="Запит"
curl -X POST "https://watbot.org/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": "UAH",
    "amount": 10000,
    "amount_note": "100 UAH",
    "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 UAH.",
  "code": "insufficient_funds",
  "errors": {
    "account_id": [
      "Недостатньо коштів. Поточний баланс 100 UAH."
    ]
  }
}
```

Списання не виводить рахунок у мінус, зокрема й за одночасних запитів. Якщо списати не можна, метод нічого не змінює й відповідає `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.org/uk/api#помилки).