API

API#

Документ фиксирует baseline API для беспилотного весового контура.

1. Общие правила#

  • Статус: design baseline

  • Префикс: /api/v1

  • Envelope: item/list + meta.request_id/meta.timestamp

  • Изоляция: tenant_id, industry_code=weighbridge, site_id, lane_id

  • ANPR policy:

    • prototype: primary ANPR в iT-2110-015700;

    • production: primary ANPR в iT-2210, панель получает готовый результат.

  • Identity policy:

    • QR/RFID enrich карточку, но не блокируют автоматический цикл взвешивания.

2. Группы endpoint-ов#

2.1. Weigh Session#

  • GET /api/v1/weighbridge-session/scheme

  • GET /api/v1/weighbridge-session/list

  • GET /api/v1/weighbridge-session/offline-queue

  • POST /api/v1/weighbridge-session/commands/detect

  • POST /api/v1/weighbridge-session/commands/complete-phase

  • POST /api/v1/weighbridge-session/commands/interlock

  • POST /api/v1/weighbridge-session/commands/erp-sync

List-фильтры phase-1:

  • q, vehicle_plate, trip_token, status, lane_id, direction, operation_mode, limit, offset

Ключевые команды:

  • detect:

    • создает или продолжает weigh_session по въезду или ANPR;

  • complete-phase:

    • записывает tare или gross, сохраняет evidence refs и пересчитывает состояние;

  • interlock:

    • фиксирует состояние шлагбаума, светофора и связанных gate-контуров;

  • erp-sync:

    • публикует очередь синхронизации карточек во внешнюю систему.

2.2. Driver Identity#

  • GET /api/v1/weighbridge-identity/scheme

  • GET /api/v1/weighbridge-identity/list

  • POST /api/v1/weighbridge-identity/commands/resolve

  • POST /api/v1/weighbridge-identity/commands/attach

Правило:

  • resolve допускается вызывать как до первой фазы, так и после нее;

  • отсутствие resolve не блокирует automatic close.

2.3. Media Evidence#

  • GET /api/v1/weighbridge-media/scheme

  • GET /api/v1/weighbridge-media/list

  • POST /api/v1/weighbridge-media/commands/ingest

Правило media policy:

  • gross: верхняя камера обязательна;

  • tare: верхняя камера обязательна только если кузов не пустой или сессия помечена как спорная/manual review.

  • ingest обязан возвращать storage_ref исходного evidence и при наличии preview_ref для UI/handover.

2.4. Weigh Alarms#

  • GET /api/v1/weighbridge-alarms/scheme

  • GET /api/v1/weighbridge-alarms/list

  • POST /api/v1/weighbridge-alarms/commands/publish

  • POST /api/v1/weighbridge-alarms/commands/ack

Базовые alarm codes phase-1:

  • weighbridge_weight_unstable

  • weighbridge_duplicate_entry

  • weighbridge_partial_exit

  • weighbridge_anpr_mismatch

  • weighbridge_camera_unavailable

  • weighbridge_scale_timeout

3. Пример payload#

3.1. POST /api/v1/weighbridge-session/commands/complete-phase#

{
  "item": {
    "session_id": "wbs-2026-03-10-0001",
    "phase": "gross",
    "weight_kg": 28420,
    "stability_state": "stable",
    "plate": "A123AA797",
    "camera_media_ids": ["med-plate-out-001", "med-cargo-top-001"],
    "captured_at": "2026-03-10T12:15:00Z"
  }
}

3.2. POST /api/v1/weighbridge-identity/commands/resolve#

{
  "item": {
    "session_id": "wbs-2026-03-10-0001",
    "rfid_uid": "04AABBCCDD",
    "qr_payload": "trip=TR-2026-00045;driver=DRV-1007",
    "vehicle_plate": "A123AA797"
  }
}

3.3. POST /api/v1/weighbridge-alarms/commands/publish#

{
  "item": {
    "session_id": "wbs-2026-03-10-0001",
    "alarm_code": "weighbridge_anpr_mismatch",
    "severity": "high",
    "message": "plate mismatch between entry and gross phase"
  }
}

4. Принятые правила цикла#

  • partial session допустима: карточка может быть сохранена после одной фазы и позже закрыта второй;

  • управление шлагбаумом и светофором входит в базовый автоматический контур через iU-6130 / iU-6135;

  • completed допустим только при наличии обязательного evidence и двух фаз;

  • manual_review используется как controlled fallback вместо silent reject;

  • rejected применяется только по явному review-решению и не должен выставляться автоматически при отсутствии evidence;

  • повторный detect в пределах активного lane/cycle context обязан вернуть существующий session_id и зафиксировать duplicate condition без создания второй карточки;

  • offline-queue хранит session/media/alarm entities до подтвержденного sync и не должен порождать duplicate session после recovery.

5. Первая реализационная очередь#

В phase-1 обязательны:

  1. weighbridge-session/scheme|list|offline-queue|detect|complete-phase|interlock|erp-sync

  2. weighbridge-identity/resolve|attach

  3. weighbridge-media/ingest

  4. weighbridge-alarms/publish|ack

Во phase-1 не требуется:

  • сложная ERP-оркестрация beyond queue/export;

  • авто-классификация груза beyond basic cargo_top;

  • сложная пропускная логика по расписаниям.

Содержание