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

Как устроена интеграция

Учётная система — источник заказов и заданий. Selpo — цеховое табло: показывает задачи, фиксирует статусы и время.

Получить API-токен клиента.
Создать или сопоставить участки (цеха).
Отправлять задачи на табло.
Опрашивать журнал событий и статусы — переносить факты обратно в учёт.

Интеграция идёт только через REST /api/v1. WebSocket нужен браузерному табло, не учётной системе.

Базовые параметры

Параметр	Значение
Базовый URL (prod)	`https://selpotask.ru`
Префикс API	`/api/v1`
Полный URL метода	`{BASE_URL}/api/v1/{path}`
Формат	JSON, UTF-8
Заголовок тела	`Content-Type: application/json; charset=utf-8`
Аутентификация	`Authorization: Bearer <token>`

Токен и пароль в URL передавать нельзя — только в заголовке Bearer или в JSON-теле для /auth/token.

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

Получить токен

POST /api/v1/auth/token

{
  "login": "zavod_a",
  "password": "********"
}

Ответ 200: { "token": "…" } — строка 32 символа. Каждый успешный запрос выдаёт новый токен и инвалидирует предыдущий.

Обновить токен без логина/пароля

POST /api/v1/auth/token/refresh

Нужен текущий Bearer. В ответе — новый токен; старый перестаёт действовать. Удобно, если в учётной системе хранится только токен.

Использование

Authorization: Bearer a1b2c3d4e5f6789012345678abcdef01

Заголовок обязателен для всех методов, кроме POST /auth/token и GET /config/delay.

HTTP	Код	Смысл
401	`auth_required`	Нет или пустой Bearer
401	`auth_failed`	Неверный или устаревший токен / логин
403	`account_blocked`	Аккаунт заблокирован
403	`account_expired`	Истёк срок подписки

При 401 сначала вызовите /auth/token/refresh, затем один раз повторите исходный запрос. Не запрашивайте токен на каждый вызов.

Bootstrap — параметры клиента одним запросом

GET /api/v1/bootstrap

После указания адреса сервиса и токена один запрос отдаёт URL, тариф, лимиты опроса, список участков и табло диспетчера с PIN (bootstrapVersion ≥ 3).

Блок	Зачем
`urls`	base, api, adminPanel, health
`client`	Имя, логин, срок, флаги
`tariff` / `usage`	Лимиты и текущее использование (в т.ч. `usage.dispatcherBoards`)
`integration.pollMinIntervalSec`	Минимальный интервал опроса
`divisions[]`	Участки: `divId`, ссылка на табло, PIN в `password`
`dispatcherBoards[]`	Табло диспетчера: `boardId`, `link`, `divisionIds` (до 3), PIN в `password`

Пароль администратора и сам API-токен в ответе не возвращаются.

Формат ответов

Успех: JSON-объект или массив без обёртки { data: … }. Код 200 или 201 при создании.

Ошибка:

{
  "code": "validation_error",
  "error": "Краткий текст",
  "reason": "Что делать",
  "httpStatus": 400,
  "details": {}
}

HTTP	Когда
400	Невалидное тело или query
401 / 403	Авторизация и доступ
404	Нет участка или задачи
409	Дубликат или недопустимый статус
423	Лимит тарифа / пауза между запросами
429	Слишком много запросов

Статусы и важные поля

Статус задачи (`taskStatus`)

Значение	Имя	На табло	Смысл
`0`	PLANNED	Да	Поступила, не начата
`1`	RUN	Да	В работе
`2`	STOP	Да	Пауза
`5`	DONE	Нет	Выполнена
`6`	CANCEL	Нет	Отменена

Приоритет

0 — обычная, 1 — срочная (метка «СРОЧНО», выше в списке).

Идентификаторы

divId — алиас участка (генерирует сервер при создании; в задачах указывается этот id).
taskId — ваш внешний ключ задачи (1–100 символов, уникален на участке). В URL кодируйте спецсимволы.

Интервал опроса

GET /api/v1/config/delay

Ответ: { "delay": 10 } — рекомендуемый интервал в секундах. Не опрашивайте чаще.

Участки

POST /api/v1/divisions

{
  "name": "Упаковка",
  "password": "0000",
  "timezone": 3
}

Поле	Обяз.	Ограничения
`name`	да	1–200 символов
`password`	да	PIN табло, 1–50
`timezone`	нет	2–12, по умолчанию 3

Ответ 201 содержит divId, link (URL табло) и password (PIN). Сохраните их в учётной системе.

Метод	Путь	Назначение
GET	`/divisions`	Список участков
GET	`/divisions/{divId}`	Один участок
PATCH	`/divisions/{divId}`	Имя / PIN / часовой пояс
DELETE	`/divisions/{divId}`	Удалить участок, задачи и исполнителей

Задачи

POST /api/v1/tasks

{
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "taskNum": 101,
  "taskDate": "03.09.2026",
  "priority": 1,
  "qty": 50,
  "item": "Крышка",
  "itemPrt": "пластик",
  "description": "Технологическая инструкция для рабочего.",
  "orderNum": "З-4501",
  "orderDate": "01.09.2026 10:00:00",
  "orderType": "Производство",
  "divId": "e24be3b2848a"
}

Поле	Обяз.	Комментарий
`taskId`	да	Внешний id, уникален на участке
`taskNum`	да	Номер на карточке табло
`taskDate`	да	Рекомендуется `dd.mm.yyyy`
`divId`	да	Участок этого клиента
`priority`	нет	0 или 1
`description`	нет	До 2000 символов — текст для рабочего

Управление статусом из учёта

Все методы — POST, тело пустое.

Действие	Путь	Допустимый статус
Начать / продолжить	`/tasks/{taskId}/run`	0 или 2
Пауза	`/tasks/{taskId}/pause`	1
Завершить	`/tasks/{taskId}/done`	1 или 2
Отменить	`/tasks/{taskId}/cancel`	0, 1 или 2

Приоритет: POST …/priority/up и …/priority/down. Удаление: DELETE /tasks/{taskId}.

Статус и время для учёта

GET /api/v1/tasks/{taskId}/status

Поле	Смысл
`times.workMs`	Чистое рабочее время, мс
`times.pauseMs`	Время пауз, мс
`times.totalMs`	От первого «Начать», мс
`executorName`	Кто назначен на табло
`taskStatus`	Текущий статус

Список изменённых задач: GET /tasks?since={unix_ms} → { tasks, time }. Сохраняйте time для следующего опроса.

Журнал событий

Основной канал обратной связи с табло.

GET /api/v1/events?since={unix_ms}

{
  "events": [
    {
      "taskId": "550e8400-…",
      "divId": "e24be3b2848a",
      "action": "run",
      "timestamp": 1788446425000,
      "data": { "taskStatus": 1 }
    }
  ],
  "time": 1788446550000
}

action	Когда
`create` / `delete`	Создание / удаление задачи
`run` / `stop`	Старт или пауза (табло или API)
`done` / `cancel`	Завершение / отмена
`priority`	Смена срочности

Алгоритм: прочитать since → обработать события → при run/stop/done/cancel запросить /tasks/{id}/status для времени → сохранить новый since → ждать delay секунд.

Типовой сценарий

POST /auth/token или ввод готового токена → сохранить Bearer.
GET /bootstrap → URL, тариф, участки и PIN.
Сопоставить цеха учёта с divId (или POST /divisions).
При запуске заказа — POST /tasks.
Регламент: GET /events?since=…, обновлять статусы и время в учёте.
При необходимости управлять срочностью и отменой из учёта через /priority/* и /cancel.

Токен одного клиента не видит данные другого. Один экземпляр интеграции = один клиент Selpo.

Файлы расширений и дистрибутивы: раздел «Файлы».