Ключи и доступ
Ключ выпускается в кабинете и показывается один раз — мы храним только его хэш и восстановить секрет не сможем. Потерялся — выпустите новый и отзовите старый.
# Все запросы — с ключом в заголовке curl https://api.insysit.com/api/public/v1/tickets?limit=50 \ -H "Authorization: Bearer sk_live_a1b2c3d4.секрет"
Ключ можно выпустить и отозвать — ротации по расписанию, срока жизни, ограничения по IP и персональных квот нет. Тестовых ключей и песочницы тоже нет: ключ один и сразу боевой. Ограничение частоты — около 5 запросов в секунду, всплеск до 40, и считается оно по IP-адресу, а не по ключу: несколько интеграций с одного сервера делят лимит.
Скоупы выбираются при выпуске ключа: интеграции на чтение незачем давать право менять заявки.
Чтение
Постраничный обход — курсором по идентификатору, до 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 — отдельный модуль: он включается по запросу и не входит в базовую поставку. Ключи и обработчики после подключения выпускаются в кабинете, в разделе «Интеграции».