Ключи и доступ
Ключ выпускается в кабинете и показывается один раз — мы храним только его хэш и восстановить секрет не сможем. Потерялся — выпустите новый и отзовите старый.
# Все запросы — с ключом в заголовке curl https://api.insysit.com/api/public/v1/tickets?limit=50 \ -H "Authorization: Bearer sk_live_a1b2c3d4.секрет"
Ключ можно выпустить и отозвать — ротации по расписанию, срока жизни, ограничения по IP и персональных квот нет. Ограничение частоты — около 5 запросов в секунду, всплеск до 40, и считается оно по IP-адресу, а не по ключу: несколько интеграций с одного сервера делят лимит.
Скоупы выбираются при выпуске ключа: интеграции на чтение незачем давать право менять заявки.
# Спецификация — без ключа, ее читают до покупки
curl https://api.insysit.com/api/public/v1/openapi.yaml
# Песочница: тот же запрос, ключ sk_test_ — данные не изменятся
curl -X POST https://api.insysit.com/api/public/v1/tickets \
-H "Authorization: Bearer sk_test_a1b2c3d4.секрет" \
-d '{"object_id":"…","object_name":"Дом 1","description":"Застряли","ticket_type":"stuck"}'OpenAPI 3.0.3 отдает сам API — открыто, без ключа: подрядчик читает контракт до того, как ключ у него появится. Спецификация лежит рядом с кодом и сверяется с настоящими маршрутами тестом, поэтому разойтись с ними не может.
Ключ песочницы (sk_test_) выпускается там же, в кабинете. Чтения по нему настоящие — справочники подрядчику все равно сопоставлять по реальным данным, — а записи выполняются вхолостую: заявка не создается, склад не двигается, вебхуки не уходят. В ответ вместо объекта приходит test_mode с пояснением — идентификатора нет, потому что ничего не создалось; тот же признак дублируется заголовком X-Insys-Test-Mode. Проверяются форма запроса, права ключа и вид неисправности (закрытый список: stuck, stopped, emergency, maintenance, intercom, dispatch_control), но не существование объектов по идентификаторам — это проверит уже сама запись.
Чтение
Постраничный обход — курсором по идентификатору, до 200 записей за запрос. Смещения нет: список не «съезжает», пока вы его листаете.
Запись
Заявку можно создать с ключом идемпотентности: повторный запрос с тем же ключом не создаст дубль — это безопасно при ретраях. Заявку из внешней системы можно завести как предложенную, чтобы диспетчер подтвердил ее перед работой.
Писать можно в заявки и склад. Оборудование, журнал ТО и акты 1С доступны только на чтение. Действия внешней системы записываются от системного пользователя — в журнале аудита видно, что заявку завел не человек.
События
Укажите адрес обработчика — и платформа сама постучится в него. Событий ровно шесть.
Подпись доставки
Каждая доставка подписана. Проверяйте подпись до того, как доверитесь телу запроса.
# Заголовки доставки
X-Insys-Signature: sha256=hex
X-Insys-Timestamp: 1763040000
# Тело
{ "event": "ticket.created",
"tenant": "acme",
"data": { … } }# Подписывается "<timestamp>.<тело>",
# а не тело само по себе.
signed = f"{ts}.{body}"
expected = hmac.new(
secret.encode(), # whsec_…
signed.encode(),
hashlib.sha256
).hexdigest()Секрет обработчика, как и ключ, показывается один раз. Если ваш сервер ответил ошибкой 5xx или попросил притормозить — доставка повторится автоматически; ответ 4xx считается окончательным отказом и повтора не будет. На ответ дается 10 секунд: отвечайте сразу, а тяжелую работу уводите в фон. Переотправить доставку вручную из кабинета нельзя.
Подключить
API — отдельный модуль: он включается по запросу и не входит в базовую поставку. Ключи и обработчики после подключения выпускаются в кабинете, в разделе «Интеграции».