API на Edge

Уеб приложението на Edge е обикновен клиент на REST API под /api/v1. Всичко, което прави приложението, можете да направите и чрез API. Пълният справочник на крайните точки е справочникът на API на Edge, генериран от entrosity-edge.backend/api/openapi.yaml – спецификацията, от която се генерират маршрутизаторът и валидирането на заявките на сървъра (и TypeScript типовете на приложението).

Конвенции

• Базов URL: https://hub.entrosity.com/edge/api/v1 (проксито премахва /edge). API на конектора е под /edge/api/connector/v1 (Протокол на конектора на Edge).
• Удостоверяване: Authorization: Bearer <product token> – петминутен токен от Entrosity Hub за продукта edge (POST /api/platform/v1/auth/product-token {"product":"edge"} със сесията в Hub, API на Hub). Edge няма собствено влизане; потребителите, тенантите и ролите идват от Hub.
• Правила за достъп: всеки маршрут има правило в entrosity-edge.backend/internal/http/portal/access.go: публичен, влязъл потребител, глобален администратор или право в тенанта (Роли и права). Потребителите на тенант могат да извикват само /tenants/{id на техния тенант}/…; всеки друг тенант връща 404. Липсващо право връща 403.
• JSON тела с ключове в snake_case, най-много 1 MB. Схемите на заявките отказват непознати полета (422).
• Списъци: картодържателите, картите, одитните журнали и администраторският списък с тенанти приемат ?page=&page_size= (по подразбиране 50, най-много 200) и връщат items, page, page_size и total. Другите списъци връщат всички елементи.
• Журнал на достъпа: GET /tenants/{tenantID}/events е подреден от най-новите с keyset страниране: limit (1–500, по подразбиране 100), филтри from, to, door_id, controller_id, cardholder_id и type (повторете за няколко). Отговорът има items, has_more и, когато има още, next_before_at и next_before_id, които се подават като before_at и before_id.
• Ограничение на заявките: 20 заявки в секунда за IP адрес на клиент, пик 60 (EDGE_API_RATE_PER_SECOND, EDGE_API_RATE_BURST); над това 429.
• Всеки отговор съдържа X-Request-ID.

Грешки

Грешките са RFC 7807 application/problem+json със стабилен code:

{
  "type": "/problems/card_already_registered",
  "title": "Conflict",
  "status": 409,
  "code": "card_already_registered",
  "detail": "a card with this number is already registered",
  "request_id": "…"
}

Грешките при валидиране имат code: "validation" и fields със съобщение за всяко поле. Всички кодове: Кодове на грешки.

Асинхронни операции

Някои извиквания стартират задача на конектора и връщат задачата веднага:

Извикване	Задача	Резултат
POST /tenants/{tenantID}/connectors/{connectorID}/discover {driver, transport?, addresses?}	edge.discover	{controllers: [{driver, target, model, serial, firmware, door_mode}]}
POST /tenants/{tenantID}/controllers/{controllerID}/test	edge.controller.test	{driver, target, model, serial, firmware}
POST /tenants/{tenantID}/doors/{doorID}/open	edge.door.open	няма; следва събитието door_opened_remote

Проверявайте GET /tenants/{tenantID}/jobs/{jobID}, докато status не стане succeeded, failed, timeout или cancelled; result, error_code и error носят резултата. Търсенето на контролери и отварянето на врати изискват конекторът да е онлайн (409 connector_offline).

Синхронизацията на конфигурацията не се стартира от API: всяка промяна, която засяга контролер, планира синхронизация (Синхронизация на конфигурацията). POST /tenants/{tenantID}/controllers/{controllerID}/sync налага пълно повторно изпращане.

ПИН кодове на контролерите

ПИН кодът на контролер TrackBase002 може само да се записва:

• POST /tenants/{tenantID}/controllers и PATCH /tenants/{tenantID}/controllers/{controllerID} приемат pin (цяло число, 1–4294967294). ПИН има само драйверът trackbase002: за всеки друг драйвер pin е грешка 422 validation на полето pin.
• Промяната приема и clear_pin: true, което премахва ПИН кода; pin и clear_pin заедно дават 422.
• Контролерите се връщат с pin_set (boolean); самият ПИН никога не се връща, а журналът на одита записва само дали има зададен.
• Edge пази ПИН кода шифрован с EDGE_MASTER_KEY. Без него задаването или изчистването на ПИН отговаря с 409 master_key_missing.
• Нов или изчистен ПИН, както и нов адрес, транспорт или адрес по шината, изпраща конфигурацията на контролера отново (Протокол на конектора на Edge).

Обновления на конекторите

• Конекторите имат update_channel (stable или beta), capabilities от последното им hello (edge_update: конекторът се обновява сам) и update_version и update_offered_at: последното предложено им издание. Администраторите на тенанта сменят канала с PATCH /tenants/{tenantID}/connectors/{connectorID} {"update_channel": "beta"}.
• GET /admin/connector-releases (глобални администратори) показва запазените издания, от най-новата версия, с signing_enabled и public_key, който компилациите на конектора трябва да вграждат.
• CI публикува издания с POST /admin/connector-releases?version=&channel=stable|beta&notes=, Authorization: Bearer <EDGE_RELEASE_TOKEN> (не токен от Hub) и суровия MSI като тяло (application/octet-stream, до 64 MiB). Това извикване го няма в справочника на API; вижте Работа с Entrosity Edge.

Обновления на живо

Приложението получава обновленията на живо като server-sent events:

1. POST /auth/sse-token {"tenant_id": …} връща токен, валиден 60 секунди, обвързан с тенанта и сесията.
2. GET /tenants/{tenantID}/stream?sse_token=<token> (или с bearer токена) предава text/event-stream с коментар за поддържане на връзката на всеки 25 секунди.

Събитие	Данни
access.events	Масив с новите записи в журнала на достъпа (както в API за списъка).
controller.status	{controller_id, status, error?}
controller.sync	{controller_id, sync_status, error?}
door.state	{door_id, controller_id, open, locked}
connector.status	{connector_id, status} (online, offline, deleted)
job.update	Задача на конектор е сменила състоянието си.

Чувствителни действия

Окончателното изтриване на токен за регистриране (POST /tenants/{tenantID}/enrollment-tokens/{tokenID}/delete) е за глобални администратори и изисква step_up_token: Hub го издава срещу паролата на администратора (POST /api/platform/v1/auth/step-up, продукт edge, API на Hub).