# API

API позволяет работать с ботами Watbot из своего кода: находить и создавать контакты, отправлять им сообщения, менять переменные и теги, пополнять балансы, вести списки. Например, CRM на сайте может записать в бота заявку, а платёжная система — начислить бонусы после оплаты.

API доступно владельцу аккаунта с тарифом Pro. Запрос выполняется от имени владельца ключа и с его правами.

## Ключ API

Ключ выдаётся в профиле, на вкладке «API» — подробно в разделе [Ключ API](https://support.watbot.ru/account/profile#ключ-api). Ключ даёт полный доступ к аккаунту: храните его на сервере и не вставляйте в код страниц сайта или мобильного приложения.

Ключ передаётся в заголовке `Authorization`:

```
Authorization: Bearer ВАШ_КЛЮЧ
```

Если заголовок поставить нельзя, ключ можно передать параметром `api_token` — в адресе или в теле запроса. Заголовок надёжнее: адреса с параметрами попадают в журналы серверов.

Кнопка «Перевыпустить» в профиле заменяет ключ: прежний сразу перестаёт работать. Ключ сбрасывается и при смене или восстановлении пароля — после этого получите новый. Проверить ключ можно методом [getMe](https://support.watbot.ru/api/account#getme): он вернёт аккаунт, которому ключ принадлежит.

## Запросы

Все методы — по адресу:

```
https://watbot.ru/api/v1/имяМетода
```

- Большинство методов принимает и `GET`, и `POST`; какие именно — указано у метода. Методы, которые что-то меняют, лучше вызывать через `POST`.
- Параметры `POST` передаются в JSON (`Content-Type: application/json`) или как поля формы. У `GET` — в адресе.
- Ответы — в JSON, в кодировке UTF-8.

> [!IMPORTANT]
> Передавайте в каждом запросе заголовок `Accept: application/json`. Без него ошибки проверки параметров приходят не ответом `422` в JSON, а переадресацией — разобрать такую ошибку в коде не получится.

Пример: контакты бота.

```bash title="Запрос"
curl -X POST "https://watbot.ru/api/v1/getContacts" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 12345}'
```

Номер бота (`bot_id`) — число в адресе бота в кабинете: `/bots/12345/…`.

## Ограничения

- **Частота** — 120 запросов в минуту на аккаунт, все методы вместе.
- Сверх лимита API отвечает кодом `429`. Заголовок `Retry-After` говорит, через сколько секунд можно повторить; `X-RateLimit-Remaining` — сколько запросов осталось в текущей минуте.

## Ошибки

Успешный ответ — код `200` или `201`. Ошибки:

| Код | Когда | Ответ |
|---|---|---|
| `401` | Нет ключа, ключ неверный или перевыпущен | `{"error": "unauthorized"}` |
| `402` | У владельца ключа нет тарифа Pro | `{"error": "…", "code": "pro_required"}` |
| `403` | Нет доступа к боту или объекту; аккаунт заблокирован | `{"error": "…"}` |
| `404` | Бот, контакт или запись не найдены | `{"error": "…"}` или `{"message": "…"}` |
| `410` | Метод отключён (устаревший метод после даты отключения) | `{"error": "…", "code": "method_removed"}` |
| `422` | Параметры не прошли проверку | `{"message": "…", "errors": {"поле": ["…"]}}` |
| `429` | Превышена частота запросов | `{"message": "Too Many Attempts."}` |

Ошибка `422` перечисляет в `errors` каждое поле с причинами:

```json
{
  "message": "The contact id field is required.",
  "errors": {
    "contact_id": ["The contact id field is required."]
  }
}
```

Текст ошибок может меняться — в коде опирайтесь на код ответа и на поля `code` и `errors`.

Устаревший метод до отключения работает как прежде, но в каждом ответе присылает заголовки `Deprecation: true` и `Sunset` с датой отключения. Проверяйте их в своём коде, чтобы вовремя перейти на замену.