Документация › Для разработчиков › Публичный API
Публичный API и ключи dos_sk_live_…
[для разработчиков]Дёргай платформу из своего кода: API-ключdos_sk_live_…авторизует запросы как тебя самого — с теми же правами на проекты, что и в браузере.
⏱ 8 мин · 👤 для разработчика · 🟢 live
За 30 секунд:
- Ключ формата `dos_sk_live_…`, передаётся в заголовке `Authorization: Bearer …`.
- Ключ работает от имени твоего аккаунта — действуют те же роли/доступы, что и в кабинете.
- Ключи бывают read и read+write, на весь аккаунт или на один проект.
- Хранится только SHA-256-хеш — сырой ключ показывается один раз при создании. Потерял — выпусти новый.
Создание ключа
В кабинете → управление API-ключами → создать. При создании:
- задаёшь права: только чтение (
read) или чтение+запись (read+write); - задаёшь область: весь аккаунт (все твои проекты) или один проект;
- опционально — срок жизни (1–365 дней).
🔑 Сырой ключ виден ОДИН раз. Платформа хранит только его SHA-256-хеш и не может показать ключ повторно. Скопируй сразу в надёжное место. Потерял — просто отзови и выпусти новый.
Лимиты: до 50 ключей на аккаунт; запросы по ключу — до 120 в минуту (при превышении API вернёт 429 Too Many Requests — сделайте паузу и повторите). Управлять ключами можно только из браузера (залогиненная сессия) — сам ключ не может создавать другие ключи (защита от эскалации прав).
Использование
Передавай ключ в заголовке:
Authorization: Bearer dos_sk_live_xxxxxxxxxxxxxxxxxxxxxxxxПлатформа резолвит ключ в твоего пользователя — дальше работают те же правила доступа, что и в кабинете: ключ видит ровно те проекты и может ровно то, что роль твоего аккаунта на этих проектах. Никаких отдельных «прав ключа» сверх твоих собственных нет.
| Свойство | Поведение |
|---|---|
| Права | read — только GET; write — позволяет POST/PUT/PATCH/DELETE. Ключ только для чтения на мутирующем запросе → отказ |
| Область | account-scoped (все проекты) или project-scoped (заблокирован на один) |
| RBAC | наследует роли твоего аккаунта на проектах — не выше |
| Отзыв | отозванный ключ перестаёт работать сразу |
Базовый адрес: `https://dosai.pro`. Пример запроса:
curl https://dosai.pro/api/projects \
-H "Authorization: Bearer dos_sk_live_…"Каталог эндпоинтов
Все пути — относительно https://dosai.pro, авторизация — Authorization: Bearer dos_sk_live_… (мутирующие запросы требуют ключ с правом write).
Проекты
| Метод | Путь | Что делает |
|---|---|---|
| GET | /api/projects | Список всех проектов пользователя |
| POST | /api/projects | Создать новый проект — { name, company_name, industry, … } |
| GET | /api/projects/:id | Получить проект по ID |
| PATCH | /api/projects/:id | Обновить проект |
| DELETE | /api/projects/:id | Удалить проект |
Лиды
| Метод | Путь | Что делает |
|---|---|---|
| GET | /api/projects/:id/leads | Список лидов — query page, limit |
| GET | /api/projects/:id/leads/:leadId | Получить лид по ID |
| PATCH | /api/projects/:id/leads/:leadId | Обновить лид — { lead_status, client_name, phone, email } |
| DELETE | /api/projects/:id/leads | Массовое удаление — { ids: string[] } |
| GET | /api/projects/:id/leads/export | Экспорт лидов в CSV |
Диалоги
| Метод | Путь | Что делает |
|---|---|---|
| GET | /api/projects/:id/conversations | Список диалогов — query page, limit, status |
| GET | /api/projects/:id/conversations/:convId | Детали диалога |
| GET | /api/projects/:id/conversations/:convId/messages | Сообщения диалога |
| POST | /api/projects/:id/conversations/:convId/send | Отправить сообщение от оператора — { content: string } |
Интеграции
| Метод | Путь | Что делает |
|---|---|---|
| GET | /api/projects/:id/integrations | Список интеграций |
| POST | /api/projects/:id/integrations | Создать интеграцию (webhook) — { name, type, url, events[], headers? } |
| DELETE | /api/projects/:id/integrations/:intId | Удалить интеграцию |
Аналитика и отчёты
| Метод | Путь | Что делает |
|---|---|---|
| GET | /api/projects/:id/analytics | Статистика проекта — query from, to (YYYY-MM-DD) |
| GET | /api/projects/:id/reports | Скачать PDF-отчёт за месяц — query period=2026-03 |
Биллинг
| Метод | Путь | Что делает |
|---|---|---|
| GET | /api/projects/:id/tokens | Баланс токенов проекта |
| GET | /api/projects/:id/tokens/history | История транзакций |
Лимиты запросов
- API-ключ: до 120 запросов/мин на ключ; сверх —
429 Too Many Requests. - Ориентиры по типам: GET ≈ 30–60/мин, POST/PATCH ≈ 10–30/мин, PDF-отчёты ≈ 5/мин (точные значения у каждого роута свои).
- В каждом ответе — заголовки
X-RateLimit-Limit/X-RateLimit-Remaining/X-RateLimit-Reset; при 429 ещё иRetry-After(секунды до сброса).
Безопасность ключа
- Это пароль доступа к твоим проектам — храни как секрет, не коммить в репозиторий, не клади в открытый фронтенд.
- Светанул ключ — немедленно отзови и выпусти новый.
- Для интеграции, которой нужно только читать, — выдавай read-only ключ.
- Нужен доступ только к одному проекту — делай project-scoped ключ, не account-wide.
💬 Простыми словами
Если ты разработчик и хочешь дёргать платформу из своего кода — заводишь API-ключ. Это длинная строка вида dos_sk_live_…, которую ты прикладываешь к запросам в заголовке Authorization. Важная идея: ключ — это «ты в виде кода». Он видит ровно те проекты и умеет ровно то, что и ты сам в кабинете, не больше. Хочешь дать интеграции только читать — выпусти ключ «только чтение». Хочешь ограничить одним проектом — выпусти ключ на этот проект.
Главное правило безопасности: ключ показывается один-единственный раз при создании — мы храним только его «отпечаток» и заново показать не сможем. Скопировал, сохранил надёжно. Потерял или засветил — не страшно, заходишь и отзываешь, выпускаешь новый. И никогда не клади такой ключ в открытый код или фронтенд — это как пароль.
Дальше: → Кастомные вебхуки
Связано: Роли и права · Формат данных
Не получилось? → напиши в саппорт