Live-токены
Токен вида st_live_… работает в продакшене. По умолчанию живёт 90 дней и может читать/писать статусы. Создаётся в разделе «API-ключи».
Статусо · для разработчиков
Руководство по API
Всё, что нужно, чтобы подключить живые статусы к вашей CRM, SaaS или собственной системе: токены, методы, вебхуки, лимиты и обработка ошибок. Одна страница — и интеграция готова за вечер.
Bearer
/v2
1 сек
v2
api.statuso.ru
200 OK · 42 ms
PATCH /v2/statuses/br-4821
Authorization: Bearer st_live_9f2a…
Authorization: Bearer st_live_9f2a…
{ "text": "Открыто до 20:00", "open": true, "windows": ["18:30","19:10"] } → 200
Быстрый старт
Базовый URL и формат ответа
Все методы работают на https://api.statuso.ru/v2. Запросы и ответы — JSON в UTF-8. Заголовок Content-Type: application/json обязателен для тела. Все времена — в ISO 8601 с часовым поясом.
Базовый адрес. Простое окружение: https://api.statuso.ru/v2. Для партнёрских и корпоративных тарифов есть отдельный эндпоинт https://api.statuso.ru/v2/partner — тот же набор методов, но с расширенными лимитами.
Каждый ответ содержит поле request_id — его стоит логировать: при обращении в поддержку мы найдём запрос за секунды. В теле ответа нет лишних обёрток — только data и, при необходимости, meta.
Пример успешного ответа
{
"request_id": "req_8f3a1c",
"data": { "id": "st_4821", "open": true, "updated_at": "2025-02-14T18:05:00+03:00" },
"meta": { "version": "2.4" }
}
Аутентификация и токены
Безопасно и без лишней бюрократии
Статусо использует Bearer-токены. Токен создаётся в личном кабинете или через API, и у каждого есть своё время жизни и набор прав.
Test-токены
Токен st_test_… пишет только в песочнице — реальные каналы не трогаются. Не истекает, пока активен аккаунт. Идеален для CI и автотестов.
Права и ротация
Каждому токену можно выдать права read, write или admin. Ротация — в один клик: старый токен живёт ещё 24 ч для плавного перехода.
Как передать токен
Добавьте заголовок Authorization: Bearer st_live_9f2a1c… к каждому запросу. Не храните токен в клиентском коде и не отправляйте его в теле. Если токен просрочен или не найден — вернём 401 с понятным сообщением.
Методы API и примеры запросов
Короткий набор основных методов
Достаточно трёх-четырёх вызовов, чтобы управлять статусами полностью. Ниже — ключевые эндпоинты с примерами.
Обновить статус
PATCH https://api.statuso.ru/v2/statuses/br-4821
{
"text": "Открыто до 20:00 · запись онлайн",
"open": true,
"channels": ["whatsapp","telegram"],
"windows": ["18:30","19:10"]
}
Ответ 200: статус применён и рассинхронизирован на выбранные каналы в течение секунды. Можно передать только изменённые поля — остальное не затрётся.
GET /statuses
Список статусов аккаунта с пагинацией. Параметры limit (до 100) и cursor. Удобно для синхронизации кеша.
POST /statuses
Создать новый статус для канала или CRM-объекта. Вернёт 201 с идентификатором id и текущим updated_at.
DELETE /statuses/{id}
Удалить статус и снять его с всех каналов. Вернёт 204 без тела. Повторное удаление — 404.
Параметры запроса
Принятые форматы: text до 1024 символов, open — булево, channels — массив из whatsapp и telegram, windows — массив строк HH:MM. Неизвестные поля игнорируются, чтобы не ломать совместимость при добавлении новых параметров.
Вебхуки и события
Пусть ваш сервис сам узнаёт об изменениях
Вместо опроса API можно подписаться на события: Статусо пришлёт POST-запрос на ваш URL, когда статус изменён, канал отвалился или завершилась синхронизация.
status.updated
Срабатывает, когда текст, open или окна изменились. В теле — id, новое значение и updated_at. Приходит в течение 1 сек.
channel.failed
Если WhatsApp или Telegram не приняли обновление — пришлём событие с error_code и попыткой ретрая. Полезно для алертов в вашем мониторинге.
sync.completed
Финальное событие после того, как все выбранные каналы приняли изменение. Содержит итоговый state: ok или partial.
Подпись и безопасность
Каждый вебхук несёт заголовок X-Statuso-Signature — HMAC-SHA256 от тела с вашим секретом. Проверьте подпись перед обработкой. Ответьте 2xx в течение 5 сек; иначе мы повторим доставку по экспоненциальной ретраи до 24 часов. События доставляются в порядке очереди, без дублей.
Обработка ошибок и ретраи
Что делать, когда что-то пошло не так
Мы возвращаем понятные коды и всегда — поле request_id. Ниже — самые частые ситуации и как на них реагировать.
Коды ответов
400 — неверное тело или параметры; 401 — токен не найден или просрочен; 403 — токен не имеет нужного права; 404 — статус не существует; 409 — конфликт версий (данные уже изменились); 429 — превышены лимиты; 5xx — ошибка на нашей стороне.
Экспоненциальный ретрай
При 429 или 5xx ждите интервал из заголовка Retry-After (или 1, 2, 4, 8 сек) и повторяйте. Максимум — 5 попыток, дальше лучше показать пользователю «обновим позже».
Конфликт версий
409 значит, что статус уже изменился с момента вашего чтения. Перечитайте updated_at, примените изменение поверх актуального и отправьте снова — без потери данных.
Логируйте request_id
В каждом ответе есть request_id. Сохраняйте его рядом с вашим логируемым действием — поддержка найдёт полный след запроса и вебхуков за минуты.
Лимиты и квоты
Сколько можно делать и как
Лимиты зависят от тарифа. Указаны ориентиры, чтобы вы спроектировали интеграцию без сюрпризов. Текущие значения — в личном кабинете на странице «Квоты».
600
запросов в минуту (базовый)
100
объектов в одном GET
1 024
символа в поле text
24 ч
окно повторной доставки вебхука
Скорость запросов
Базовый тариф — до 600 запросов/мин, корпоративный — до 6 000. Превышение даёт 429 и заголовок Retry-After. Используйте батч-методы, чтобы снизить нагрузку.
Объём тела
Максимальный размер тела запроса — 32 КБ. Большие списки окон лучше отправлять частями через POST /statuses/{id}/windows с курсорами.
Приоритет и батчи
Батч-обновление до 50 статусов за один запрос считается одним вызовом для лимитов. Критичные события (закрытие) идут с приоритетом и обходят очереди.
Batch · priority
Готовы к интеграции?
Получите токен и попробуйте на песочнице
Тестовый токен и OpenAPI-спецификация — без карты и долгих анкет. Подключите один канал и проверьте все методы за вечер.
Частые вопросы разработчиков
Сразу по делу
Коротко о том, что спрашивают чаще всего при интеграции. Не нашли ответ — напишите в поддержку, отвечаем в течение дня.
?Есть ли OpenAPI-спецификация?
Да. Файл openapi.json доступен на странице руководства и по адресу /v2/openapi.json. Он описывает все методы, параметры и коды ошибок, его можно вставить в Swagger или Postman.
?Как отличить песочницу от продакшена?
Различают токены: st_test_… работает только в песочнице и не трогает реальные каналы, st_live_… — в продакшене. Базовый URL один, разница только в токенe.
?Что будет, если мой сервис отвалится?
Статус на каналах покажет последний известный актуальный вариант и плавно восстановится, когда данные вернутся. Клиенты не увидят «пусто», а вы получите событие channel.failed с деталями.
?Поддерживаете ли вы SDK?
Есть официальные примеры на Python и Node.js в репозитории. API — чистый REST, поэтому подойдут любые HTTP-клиенты. Вебхуки подписываются HMAC-SHA256, примеры проверки — в документации.
?Как часто обновляется статус на каналах?
После успешного запроса синхронизация идёт в течение секунды. Если канал временно недоступен, обновление ставится в очередь и применяется автоматически при восстановлении — данные не теряются.