Документация API v1

Базовый адрес: https://bizgateway.pro/api/v1. Ключ — в кабинете, раздел «API и вебхуки». Все запросы и ответы в JSON.

Аутентификация

Заголовок X-Api-Key: <ключ> или Authorization: Bearer <ключ>. Без ключа — 401 unauthorized. Лимит: 300 запросов в минуту на ключ (429 rate_limited).

Ошибки всегда одного вида: { "error": "<код>", "message": "...", ...детали } с соответствующим HTTP-статусом.

Каналы

МетодПутьОписание
GET/meАккаунт, баланс, число каналов
GET/channelsСписок каналов с состоянием (state: idle, connecting, qr, open, closed, logged_out) и статусом оплаты
GET/channels/:idСостояние одного канала, привязанный номер, лимиты и использование за месяц

Сообщения

МетодПутьТело / ответ
POST/channels/:id/messagesWhatsApp: { "phone": "+7 999 123-45-67", "text": "..." } → { id, phone, messageId, jid }
Telegram: { "to": "@username | +7… | tg:<id>", "text": "..." } → { id, to, name, messageId }
POST/channels/:id/messagesОтвет в известный чат (WhatsApp и Telegram): { "jid": "79991234567@s.whatsapp.net | tg:<id>", "text": "..." } → { id, messageId, jid, phone, name, kind, ts }
GET/channels/:id/messages?limit=50&direction=inЖурнал: входящие и исходящие
GET/channels/:id/chats?limit=50&groups=1Чаты из переписок (до 200, новые сверху; группы — только с groups=1): { chats: [{ jid, name, phone, username, isGroup, unread, lastMessageAt, lastText }] }
GET/channels/:id/chats/:jid/messages?limit=50&before=<ts>Сообщения чата по возрастанию времени: { jid, messages: [{ id, direction, text, type, ts, createdAt, status, senderName, deleted }] }; медиа без подписи — [фото], [голосовое], [файл: имя]
GET/channels/:id/numbers/check?phone=...{ phone, exists, jid } — есть ли номер в WhatsApp (только каналы WhatsApp)
curl -X POST https://bizgateway.pro/api/v1/channels/CHANNEL_ID/messages \
  -H "X-Api-Key: ВАШ_API_KEY" -H "Content-Type: application/json" \
  -d '{"phone":"+7 999 123-45-67","text":"Здравствуйте! Ваш заказ готов."}'

Коды ошибок: invalid_phone 400, phone_not_on_whatsapp 422, whatsapp_not_connected 503, channel_suspended 402, plan_limit_reached 402, daily_limit_reached 429, send_failed 502.

Коды входа (OTP)

МетодПутьТело / ответ
POST/channels/:id/otp/send{ "phone": "...", "purpose": "login", "clientIp": "1.2.3.4" } → { phone, purpose, expiresInSec, resendAfterSec, messageId }
POST/channels/:id/otp/verify{ "phone": "...", "code": "123456", "purpose": "login" } → { verified: true, phone, purpose }

Код действует 5 минут, 5 попыток, повтор не чаще раза в 60 секунд, не больше 5 кодов в час на номер и 30 на clientIp. Ошибки: invalid_code (с attemptsLeft), code_expired, code_not_found, too_many_attempts, resend_too_soon, too_many_requests.

Вебхуки

Укажите URL и получите секрет в кабинете. Мы отправляем POST с JSON { event, data, sentAt }, заголовками X-Event и X-Signature: sha256=<HMAC-SHA256(secret, тело)>. Три повтора с паузами 1, 3 и 9 секунд; отвечайте 2xx быстро.

Событиеdata
message.received{ channelId, channelKind, jid, phone, name, username, text, messageId, ts, fromMe: false, direction: "in", isGroup, id, from, pushName, timestamp }
message.sent{ channelId, channelKind, jid, phone, name, username, text, messageId, ts, fromMe: true, direction: "out", source }
channel.state{ channelId, state, connected, phone, lastDisconnect }
channel.suspended{ channelId, reason, plan, price }
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyWebhook(rawBody: string, signature: string | undefined, secret: string) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  return !!signature && signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Подключение приложений (OAuth)

Партнёрские сервисы подключаются кнопкой «Подключить BizGateWay»: пользователь входит и разрешает доступ, сервис получает токен.

ШагЗапрос
1GET /oauth/authorize?client_id=…&redirect_uri=…&state=… → после согласия редирект на redirect_uri?code=…&state=… (отказ — error=access_denied)
2POST /oauth/token { grant_type: "authorization_code", code, client_id, client_secret, redirect_uri } → { access_token, token_type: "Bearer", account }. Код одноразовый, живёт 5 минут
3Все запросы /api/v1 — с Authorization: Bearer <access_token>
PUT /api/v1/app/webhook { url } → { url, secret } — свой адрес и секрет вебхука у подключения; DELETE /api/v1/app/connection — отключиться

Правила безопасной работы

  • Пишите тем, кто дал согласие и ждёт сообщения; первым лучше писать после обращения клиента.
  • Не отправляйте одинаковые тексты подряд, добавляйте имя и детали; давайте способ отписаться.
  • Новый номер прогревайте с телефона несколько дней; телефон должен выходить в сеть хотя бы раз в две недели.
  • Лимиты тарифа и паузы между сообщениями встроены — они защищают номер, не обходите их.