RKDash API

RKDash API

REST API с версией /api/v1 и дата-версией контракта 2026-09-15 (заголовок X-Api-Version, текущая версия — 1.3.0). Формат ответов — JSON, ошибок — application/problem+json по RFC 7807.

35
методов в справочнике
100/мин
лимит на ключ, всплеск до 20 в секунду
OpenAPI 3.1
спецификация из Zod-схем: /api/v1/openapi

Первый запрос за 5 минут

  1. Войдите в панель → Настройки → API → «Выпустить ключ». Выберите тестовый режим (rk_test_…) и области доступа, например read:dishes и read:checks.
  2. Скопируйте ключ: он показывается один раз.
  3. Сделайте запрос — сначала по меню, затем по чекам.
# список блюд с фудкостом выше 40% (себестоимость посчитана)
curl -s -H "Authorization: Bearer rk_test_ВАШ_КЛЮЧ" \
  "https://rkdash.com/api/v1/dishes?limit=3&filter[foodcost_gt]=40"

# чеки за период
curl -s -H "Authorization: Bearer rk_test_ВАШ_КЛЮЧ" \
  "https://rkdash.com/api/v1/checks?date_from=2026-09-01&date_to=2026-09-15&limit=5"

Ключ можно передавать и заголовком X-Api-Key. Ответ содержит X-Request-Id — по нему находится запись в журнале «Настройки → API».

Попробовать здесь

Вставьте тестовый ключ и отправьте запрос прямо со страницы — он уйдёт в живой API этого стенда. Ключ хранится в localStorage браузера и через сервер документации не идёт.

право: read:restaurants
GET /api/v1/restaurants?limit=3

Ключи и области доступа

Ключ живёт в одном рабочем пространстве и несёт набор областей. Проверка идёт на каждом вызове: ключ без области отвечает 403 insufficient_scope.

ОбластьЧто открываетРаздел
read:restaurantsЧтение списка заведенийЗаведения
write:restaurantsИзменение заведенийЗаведения
read:dishesЧтение меню и фудкостаМеню
write:pricesИзменение цен блюдМеню
read:checksЧтение чеков и продажПродажи
read:waitersЧтение официантов и их статистикиПерсонал
read:stockЧтение складаСклад
write:stockПриходы и списанияСклад
read:dashboardsЧтение дашбордов и их данныхДашборды
read:integrationsЧтение интеграцийИнтеграции
write:integrationsПодключение интеграцийИнтеграции
ai:askВопросы к AI-агенту по даннымAI
read:webhooksЧтение подписок на событияВебхуки
write:webhooksУправление вебхукамиВебхуки
read:kanbanЧтение доски задачАдаптер агента
write:kanbanСоздание и движение карточекАдаптер агента
write:dashboardsСоздание и правка дашбордовАдаптер агента
read:agentsСписок цифровых сотрудниковАдаптер агента
write:agentsУправление агентами и задачамиАдаптер агента
run:opsЗапуск обменов, сканов и рассылокАдаптер агента
read:auditЧтение журнала действийАдаптер агента
adapter:controlУправление самим адаптером (только владелец)Адаптер агента

Ротация: «Вращать» выпускает новый ключ, старый продолжает работать до отзыва — интегратор успевает разложить ключ, не ловя отказ. Отзыв действует сразу.

Общие правила: страницы, фильтры, сортировка, повторы

# пагинация курсором
GET /api/v1/checks?limit=50&cursor=c_eyJvIjo1MH0
→ { "data": [...], "meta": { "hasMore": true, "nextCursor": "c_...", "total": 10172 } }

# фильтры: filter[поле], операторы _gt/_gte/_lt/_lte/_ne/_contains/_in
GET /api/v1/dishes?filter[foodcost_gt]=40&filter[category]=Супы

# сортировка: минус — по убыванию
GET /api/v1/dishes?sort=-revenue

# повтор POST: тот же Idempotency-Key вернёт прежний ответ, другое тело — 409
curl -X PATCH -H "Idempotency-Key: 7f2c1a90" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"price": 520}' \
  https://rkdash.com/api/v1/dishes/dish_.../price

# смена версии контракта
curl -H "X-Api-Version: 2026-09-15" ...

Размер страницы — от 1 до 200, по умолчанию 50. Неизвестное поле фильтра или сортировки — ошибка 422 со списком допустимых, а не молча пустой результат.

Вебхуки

Подписчик получает POST с телом события. Подпись — X-Rkdash-Signature: t=<время>,v1=<HMAC-SHA256(secret, "время.тело")>. Не доставленные события повторяются трижды (сразу, через минуту и через пять), весь путь виден в журнале доставок.

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hook","events":["dish.updated","check.created","stock.low"]}' \
  https://rkdash.com/api/v1/webhooks

# журнал доставок
curl -H "Authorization: Bearer $KEY" https://rkdash.com/api/v1/webhooks/wh_.../deliveries

Событие check.created появляется после обмена с учётной системой (сканер сравнивает витрину с прошлым состоянием), stock.low — когда сальдо движений по позиции уходит ниже порога, заданного при внесении движения.

Справочник методов

Полная спецификация — /api/v1/openapi (OpenAPI 3.1). Файл openapi.yaml лежит в репозитории; из него собраны SDK @rkdash/api (TypeScript) и rkdash (Python).

Заведения

GET/api/v1/restaurantsСписок заведенийread:restaurants

Заведения из витрины: R-Keeper отдаёт рестораны, iiko — подразделения. Метрики считаются за указанный период.

curl -H "Authorization: Bearer $RKDASH_KEY" "https://rkdash.com/api/v1/restaurants?limit=3"
POST/api/v1/restaurantsДобавить заведение в реестрwrite:restaurants

Создаёт запись реестра: город, адрес, комментарий. Если заведение уже приходит из учётной системы, запись связывается с ним по `sourceKey`.

GET/api/v1/restaurants/{id}Заведение по идентификаторуread:restaurants
PATCH/api/v1/restaurants/{id}Изменить заведениеwrite:restaurants

Меняет поля реестра. Заведения из учётной системы правятся только здесь, не в источнике.

Меню

GET/api/v1/dishesСписок блюд с фудкостомread:dishes

Выручка и количество — из продаж, себестоимость порции — из расчёта StoreHouse. `foodcostPct = null` означает, что себестоимость по позиции не рассчитана: это не ноль.

curl -H "Authorization: Bearer $RKDASH_KEY" "https://rkdash.com/api/v1/dishes?filter[foodcost_gt]=40&limit=3"
GET/api/v1/dishes/{id}Блюдо: карточка, история цен, продажи по днямread:dishes
PATCH/api/v1/dishes/{id}/priceСогласовать новую цену блюдаwrite:prices

RKDash — аналитическая витрина, а не учётная система: изменение сохраняется в журнал согласованных изменений с причиной и автором, уходит в учётную систему ближайшим обменом и порождает событие `dish.updated`.

curl -X PATCH -H "Authorization: Bearer $RKDASH_KEY" -H "Idempotency-Key: 7f2c" -H "Content-Type: application/json" -d '{"price": 520, "reason": "рост закупки"}' https://rkdash.com/api/v1/dishes/dish_.../price

Продажи

GET/api/v1/checksЧеки за периодread:checks

Чек собирается из строк продаж: сумма чека всегда сходится с продажами.

curl -H "Authorization: Bearer $RKDASH_KEY" "https://rkdash.com/api/v1/checks?date_from=2026-09-01&date_to=2026-09-15&limit=5"
GET/api/v1/checks/{id}Чек с составомread:checks

Персонал

GET/api/v1/waitersОфицианты за периодread:waiters

Выручка, число чеков и средний чек по каждому сотруднику.

GET/api/v1/waiters/{id}/statsСтатистика официантаread:waiters

Сводка, выручка по дням, распределение по часам и топ блюд.

Склад

GET/api/v1/stockДвижения склада за периодread:stock

Расход по номенклатуре R-Keeper, расход продуктов iiko и движения, внесённые через API. Остатков StoreHouse в витрине нет — поле `balanceAvailable` всегда `false`, и это указано в `note`.

POST/api/v1/stock/movementsПриход или списаниеwrite:stock

Записывает движение в журнал склада. Если передать `lowThreshold`, позиция попадает под правило «низкий остаток»: при уходе сальдо ниже порога приходит событие `stock.low`.

Дашборды

GET/api/v1/dashboardsДашборды конструктораread:dashboards
GET/api/v1/dashboards/{id}/dataДанные виджетов дашбордаread:dashboards

Каждый виджет считается тем же кодом, что рисует панель, — цифры совпадают.

Интеграции

GET/api/v1/integrationsСервисы предприятияread:integrations

Список сервисов платформы MCP с признаком подключённого доступа.

POST/api/v1/integrations/{slug}/connectПодключить сервисwrite:integrations

Сохраняет доступы к учётной системе: платформа проверяет связь и возвращает результат проверки. Секреты обратно не отдаются.

Доска

GET/api/v1/cardsКарточки доски задачread:kanban

Доска одна на панель и агента: карточка, созданная через API, сразу видна в интерфейсе и доступна диспетчеру цифровых сотрудников. Показ `include` не поддерживается — состав плоский.

curl -H "Authorization: Bearer ***" "https://rkdash.com/api/v1/cards?filter[status]=new&limit=5"
GET/api/v1/agent-tasksЗадачи, которые ждут исполнителяread:kanban

То же, что видно на доске, но глазами агента: что назначено на него и ещё не начато. Нужен агенту на своём сервере — платформа не всегда может достучаться до него сама, а забрать задачу он может этим запросом.

curl -H "Authorization: Bearer ***" "https://rkdash.com/api/v1/agent-tasks?filter[assignee]=analyst&limit=5"
GET/api/v1/cards/{id}Карточка по идентификаторуread:kanban
POST/api/v1/cardsЗавести задачу на доскеwrite:kanban

Создаёт карточку в `kanban.db` — том же файле, из которого живёт канбан. Исполнитель берётся из /agents: неизвестный профиль отклоняется, чтобы задача не повисла без исполнителя.

curl -X POST -H "Authorization: Bearer ***" -H "Idempotency-Key: 4f1a" -H "Content-Type: application/json" -d '{"title": "Проверить фудкост за неделю", "assigneeId": "analyst"}' https://rkdash.com/api/v1/cards
PATCH/api/v1/cards/{id}Двинуть карточку: статус, приоритет, исполнительwrite:kanban

То же, что перетаскивание карточки в панели: `in_progress` — «взял в работу», `done` — задача закрыта.

GET/api/v1/cards/{id}/commentsЛента карточкиread:kanban

Комментарии людей и итоговые отчёты агентов в одном порядке — то, что видно в ленте карточки в панели.

POST/api/v1/cards/{id}/commentsКомментарий к карточкеwrite:kanban

Отчёт агента по задаче: автор по умолчанию — исполнитель карточки. Появление комментария порождает событие `card.commented`.

curl -X POST -H "Authorization: Bearer ***" -H "Idempotency-Key: 9c2" -H "Content-Type: application/json" -d '{"content": "Фудкост пересчитан, отчёт во вложении"}' https://rkdash.com/api/v1/cards/t_.../comments
DELETE/api/v1/cards/{id}Убрать карточку с доскиwrite:kanban

Архивация: карточка уходит с доски, история задачи сохраняется в базе.

Агенты

GET/api/v1/agentsИсполнители задачread:agents

Цифровые сотрудники выполняют работу по ресторану, профили разработки — доработку платформы. Значение `id` подставляется в `assigneeId` карточки.

AI

POST/api/v1/ai/askСпросить агента о данныхai:ask

Вопрос на русском уходит агенту `rkdash`: в ответе текст и готовая поверхность A2UI — блоки дашборда, которые можно отрисовать у себя.

curl -X POST -H "Authorization: Bearer $RKDASH_KEY" -H "Content-Type: application/json" -d '{"question":"Какая выручка за август?","threadId":"demo-1"}' https://rkdash.com/api/v1/ai/ask

Вебхуки

GET/api/v1/webhooksПодписки на событияread:webhooks
POST/api/v1/webhooksПодписаться на событияwrite:webhooks

Отдаёт секрет подписи — он показывается один раз при создании.

GET/api/v1/webhooks/{id}Подписка по идентификаторуread:webhooks
PATCH/api/v1/webhooks/{id}Изменить подпискуwrite:webhooks
DELETE/api/v1/webhooks/{id}Удалить подпискуwrite:webhooks
POST/api/v1/webhooks/{id}/deliveries/{deliveryId}/replayПовторить доставку событияwrite:webhooks

Возвращает запись журнала в очередь и выполняет попытку сразу. Новой записи не создаётся: в интерфейсе приёмника не появляется дубль.

GET/api/v1/events/streamЖивой поток событий (SSE)read:webhooks

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

GET/api/v1/webhooks/{id}/deliveriesЖурнал доставокread:webhooks

Видно, куда и с каким результатом ушло каждое событие, включая повторные попытки.