UnloadZones — документация для интеграции

Модуль UnloadZones предоставляет REST API, через которое ваша информационная система обновляет данные по зонам.

1. Обзор

Централизованная передача на экран текстов для зон.
Простые HTTP-запросы к REST API с аутентификацией по API-ключу (X-API-Key).
Надёжность: ETag, условные запросы (If-None-Match, If-Match), ограничение частоты, аудит-логи обращений.

2. Модель данных зоны

Пример объекта зоны в ответе API:

{
  "zone_id": 1,
  "name": "Пост 1",
  "text": "ИВАНОВ В.Г.",
  "message_color": "#FF0000",
  "layout_w": 160,
  "layout_h": 20,
  "updated_at": "2025-09-20T12:30:00Z",
  "etag": "8792368e99e2742968bc935ccdbe85f6c7226611"
}

3. Аутентификация и лимиты

Каждый запрос должен содержать заголовок X-API-Key.
Базовый URL REST: /api/v1 (например: http://your_url/api/v1).
Лимит: 120 запросов/минуту на IP.
Используйте If-None-Match и If-Match с ETag для синхронизации изменений.

4. Эндпоинты API: Зоны

`GET /zones`

Возвращает список всех зон.

Пример ответа:

[
  { "id": 1, "name": "Зона 1", "text": "ОЖИДАНИЕ", "message_color": "#FF0000" },
  { "id": 2, "name": "Зона 2", "text": "ГОТОВО", "message_color": "#00FF00" }
]

`GET /zones/{zone_id}`

Возвращает данные конкретной зоны.
Поддерживает заголовок If-None-Match (ETag) для оптимизации кэширования.

Пример ответа:

{
  "id": 1,
  "name": "Зона 1",
  "text": "ОЖИДАНИЕ",
  "message_color": "#FF0000",
  "layout_w": 192,
  "layout_h": 64
}

`PUT /zones/{zone_id}`

Полная замена данных зоны (upsert).
Требует заголовок If-Match для контроля версий.

Пример запроса:

{
  "name": "Зона 1",
  "text": "ГОТОВО",
  "message_color": "#00FF00",
  "layout_w": 256,
  "layout_h": 64
}

`PATCH /zones/{zone_id}/text`

Изменяет только текст зоны.

Пример запроса:

{ "text": "ГОТОВО К ВЪЕЗДУ" }

`PATCH /zones/{zone_id}/color`

Изменяет только цвет сообщения.

Пример запроса:

{ "message_color": "#00FF00" }

`PATCH /zones/{zone_id}/size`

Изменяет только размеры зоны (layout_w, layout_h).

Пример запроса:

{ "layout_w": 256, "layout_h": 64 }

`PATCH /zones/{zone_id}/name`

Изменяет только название зоны.

Пример запроса:

{ "name": "Зона ожидания" }

5. Примеры запросов

curl

BASE="http://your_url"
KEY="ABCD-EFGH-1234-IJKL"

# список зон
curl -i -H "X-API-Key: $KEY" -H "Accept: application/json"       "$BASE/api/v1/zones"

# зона 1
curl -i -H "X-API-Key: $KEY" -H "Accept: application/json"       "$BASE/api/v1/zones/1"

# изменить только текст
curl -i -X PATCH -H "X-API-Key: $KEY" -H "Content-Type: application/json"       -d '{"text":"TEST"}'       "$BASE/api/v1/zones/1/text"

# полный PUT c If-Match
ETAG="8792368e99e2742968bc935ccdbe85f6c7226611"
curl -i -X PUT -H "X-API-Key: $KEY" -H "If-Match: $ETAG"       -H "Content-Type: application/json"       -d '{"name":"Пост 1","text":"ИВАНОВ В.Г.","message_color":"#FF0000","layout_w":160,"layout_h":20}'       "$BASE/api/v1/zones/1"

Node (fetch)

const BASE = 'http://your_url';
const KEY  = 'ABCD-EFGH-1234-IJKL';

const res = await fetch(`${BASE}/api/v1/zones/1/text`, {
  method: 'PATCH',
  headers: {
    'X-API-Key': KEY,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({ text: 'TEST' })
});
console.log(await res.json());

6. Использование ETag: `If-None-Match` и `If-Match`

ETag используется для обеспечения целостности данных и предотвращения конфликтов при одновременных изменениях ресурса.

If-None-Match применяется при GET, чтобы вернуть 304 Not Modified, если данные не изменились.
If-Match используется при PUT/PATCH, чтобы обновление прошло только если версия совпадает.

curl

BASE="http://your_url"
KEY="${UZ_API_KEY:?Set UZ_API_KEY first}"
ZONE_ID=1

# GET зоны
curl -sS -D headers.txt -H "X-API-Key: $KEY" -H "Accept: application/json"   "$BASE/api/v1/zones/$ZONE_ID" -o body.json

ETAG=$(awk -F': ' 'tolower($1)=="etag"{print $2}' headers.txt | tr -d '
"')
echo "ETag: $ETAG"

# Повторный GET c If-None-Match
curl -i -H "X-API-Key: $KEY" -H "If-None-Match: "$ETAG""   "$BASE/api/v1/zones/$ZONE_ID"

# PATCH с If-Match
curl -i -X PATCH -H "X-API-Key: $KEY" -H "If-Match: "$ETAG""   -H "Content-Type: application/json"   -d '{"text":"ГОТОВО К ВЪЕЗДУ"}' "$BASE/api/v1/zones/$ZONE_ID/text"

Node.js

let res = await fetch(`${BASE}/api/v1/zones/${zoneId}`, { headers:{ "X-API-Key": KEY } });
let etag = (res.headers.get("etag")||"").replaceAll('"','');

let pr = await fetch(`${BASE}/api/v1/zones/${zoneId}/text`, {
  method:"PATCH",
  headers:{
    "X-API-Key": KEY,
    "If-Match": `"${etag}"`,
    "Content-Type":"application/json"
  },
  body: JSON.stringify({ text: "ГОТОВО К ВЪЕЗДУ" })
});

Python

import requests, os

BASE="http://your_url"
KEY=os.environ["UZ_API_KEY"]
H={"X-API-Key":KEY}

r=requests.get(f"{BASE}/api/v1/zones/1",headers=H)
etag=r.headers.get("ETag","").strip('"')

resp=requests.patch(f"{BASE}/api/v1/zones/1/text",
  headers={**H,"If-Match":f'"{etag}"',"Content-Type":"application/json"},
  json={"text":"ГОТОВО К ВЪЕЗДУ"})
print(resp.status_code)

7. Коды ошибок

401 Unauthorized — неверный API-ключ.
404 Not Found — зона не найдена.
412 Precondition Failed — ETag устарел.
422 Unprocessable Content — ошибки валидации.
429 Too Many Requests — превышен лимит.
5xx — техническая ошибка.

8. Троблшутинг

Изменения не видны → убедитесь, что ответ 200 и text непустой.
412 Precondition Failed → получите новый ETag и повторите PUT.
401 Unauthorized → проверьте X-API-Key.
429 Too Many Requests → снизьте частоту запросов.

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

Храните API-ключ в секрете.
Ограничьте доступ к REST-узлу (VPN, доверенные IP).
Используйте If-Match для защиты от перезаписи данных.
Ведите аудит логов.

10. Поддержка

Личный кабинет → раздел ИнфоЛедСпектрум / Поддержка.
Приложите пример запроса/ответа (без ключа).
Укажите время, метод и путь.
В экстренных случаях — телефон из договора.

11. Визуальный интерфейс и тестирование API

В админ-панели доступен раздел API Test (Playground).
Здесь можно проверять работу всех эндпоинтов без кода.

API Playground

12. Управление API-ключами

API Keys

Создайте ключ, скопируйте его и используйте в заголовке X-API-Key.
Можно временно отключить или удалить ключ.

13. Логи API-запросов

API Logs

В логах фиксируются:

время запроса,
ключ,
метод и путь,
статус ответа,
ETag.

14. Управление зонами

Зоны

Через интерфейс можно создавать зоны, изменять текст и цвет, видеть дату последнего обновления.

15. Документация внутри панели

API Docs

Содержит описание методов, лимитов и примеров — быстрый справочник для разработчиков.

16. Валидация параметров

Поле	Тип / Ограничения	Обязательность
name	строка, максимум 64 символа	необязательно
text	строка, длина 1..255	обязательно для `PATCH /text` и при `PUT`
message_color	строка, формат HEX `^#[0-9A-Fa-f]{6}$`	обязательно для `PATCH /color` и при `PUT`
layout_w	целое число ≥ 1	обязательно для `PATCH /size` и при `PUT`
layout_h	целое число ≥ 1	обязательно для `PATCH /size` и при `PUT`
zone_id	целое число ≥ 1 (передаётся в пути URL)	всегда
If-Match	строка (валидный ETag)	рекомендуется для `PUT` и `PATCH`

Заметки

API стабильно возвращает JSON; указывайте Accept: application/json.
В системе используется UTC+3

UnloadZones — документация для интеграции

1. Обзор

2. Модель данных зоны

3. Аутентификация и лимиты

4. Эндпоинты API: Зоны

GET /zones

GET /zones/{zone_id}

PUT /zones/{zone_id}

PATCH /zones/{zone_id}/text

PATCH /zones/{zone_id}/color

PATCH /zones/{zone_id}/size

PATCH /zones/{zone_id}/name

5. Примеры запросов

curl

Node (fetch)

6. Использование ETag: If-None-Match и If-Match

curl

Node.js

Python

7. Коды ошибок

8. Троблшутинг

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

10. Поддержка

11. Визуальный интерфейс и тестирование API

12. Управление API-ключами

13. Логи API-запросов

14. Управление зонами

15. Документация внутри панели

16. Валидация параметров

Заметки

`GET /zones`

`GET /zones/{zone_id}`

`PUT /zones/{zone_id}`

`PATCH /zones/{zone_id}/text`

`PATCH /zones/{zone_id}/color`

`PATCH /zones/{zone_id}/size`

`PATCH /zones/{zone_id}/name`

6. Использование ETag: `If-None-Match` и `If-Match`