API Toolkeeper

Программный доступ к данным вашей компании: выгрузить инвентаризации и передачи в свой дашборд, завести сотрудников из кадровой системы, построить отчёт так, как нужно именно вам.

Адрес API: https://toolkeeper.io/openapi/v1
Аутентификация: Authorization: Bearer <ваш ключ>
Интерактивный справочник: https://toolkeeper.io/openapi/v1/docs
Машиночитаемая спецификация: https://toolkeeper.io/openapi/v1/openapi.json

С чего начать

Получите ключ. Владелец компании создаёт его сам: «Мой профиль → Настройки аккаунта → API-ключи». Отметьте только те права, которые действительно нужны, и укажите срок действия.
Сохраните ключ сразу. Мы показываем его один раз. Дальше в интерфейсе останется только публичное начало вида tk_live_7Qm2XbR4 — по нему ключ можно узнать, но нельзя использовать.
Проверьте, что он работает. Одна команда — и вы увидите, что за ключ у вас в руках:

curl -s -H "Authorization: Bearer $TOOLKEEPER_API_KEY" \
  https://toolkeeper.io/openapi/v1/me

Ответ покажет название ключа, вашу компанию, к каким пространствам он допущен, полный список выданных прав и дату, после которой он перестанет работать. Если что-то идёт не так — начните отладку именно с /me: этот метод не требует ни одного права и отвечает всегда, когда ключ валиден.

Как устроен ключ

Ключ состоит из четырёх частей, и каждая нужна:

tk_live_7Qm2XbR4_9fKd2LmQ8vTnRs4WcXy7BpZ1aHj3Ue  a4Xb2Q
└──┬───┘└───┬──┘ └──────────────┬─────────────┘  └──┬─┘
   │        │                   │                   │
   │        │                   │                   └─ контрольная сумма
   │        │                   └─ секрет (~190 бит)
   │        └─ публичный идентификатор ключа
   └─ вендор и среда: live — боевые данные, test — тестовый контур

Идентификатор публичен. Его можно писать в логи, показывать в интерфейсе и называть в переписке с поддержкой: он говорит, какой ключ, но не даёт им воспользоваться.
Секрет у нас не хранится — только его криптографический отпечаток. Восстановить потерянный ключ невозможно, можно лишь выпустить новый.
Контрольная сумма позволяет отличить опечатку от неверного ключа: обрезанный при копировании ключ отбраковывается до обращения к базе.

Ключ всегда живёт ограниченное время. Бессрочных ключей нет намеренно: ключ, который никто не обновляет, переживает и интеграцию, и ноутбук, на котором он лежал. По умолчанию — 90 дней, максимум — год.

Что ключ может читать

Данные	Метод	Право	Что вернётся
Рабочие пространства	`GET /workspaces GET /workspaces/{id}`	workspaces:read	Список и карточка пространства: название, часовой пояс, кто владелец.
Сотрудники	`GET /employees GET /employees/{id}`	employees:read	ФИО, телефон, должность, пространства, роли. Пароли не отдаются никогда.
ТМЦ	`GET /items GET /items/{id}`	items:read	Карточки с названиями категории, бренда, статуса, склада, ответственного.
История карточки	`GET /items/{id}/history`	items:read	Полный аудит-трейл: изменения полей и все передачи в хронологии, с именами.
Инвентаризации	`GET /inventories GET /inventories/{id}`	inventories:read	Кампании: статус, даты, охват, участники, позиции.
Отчёт инвентаризации	`GET /inventories/{id}/report`	inventories:read	Найдено / не найдено / с замечаниями, стоимость недостачи, разбивка по людям.
Передачи	`GET /transfers GET /transfers/{id}`	transfers:read	Кто кому что передал. Фильтр `stuck=1` — зависшие, с временем ожидания.
Справочники	`GET /dictionaries/storages GET /dictionaries/building-sites GET /dictionaries/statuses`	dictionaries:read	Склады, объекты, категории/бренды/статусы/должности — для фильтров дашборда.
Сводная статистика	`GET /stats`	stats:read	Счётчики по компании: люди, ТМЦ, стоимость, активность.
Справочник ролей	`GET /roles`	roles:read	Роли, которые ключ имеет право назначать.
Про сам ключ	`GET /me`	— (нужен только валидный ключ)	Чей ключ, к какому пространству привязан, какие права, до какой даты.

Что ключ может изменять

Действие	Метод	Право	Ограничения
Создать сотрудника	`POST /employees`	employees:write	ФИО, телефон, должность, пространства, роли из белого списка.
Создать сотрудников пачкой	`POST /employees/bulk`	employees:write	До 100 за раз, лимит 5 запросов в минуту.
Изменить сотрудника	`PATCH /employees/{id}`	employees:write	Только свои поля. Пароль через API не меняется вообще.
Изменить права сотрудника	`POST /employees/{id}/roles`	employees:roles	Отдельное право. Административные роли снять нельзя.
Удалить сотрудника	`DELETE /employees/{id}`	employees:delete	Отдельное право. Владельца компании и админов удалить нельзя.
Создать ТМЦ	`POST /items`	items:write	Карточка с категорией, брендом, складом, ответственным.
Создать ТМЦ пачкой	`POST /items/bulk`	items:write	До 100 за раз, лимит 5 запросов в минуту.

Права выдаются по одному. Ключ для дашборда получает только *:read и физически не способен ничего изменить. Удаление сотрудников и переназначение прав — отдельные права, которые не входят в обычную запись: скрипт, заводящий людей, не должен уметь их убирать.

Что ключ не может — никогда

Это не настройка и не вопрос выданных прав. Таких методов в API просто нет:

Удалять или изменять ТМЦ, склады, объекты, справочники.
Создавать, изменять или отменять передачи — это делается в приложении, с фотофиксацией.
Создавать, изменять или удалять рабочие пространства.
Создавать, запускать или править инвентаризации и их результаты.
Менять пароли, входить под сотрудником, выпускать другие ключи.
Видеть данные любой другой компании — ключ жёстко привязан к вашей.
Трогать биллинг, тариф, счета и настройки аккаунта.

Передачи и инвентаризации читаются, но не создаются через API — сознательное решение. Эти операции завязаны на фотофиксацию, подтверждение обеими сторонами и мобильный сценарий; дублировать их программно значит открыть путь к «передачам», которых никто не видел.

Лимиты и повторы

60 запросов в минуту на ключ; для */bulk — 5 в минуту. Остаток — в заголовках X-Rate-Limit-*.
POST-запросы принимают заголовок Idempotency-Key. Повтор с тем же ключом и тем же телом вернёт сохранённый ответ (Idempotent-Replay: true) вместо второго сотрудника; повтор с другим телом — 409.
Списки отдаются постранично: ?page= и ?per_page= (максимум 200).

Ошибки

Все ошибки — RFC 9457 application/problem+json. В теле всегда есть type, title, status, detail, instance, а также ссылки docs и base_url — чтобы вызывающая сторона могла разобраться по одному ответу, ничего больше не открывая.

401 unauthorized — Ключ не передан, просрочен, отозван или неверен. В ответе есть заголовок WWW-Authenticate и подсказка, как аутентифицироваться.

403 forbidden — Ключ валиден, но у него нет нужного права. В detail написано, какого именно — выпустите новый ключ с этим правом.

404 not-found — Объекта нет либо он вне вашей компании. Мы намеренно не различаем эти случаи, чтобы по кодам ответа нельзя было нащупать чужие данные.

422 validation — Данные не прошли проверку. В errors[] — по одной записи на поле: field, code, message.

409 conflict — Повтор Idempotency-Key с другим телом запроса.

429 rate-limited — Превышен лимит запросов либо слишком много неудачных попыток аутентификации. Подождите и повторите.

400 bad-request — Запрос сформирован неверно — например, нечитаемый JSON или недопустимый параметр.

500 server-error — Ошибка на нашей стороне. Повторите позже; текст ошибки наружу не раскрывается.

Безопасность

Ключ видит только вашу компанию. Привязка к клиенту задаётся в момент выпуска и не читается из запроса — подменить её нельзя.
Ключ можно сузить до одного пространства. Тогда он не увидит и не тронет ничего за его пределами, даже если запросит явно.
Административные роли защищены. Владельца компании и администраторов через API нельзя ни удалить, ни разжаловать, ни изменить.
Пароли через API не устанавливаются и не меняются — ни свои, ни чужие.
Каждый вызов записывается — успешный и отклонённый. Мы можем показать, что именно делал конкретный ключ и когда.
Ключ отзывается мгновенно — кнопкой в кабинете, без обращения в поддержку.
Метод, которому забыли назначить право, закрыт, а не открыт: неописанный доступ считается ошибкой конфигурации и отклоняется.

Ключ — это пароль. Не кладите его в репозиторий, в мобильное приложение и во фронтенд: оттуда его заберёт любой, кто откроет исходники. Держите в переменных окружения или в менеджере секретов. Если ключ мог утечь — отзовите и выпустите новый, это занимает минуту.

Нужна помощь

Напишите на sales@toolkeeper.io и укажите публичный идентификатор ключа (например, tk_live_7Qm2XbR4) — по нему мы найдём ваши запросы в журнале. Сам ключ присылать не нужно и не надо.