API конструктора

REST API в формате JSON: ваши боты, клиенты, баланс баллов, начисление и списание. Подходит, чтобы связать бота с кассой, сайтом или своей учётной системой.

1Как подключиться

В конструкторе откройте Настройки аккаунта → API для разработчиков и нажмите Создать ключ.
Скопируйте ключ сразу — он показывается один раз. Ключ начинается с ezc_.
Передавайте его в каждом запросе в заголовке Authorization: Bearer ezc_….

Базовый адрес:

https://ez-business.ru/constructer/api/v1

Ключ — как пароль от аккаунтаХраните его на сервере и не вставляйте в код сайта или мобильного приложения. Если ключ утёк, удалите его в настройках и создайте новый.

2Ошибки и лимиты

Ответ с ошибкой всегда содержит поле error с понятным текстом.

Код	Что значит
400	Неверные параметры запроса
401	Нет ключа, или ключ удалён
402	Доступ к аккаунту закончился — бот остановлен до продления
403	Аккаунт заблокирован
404	Бот, клиент или метод не найден
429	Больше 120 запросов в минуту на ключ. Подождите столько секунд, сколько указано в заголовке `Retry-After`
502	Не ответил бот или МойСклад — повторите запрос позже

3Аккаунт

GET /me — владелец ключа и состояние доступа.

{
  "id": "5b1c…",
  "login": "owner@example.com",
  "profile": { "name": "Анна", "email": "owner@example.com", "phone": "", "company": "Кофейня Зерно" },
  "access": { "active": true, "plan": "trial", "paidUntil": "2026-10-10T12:00:00.000Z", "maxBots": 1 }
}

4Боты

GET /bots — список ботов.
GET /bots/{botId} — один бот.

{
  "bots": [{
    "id": "209245bc-…",
    "name": "Кофейня Зерно",
    "username": "zerno_cards_bot",
    "platform": "telegram",
    "status": "running",
    "appUrl": "https://ez-business.ru/constructer/209245bc-…",
    "clients": "local",
    "createdAt": "2026-10-07T13:38:00.000Z",
    "startedAt": "2026-10-07T13:38:02.000Z"
  }]
}

status: running — работает, stopped — остановлен, suspended — остановлен до продления доступа. clients: local — клиенты хранятся в боте, moysklad — в МоёмСкладе.

POST /bots/{botId}/start, /stop, /restart — запустить, остановить, перезапустить.

5Клиенты

GET /bots/{botId}/clients?limit=50&offset=0&search= — клиенты, новые сверху. limit — до 100. search ищет по имени, телефону и номеру карты.

GET /bots/{botId}/clients/{clientId} — один клиент. Вместо clientId можно передать телефон.

{
  "clients": [{
    "id": "123456789",
    "name": "Анна Смирнова",
    "firstName": "Анна",
    "lastName": "Смирнова",
    "phone": "+79000000011",
    "cardNumber": "100231",
    "balance": 1240,
    "messengerUserId": "123456789",
    "registeredAt": "2026-10-07T10:00:00.000Z"
  }],
  "total": 1, "limit": 50, "offset": 0
}

Для ботов без МоегоСклада id — это ID клиента в мессенджере. Для ботов с МоимСкладом — ID контрагента.

6Начисление и списание баллов

POST /bots/{botId}/clients/{clientId}/bonus

Поле	Описание
`amount`	Целое число. Больше нуля — начислить, меньше — списать. До 1 000 000 по модулю
`comment`	Необязательно. Покажется клиенту в истории баллов, до 200 символов
`operationId`	Необязательно. Ваш номер операции, например номер чека: повторный запрос с тем же номером баллы второй раз не начислит

{ "ok": true, "balance": 1340, "applied": 100 }

Клиент получит сообщение о начислении в боте. Первая покупка приглашённого друга начисляет бонус пригласившему так же, как при ручном начислении. Если списать больше, чем на балансе, баланс станет нулевым — в applied будет фактическое изменение.

7Примеры

curl

curl https://ez-business.ru/constructer/api/v1/bots \
  -H "Authorization: Bearer ezc_ваш_ключ"

curl -X POST https://ez-business.ru/constructer/api/v1/bots/BOT_ID/clients/79000000011/bonus \
  -H "Authorization: Bearer ezc_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "comment": "Покупка, чек 1532", "operationId": "check-1532"}'

Node.js

const API = 'https://ez-business.ru/constructer/api/v1'
const headers = { Authorization: `Bearer ${process.env.EZC_KEY}`, 'Content-Type': 'application/json' }

const { bots } = await (await fetch(`${API}/bots`, { headers })).json()
const res = await fetch(`${API}/bots/${bots[0].id}/clients/79000000011/bonus`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ amount: 100, comment: 'Покупка', operationId: 'check-1532' })
})
console.log(await res.json())