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

Ці методи працюють із рахунками контакту — внутрішнім балансом у боті: бонусами, балами, депозитом. Це ті самі рахунки, які поповнюють і списують блоки «Поповнити рахунок контакту» та «Списати з рахунку контакту» і які видно в картці контакту на вкладці «Рахунки». Наприклад, платіжна система після оплати на сайті може нарахувати контакту бонуси, а бот — показати баланс функцією getBalance.

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

Увага

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

Важливо

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

getContactAccounts

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

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

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

Запит

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

Відповідь 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.

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

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

Запит

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

Відповідь 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
  }
}

Відповідь 422

{
  "message": "У контакту вже є рахунок у цій валюті.",
  "code": "currency_exists",
  "errors": {
    "currency": [
      "У контакту вже є рахунок у цій валюті."
    ]
  }
}

Особливості:

Якщо в контакту вже є рахунок у цій валюті — 422, помилка в полі currency.
Для блоків сценарію відкривати рахунок заздалегідь не обов'язково: блок «Поповнити рахунок контакту» відкриє його сам. Для поповнення через API рахунок потрібен — методи працюють за account_id.

deleteContactAccount

Видаляє рахунок контакту.

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

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

Запит

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

Відповідь 422

{
  "message": "Не можна видалити рахунок із балансом 150 UAH.",
  "code": "account_not_empty",
  "errors": {
    "account_id": [
      "Не можна видалити рахунок із балансом 150 UAH."
    ]
  }
}

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

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

addFundsToContactAccount

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

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

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

Запит

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

Відповідь 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

Списує з рахунку.

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

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

Запит

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

Відповідь 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
  }
}

Відповідь 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 — у розділі Помилки.

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

getContactAccounts#

addContactAccount#

deleteContactAccount#

addFundsToContactAccount#

withdrawFundsFromContactAccount#

Помилки рахунків#

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

getContactAccounts

addContactAccount

deleteContactAccount

addFundsToContactAccount

withdrawFundsFromContactAccount

Помилки рахунків