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

Эти методы работают со счетами контакта — внутренним балансом в боте: бонусами, баллами, депозитом. Это те же счета, что пополняют и списывают блоки «Пополнить счет контакта» и «Списать со счета контакта» и что видны в карточке контакта на вкладке «Счета». Например, платёжная система после оплаты на сайте может начислить контакту бонусы, а бот — показать баланс функцией getBalance.

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

Внимание

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

Важно

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

getContactAccounts

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

GETPOSThttps://watbot.ru/api/v1/getContactAccounts

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

Запрос

curl -G "https://watbot.ru/api/v1/getContactAccounts" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  --data-urlencode "contact_id=678"

Ответ 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.

POSThttps://watbot.ru/api/v1/addContactAccount

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

Запрос

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"}'

Ответ 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
  }
}

Ответ 422

{
  "message": "У контакта уже есть счёт в этой валюте.",
  "code": "currency_exists",
  "errors": {
    "currency": [
      "У контакта уже есть счёт в этой валюте."
    ]
  }
}

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

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

deleteContactAccount

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

POSThttps://watbot.ru/api/v1/deleteContactAccount

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

Запрос

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}'

Ответ 422

{
  "message": "Нельзя удалить счёт с балансом 150 RUB.",
  "code": "account_not_empty",
  "errors": {
    "account_id": [
      "Нельзя удалить счёт с балансом 150 RUB."
    ]
  }
}

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

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

addFundsToContactAccount

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

POSThttps://watbot.ru/api/v1/addFundsToContactAccount

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

Запрос

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"}'

Ответ 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

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

POSThttps://watbot.ru/api/v1/withdrawFundsFromContactAccount

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

Запрос

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": "Оплата доставки"}'

Ответ 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
  }
}

Ответ 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 — в разделе Ошибки.

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

getContactAccounts#

addContactAccount#

deleteContactAccount#

addFundsToContactAccount#

withdrawFundsFromContactAccount#

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

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

getContactAccounts

addContactAccount

deleteContactAccount

addFundsToContactAccount

withdrawFundsFromContactAccount

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