Интеграция парковки со СКУД и АПС

Коротко

На объекте редко существует одна система. СКУД знает сотрудника и его права, АПС управляет стойкой и шлагбаумом, камеры видят места, 1С хранит договоры, а BI ждёт отчёты. Фраза «всё интегрируется по API» не решает главный вопрос: кто владеет каждым фактом и что произойдёт, когда сообщение придёт дважды или не придёт вовремя.

Сначала нарисуйте системы, а не endpoints

Типичный контур:

Система	Возможный источник истины
СКУД/IdP	человек, карта, роль доступа
CRM/1С/tenant portal	компания, договор, заявка гостя, лимит
АПС	физический проезд, билет, касса/платёж
CShark	топология, фактические места, доступность, карта, инциденты, устройства
BI	производные агрегаты, но не оперативное решение

Это пример, а не универсальное правило. Главное — у каждого поля должен быть один authoritative owner и понятные потребители.

Ownership matrix

До разработки заполните таблицу:

Сущность/поле	Владелец	Кто читает	Направление	SLA/freshness	Конфликт
employee status	`СКУД`	АПС	push/pull	`согласованный размер выборки`	владелец побеждает
vehicle plate	`владелец данных, определённый проектом`	CShark	API	`согласованный размер выборки`	normalisation + audit
spot status	CShark	АПС, табло	API/webhook	near-real-time	timestamp/order
physical passage	`АПС/controller`	CShark	event/API	`согласованный размер выборки`	idempotent passage_id
tariff/payment	`payment APS`	CShark/BI	API	`согласованный размер выборки`	ledger/reconciliation

Если поле «редактируется везде», интеграция уже спроектирована с конфликтом.

Три типа обмена

Pull: запрос текущего состояния

Подходит для справочника и восстановления:

доступность;
список мест;
состояние сессии;
конфигурация/версия.

Преимущество — потребитель сам выбирает момент. Недостаток — polling и задержка.

Push/webhook: уведомление об изменении

Подходит для оперативных событий. Webhook должен иметь:

event ID;
timestamp и version/schema;
подпись/секрет;
timeout и retry;
журнал попыток;
replay оператором;
идемпотентность у получателя.

Command: просьба выполнить действие

Команда отличается от события: она может быть принята, выполнена, отклонена или истечь. «HTTP 200» ещё не означает физическое открытие шлагбаума. Нужны command ID и подтверждение фактического результата.

CShark разделяет device.*, domain.*, command.* и integration.* контракты.

Идемпотентность: обязательный сценарий

Представим, что АПС запросила назначение места, но ответ потерялся. Она повторяет запрос.

Неправильное поведение: система создаёт второе назначение.

Правильное:

запрос имеет внешний стабильный reference/idempotency key;
тот же ключ и то же тело возвращают первоначальный результат;
тот же ключ с другим телом даёт конфликт;
retry после рестарта не меняет решение.

CShark allocation API использует external_ref и request signature; повтор возвращает существующий hold, конфликтующее тело отклоняется.

Семантика ошибок

Клиент должен отличать:

401 — ключ отсутствует/недействителен;
403 — не хватает scope или IP вне allowlist;
404 — объект/entry point неизвестен;
409 — конфликт состояния или идемпотентности;
422 — тело не прошло контракт;
5xx/timeout — результат неизвестен, безопасен только idempotent retry.

Ошибка «нет свободных мест» не равна «опечатка в entry point». В CShark неизвестная точка въезда возвращает 404, а не молчаливый ноль.

Пример интеграции: availability и allocation

АПС получает ключ spots:read и при необходимости allocations:write.
Запрашивает /integration/v1/availability?entry_point=....
Ответ разделяет total, available, free, зоны, типы, reachability и unknown gates.
Для подходящего автомобиля АПС отправляет allocation с типом доступа, entry point, типом места и внешним ref.
CShark выбирает место, резервирует и возвращает route/guidance.
External session связывает фактический визит; дальнейшие события обновляют состояние.
Webhook сообщает об изменениях.

Этот API реализован. Конкретная АПС должна пройти mapping и совместное тестирование.

Защита интеграции

Минимальные scopes

Ключ для чтения доступности не должен создавать сессии. Чувствительные ГРЗ/фото требуют отдельного права.

Хранение ключа

Показывать raw secret один раз, хранить hash на сервере, исключить из логов и argv, предусмотреть rotation/revoke.

IP allowlist и сеть

Allowlist дополняет, но не заменяет TLS, сегментацию и firewall. Внутренний HTTP допустим только в защищённой архитектуре с принятым риском.

Аудит чувствительных данных

При чтении ГРЗ/фото CShark пишет аудит без самих ГРЗ и URL.

Rate limit и backpressure

Webhook delivery lifecycle

Webhook может быть «создан», «отправлен», «доставлен», «ошибка», «ожидает повтора». Администратору нужен журнал и безопасный replay.

Проверка должна включать:

2xx;
timeout;
500;
недействительный TLS certificate если используется HTTPS;
повтор;
получатель offline и затем online;
replay после исправления;
дубликат у получателя.

PERCo, ABLOY и другие вендоры

Для PERCo и ABLOY подготовлены требования и vendor-neutral контракты доступа, но готовые промышленный коннекторы и сертификация не входят в текущую поставку.

Корректная формулировка: «CShark имеет integration API и требования/контракты для совместного проекта». Некорректная: «готово интегрируется с любой версией PERCo/ABLOY».

Матрица приёмки интеграции

Contract validation для каждого endpoint.
Положительный поток.
Неверный scope/key/IP.
Дубликат и out-of-order.
Timeout после commit и retry.
Concurrent allocation одного последнего места.
Закрытая зона и unknown gate.
Webhook retry/replay.
Rotation/revoke ключа.
Data minimization: без чувствительного scope нет ГРЗ/фото.
Backup/restart и восстановление курсоров.

FAQ

Кто должен быть источником истины по госномеру?

Зависит от процесса. Важно выбрать одного владельца записи и определить, где происходит нормализация и кто разрешает изменение.

REST или webhooks?

Обычно оба: webhook для оперативного изменения, REST для текущего состояния и восстановления после пропуска.

Что такое идемпотентность?

Повтор одного логического запроса не создаёт второе назначение, сессию или начисление. Для этого нужен стабильный ключ и серверная фиксация результата.

Есть ли готовая интеграция CShark с PERCo/ABLOY?

Требования и фундамент есть, готовые промышленные коннекторы и натурная сертификация не входят в текущую поставку.

Как защищать API key?

Минимальный scope, one-time display, hash at rest, TLS/сегментация, IP allowlist, rotation, revoke и исключение секрета из логов.

Граница применимости к CShark

Материал описывает проверяемый инженерный подход. Конкретный состав CShark зависит от версии, подключённых источников данных, прав, конфигурации и приёмки оборудования на объекте.

Посмотрите, какие возможности CShark доступны водителю и оператору и как они применяются на парковке, на странице возможностей системы.