ES — заметки практики

Что здесь: проверенные практикой правила и грабли сервиса ES (объекты/оборудование, компании, контакты). Сигнатуры ручек — endpoints/ES.md. Когда сюда идти: перед работой с объектами через API.

Грабли

⚠ GET /Assets принимает недокументированный query-параметр contactID — фильтрует объекты по привязанному контактному лицу (обратная сторона связки AssetContacts). Это единственный способ получить «объекты контакта» одним запросом: прямые ручки дают только объект → его контакты (GET /Assets/{assetID}/contacts), а фильтра contactID у списка объектов нет в swagger (его нет в авто-генерируемом endpoints/ES.md). Параметр рабочий — подтверждено мейнтейнером 2026-07-14. При следующем обновлении сверить, не появился ли он в swagger (тогда заметку убрать). Аналог у заявок — GET /Tasks ?contactID, у договоров — GET /ServiceContract ?contactID.

⚠ Недокументированный contactID у GET /Assets (см. выше) работает и на HEAD /Assets — тотал приходит уже отфильтрованным (проверено 2026-07-15: HEAD /ES/Assets?contactID=105 → Content-Range: items=0-0/1 против items=0-0/577953 без фильтра). Это удобный способ получить «сколько объектов у контакта» одним запросом без вычитки. В swagger у HEAD /Assets query-параметров не описано вообще — ни contactID, ни прочих.

⚠ GET /Assets не поддерживает isDeleted (в swagger параметра нет, проверено 2026-07-15) — в отличие от GET /Tasks и GET /Contacts. Отфильтровать мягко удалённые объекты на стороне сервера нечем; общее правило «всегда isDeleted=false» из overview.md к объектам неприменимо.

Наиболее используемые

GET /Assets, POST /Assets, GET /Assets/{assetID}, PUT /Assets/{assetID}, PUT /Assets/{assetID}/publish, GET /Companies — расшифровка в overview.md.