{"openapi":"3.1.0","info":{"title":"InspectFlow REST API","version":"1.0.0","summary":"Bilingual (AR/EN) Multi-Entity Municipal Inspection, Enforcement & Integration Platform API","description":"Enterprise REST API for InspectFlow supporting strict multi-entity isolation (`X-Entity-Id`), Arabic/English bilingual localization (`Accept-Language`), RFC 9457 Problem Details errors, idempotent writes (`Idempotency-Key`), offline field synchronization, and HMAC-SHA256 signed webhooks.","contact":{"name":"Bridges for Digital Consultancy","url":"https://thebridges.io","email":"info@thebridges.io"}},"servers":[{"url":"https://inspectflaw.bridges.studio","description":"Active InspectFlow Deployment"}],"tags":[{"name":"System","description":"Health, OpenAPI specification, and runtime diagnostics"},{"name":"Auth & Organization","description":"Sessions, multi-entity isolation, org units, RBAC roles, and module entitlements"},{"name":"Subjects","description":"Establishments, vehicles, sites, individuals, licenses, and external registry sync"},{"name":"Requests","description":"Inspection & service requests, workflow transitions, and SLA queues"},{"name":"Inspections","description":"Inspection plans, dynamic form scoring, workflow reviews, lab samples, damage assessments, and official reports"},{"name":"Enforcement","description":"Warnings, fines, closures, repeat ladders, early-payment discounts, objections, and fine books"},{"name":"Holdings","description":"Vehicle impoundment, seized goods, daily storage fees, and release checklist gates"},{"name":"Configuration","description":"No-code form studio, workflow studio, violation catalog, lookup lists, and config pack export"},{"name":"Integrations","description":"External connections, live test console, auto-generated specs, dynamic inbound endpoints, webhooks, and API clients"},{"name":"Field Sync","description":"Offline-first field pull, idempotent outbox push, and serial/reference block reservations"},{"name":"Reports & Audit","description":"Executive KPI dashboards, UTF-8 BOM bilingual exports, and hash-chained Merkle audit logs"},{"name":"Public","description":"Zero-PII public request tracker and QR document authenticity verification"}],"paths":{"/api/v1/health":{"get":{"operationId":"getHealth","tags":["System"],"summary":"Health check & runtime mode","x-summary-ar":"فحص جاهزية النظام ووضع التشغيل","description":"Returns service health, PostgreSQL connectivity status, and active runtime mode.","parameters":[],"security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}}},"/api/v1/openapi":{"get":{"operationId":"getOpenApiSpec","tags":["System"],"summary":"OpenAPI 3.1.0 specification","x-summary-ar":"مواصفة OpenAPI 3.1.0 الكاملة","description":"Returns the machine-readable OpenAPI 3.1.0 JSON specification for all v1 endpoints and webhook envelopes.","parameters":[],"security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}}},"/api/v1/auth/session":{"get":{"operationId":"getSession","tags":["Auth & Organization"],"summary":"Get active session, entity, and available demo roles","x-summary-ar":"عرض الجلسة النشطة والجهة والأدوار المتاحة","description":"Returns current authenticated actor, active entity, available entities, and demo role switcher list.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"patch":{"operationId":"updateSession","tags":["Auth & Organization"],"summary":"Switch active entity or pilot evaluation role","x-summary-ar":"تبديل الجهة النشطة أو الدور التجريبي","description":"Updates BRIDGES_ENTITY_ID and/or BRIDGES_DEMO_USER cookies to evaluate multi-entity isolation and RBAC scopes.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"entityId":"KALBA-MUN","userEmail":"admin@kalba.gov.ae"}}}}}},"/api/v1/entities":{"get":{"operationId":"listEntities","tags":["Auth & Organization"],"summary":"List tenant entities","x-summary-ar":"عرض الجهات الحكومية المسجلة","description":"Lists entities accessible to the caller within the tenant.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createEntity","tags":["Auth & Organization"],"summary":"Create a new entity","x-summary-ar":"إنشاء جهة جديدة","description":"Creates a new isolated entity with bilingual names and letterhead configuration.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"code":"KHORFAKKAN-MUN","nameAr":"بلدية خورفكان","nameEn":"Khorfakkan Municipality"}}}}}},"/api/v1/org-units":{"get":{"operationId":"listOrgUnits","tags":["Auth & Organization"],"summary":"List organizational units for active entity","x-summary-ar":"عرض الهيكل التنظيمي للجهة النشطة","description":"Lists departments and sections scoped to the active entity.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createOrgUnit","tags":["Auth & Organization"],"summary":"Create an organizational unit","x-summary-ar":"إنشاء إدارة أو قسم تنظيمي","description":"Creates a department or section under the active entity hierarchy.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"code":"PH-LAB","nameAr":"قسم المختبرات","nameEn":"Laboratory Section","levelNameAr":"قسم","levelNameEn":"Section"}}}}}},"/api/v1/users":{"get":{"operationId":"listUsers","tags":["Auth & Organization"],"summary":"List users and inspector profiles","x-summary-ar":"عرض المستخدمين وملفات المفتشين","description":"Lists users with their role assignments and optional field inspector profile.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createUser","tags":["Auth & Organization"],"summary":"Create a user with role assignments","x-summary-ar":"إنشاء مستخدم وتعيين صلاحياته","description":"Creates a new user account with bilingual names and scoped role template assignments.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"new.inspector@kalba.gov.ae","nameAr":"خليفة الكندي","nameEn":"Khalifa Al Kindi","roleCode":"inspector"}}}}}},"/api/v1/roles":{"get":{"operationId":"listRoles","tags":["Auth & Organization"],"summary":"List RBAC role templates and permission matrix","x-summary-ar":"عرض قوالب الأدوار ومصفوفة الصلاحيات","description":"Returns the 12 shipped BRD Section 30 role templates and their data-scoped permissions.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}}},"/api/v1/entitlements":{"get":{"operationId":"listEntitlements","tags":["Auth & Organization"],"summary":"List module entitlements","x-summary-ar":"عرض صلاحيات وتفعيل الوحدات","description":"Returns enabled/disabled status for all 16 Bridges Inspect platform modules.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"patch":{"operationId":"updateEntitlement","tags":["Auth & Organization"],"summary":"Enable or disable a module entitlement","x-summary-ar":"تفعيل أو تعطيل وحدة في المنصة","description":"Toggles a module entitlement at tenant or active entity level.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"moduleKey":"enforcement.holdings","enabled":true}}}}}},"/api/v1/subjects":{"get":{"operationId":"listSubjects","tags":["Subjects"],"summary":"Search and list inspection subjects","x-summary-ar":"البحث في سجل المنشآت والمركبات والمواقع","description":"Supports bilingual Arabic-normalized search, category/risk/zone filtering, and cursor pagination.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":["subjects:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createSubject","tags":["Subjects"],"summary":"Register a new inspection subject","x-summary-ar":"تسجيل منشأة أو مركبة أو موقع جديد","description":"Registers an establishment, vehicle, site, or individual with UAE plate normalization and external key indexing.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/IdempotencyKey"}],"security":[{"BearerAuth":["subjects:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"subjectTypeCode":"ESTABLISHMENT","displayNameAr":"مقهى شاطئ كلباء","displayNameEn":"Kalba Beach Cafe","riskCategory":"low","address":"Corniche Promenade, Kalba","establishment":{"tradeLicenseNo":"SHJ-KM-55901","issuer":"SEDD Sharjah"}}}}}}},"/api/v1/subjects/{id}":{"get":{"operationId":"getSubject","tags":["Subjects"],"summary":"Get subject 360° profile","x-summary-ar":"عرض الملف الشامل للخاضع للتفتيش","description":"Returns subject details, licenses, inspections, enforcement actions, and holdings.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["subjects:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"patch":{"operationId":"updateSubject","tags":["Subjects"],"summary":"Update subject profile or risk rating","x-summary-ar":"تحديث بيانات أو تصنيف المخاطر","description":"Updates bilingual name, address, contact details, or risk category/score.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["subjects:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/subjects/{id}/licenses":{"get":{"operationId":"listSubjectLicenses","tags":["Subjects"],"summary":"List licenses for a subject","x-summary-ar":"عرض تراخيص وتصاريح المنشأة أو المركبة","description":"Lists trade licenses and municipal permits associated with a subject.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["subjects:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createSubjectLicense","tags":["Subjects"],"summary":"Attach a license or permit to a subject","x-summary-ar":"إضافة رخصة أو تصريح جديد","description":"Records a new trade license or municipal permit with expiry tracking.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["subjects:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/subjects/by-external/{system}/{externalId}":{"get":{"operationId":"getSubjectByExternalKey","tags":["Subjects"],"summary":"Lookup subject by external system identifier","x-summary-ar":"البحث عن خاضع للتفتيش برقم النظام الخارجي","description":"Resolves a subject by external system (e.g. SEDD, RTA) and external identifier.","parameters":[{"name":"system","in":"path","required":true,"schema":{"type":"string"}},{"name":"externalId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["subjects:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"put":{"operationId":"upsertSubjectByExternalKey","tags":["Subjects"],"summary":"Idempotently upsert a subject by external key","x-summary-ar":"مزامنة (إدراج/تحديث) خاضع للتفتيش برقم خارجي","description":"Upserts a subject mapped to an external registry key without creating duplicates.","parameters":[{"name":"system","in":"path","required":true,"schema":{"type":"string"}},{"name":"externalId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["subjects:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/requests":{"get":{"operationId":"listRequests","tags":["Requests"],"summary":"List inspection & service requests","x-summary-ar":"عرض قائمة طلبات التفتيش والبلاغات","description":"Filters by state, priority, requestTypeCode, assigneeId, or search text.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":["requests:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createRequest","tags":["Requests"],"summary":"Register an inspection request (supports Idempotency-Key)","x-summary-ar":"تسجيل طلب تفتيش جديد (يدعم Idempotency-Key)","description":"Registers a new request, allocates an atomic reference & public tracking code, and enforces Idempotency-Key replay safety (REQ-005).","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/IdempotencyKey"}],"security":[{"BearerAuth":["requests:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"requestTypeCode":"COMPLAINT","requesterName":"محمد الشامسي","requesterPhone":"+971501234567","priority":"high","description":"بلاغ حول نظافة منطقة تحضير الأغذية"}}}}}},"/api/v1/requests/{id}":{"get":{"operationId":"getRequest","tags":["Requests"],"summary":"Get request details & available workflow transitions","x-summary-ar":"عرض تفاصيل الطلب والانتقالات المتاحة","description":"Returns the request record, linked inspections, and currently permitted workflow transitions.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["requests:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"patch":{"operationId":"updateRequest","tags":["Requests"],"summary":"Update request assignment, priority, or notes","x-summary-ar":"تحديث تعيين الطلب أو الأولوية","description":"Updates mutable request attributes and records an audit event.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["requests:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/requests/{id}/transitions/{code}":{"post":{"operationId":"transitionRequest","tags":["Requests"],"summary":"Execute a request workflow transition","x-summary-ar":"تنفيذ انتقال حالة للطلب عبر محرك سير العمل","description":"Evaluates transition guards, roles, and separation of duties via @bridges/workflow.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"code","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["requests:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"reason":"Assigned to field inspector","fields":{"assigneeId":"01950000-0004-7000-8000-000000000004"}}}}}}},"/api/v1/plans":{"get":{"operationId":"listPlans","tags":["Inspections"],"summary":"List inspection plans & campaigns","x-summary-ar":"عرض خطط وحملات التفتيش","description":"Returns periodic inspection plans and progress counters for the active entity.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":["inspections:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createPlan","tags":["Inspections"],"summary":"Create an inspection plan","x-summary-ar":"إنشاء خطة تفتيش جديدة","description":"Creates a scheduled inspection campaign with target zones and inspectors.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["inspections:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"nameAr":"حملة تفتيش المقاهي الشتوية","nameEn":"Winter Cafe Inspection Campaign","periodStart":"2026-11-01","periodEnd":"2026-12-31","targetCount":25}}}}}},"/api/v1/inspections":{"get":{"operationId":"listInspections","tags":["Inspections"],"summary":"List inspections","x-summary-ar":"عرض سجل عمليات التفتيش","description":"Lists inspections scoped to the active entity with filtering by state, inspectorId, subjectId, and outcome.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":["inspections:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createInspection","tags":["Inspections"],"summary":"Schedule or start an unplanned inspection","x-summary-ar":"جدولة أو بدء تفتيش ميداني","description":"Creates an inspection pinned to the active published form template version and workflow.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/IdempotencyKey"}],"security":[{"BearerAuth":["inspections:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"inspectionTypeCode":"PH_ROUTINE","subjectId":"01950000-0016-7000-8000-000000000001","inspectorId":"01950000-0004-7000-8000-000000000004","state":"in_progress"}}}}}},"/api/v1/inspections/{id}":{"get":{"operationId":"getInspection","tags":["Inspections"],"summary":"Get inspection with pinned form schema, evaluation, samples & damage assessments","x-summary-ar":"عرض تفاصيل التفتيش والنموذج والتقييم والعينات والأضرار","description":"Returns complete inspection state, form definition, live scoring evaluation, lab samples, damage assessments, and available transitions.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["inspections:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"patch":{"operationId":"updateInspection","tags":["Inspections"],"summary":"Update inspection metadata, GPS check-in, or signatures","x-summary-ar":"تحديث بيانات التفتيش أو موقع GPS أو التوقيعات","description":"Updates schedule, GPS coordinates, signatures, or notes.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["inspections:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/inspections/{id}/answers":{"put":{"operationId":"saveInspectionAnswers","tags":["Inspections"],"summary":"Submit checklist answers and evaluate score via @bridges/forms","x-summary-ar":"حفظ إجابات قائمة التفتيش وحساب النتيجة والتقييم","description":"Evaluates conditional visibility, required photos/remarks, deduction/weighted scoring, critical failures, and proposed violations.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["inspections:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"answers":{"q_chiller_temp":4,"q_freezer_temp":-19,"q_expiry_check":"yes","q_pest_free":"yes","q_handler_cards":"yes","q_personal_hygiene":"yes"}}}}}}},"/api/v1/inspections/{id}/transitions/{code}":{"post":{"operationId":"transitionInspection","tags":["Inspections"],"summary":"Transition inspection state via @bridges/workflow","x-summary-ar":"تنفيذ انتقال حالة التفتيش","description":"Validates workflow rules, separation of duties (reviewer != inspector), and triggers follow-up or audit events.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"code","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["inspections:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"comment":"Verified field evidence and approved report"}}}}}},"/api/v1/inspections/{id}/report":{"get":{"operationId":"renderInspectionReport","tags":["Inspections"],"summary":"Render official bilingual HTML inspection report with QR code","x-summary-ar":"إصدار تقرير التفتيش الرسمي ثنائي اللغة مع رمز QR","description":"Renders a print-ready bilingual (AR RTL / EN LTR) inspection report with QR verification code via @bridges/documents.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["inspections:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}}},"/api/v1/inspections/{id}/samples":{"get":{"operationId":"listInspectionSamples","tags":["Inspections"],"summary":"List Public Health laboratory samples for an inspection","x-summary-ar":"عرض العينات المخبرية المرتبطة بالتفتيش","description":"Lists laboratory samples (food, water, air, soil, swab) collected during the inspection.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["inspections:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createInspectionSample","tags":["Inspections"],"summary":"Record a collected laboratory sample","x-summary-ar":"تسجيل عينة مخبرية جديدة","description":"Records sample seal number, type, destination laboratory, and chain-of-custody timestamp.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["inspections:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"sealNo":"SEAL-KM-2026-104","sampleType":"food","descriptionAr":"عينة دجاج مطبوخ من منطقة التحضير","descriptionEn":"Cooked poultry sample from prep line","labName":"Sharjah Central Food Lab"}}}}},"patch":{"operationId":"updateInspectionSample","tags":["Inspections"],"summary":"Update lab sample status and test result","x-summary-ar":"تحديث حالة ونتيجة الفحص المخبري للعينة","description":"Updates laboratory testing status (`sent_to_lab`, `in_testing`, `passed`, `failed`) and records summary.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["inspections:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/inspections/{id}/damage":{"get":{"operationId":"listDamageAssessments","tags":["Inspections"],"summary":"List accident asset damage assessments for an inspection","x-summary-ar":"عرض تقارير حصر أضرار الحوادث على الممتلكات","description":"Returns itemized municipal asset damage assessments and valuations.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["inspections:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createDamageAssessment","tags":["Inspections"],"summary":"Create an itemized accident damage assessment","x-summary-ar":"إنشاء محضر حصر وتقدير أضرار الحادث","description":"Calculates total municipal property damage compensation from the official damage asset catalog.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["inspections:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"policeReportNo":"SHJ-POL-2026-55012","responsiblePartyName":"سالم المنصوري","vehiclePlate":"SHJ-3-77410","items":[{"assetCode":"AST-POLE","quantity":1,"damageLevel":"total_loss"}]}}}}}},"/api/v1/enforcement-actions":{"get":{"operationId":"listEnforcementActions","tags":["Enforcement"],"summary":"List warnings, fines, and closure orders","x-summary-ar":"عرض الإنذارات والمخالفات المالية وأوامر الإغلاق","description":"Lists enforcement actions with live early-payment discount calculations and payment summaries.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":["enforcement:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createEnforcementAction","tags":["Enforcement"],"summary":"Issue a warning, fine, or closure order (repeat ladder & serial allocation)","x-summary-ar":"إصدار إنذار أو مخالفة مالية أو أمر إغلاق","description":"Computes repeat-offender escalation via `computeRepeatFineAmount`, allocates a fine book serial when applicable, and issues a verification code.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/IdempotencyKey"}],"security":[{"BearerAuth":["enforcement:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"kind":"fine","subjectId":"01950000-0016-7000-8000-000000000002","violationCode":"PH-V01","fineBookId":"01950000-0019-7000-8000-000000000001","notes":"Chiller temperature recorded at 9.5C"}}}}}},"/api/v1/enforcement-actions/{id}":{"get":{"operationId":"getEnforcementAction","tags":["Enforcement"],"summary":"Get enforcement action details with payments, objections, and early discount","x-summary-ar":"عرض تفاصيل المخالفة مع السداد والاعتراضات والخصم المبكر","description":"Returns complete enforcement action state, early-payment eligibility, payment history, objections, and allowed transitions.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["enforcement:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"patch":{"operationId":"updateEnforcementAction","tags":["Enforcement"],"summary":"Adjust fine amount or update enforcement notes","x-summary-ar":"تعديل قيمة المخالفة أو الملاحظات","description":"Allows authorized officers/supervisors to adjust fine amounts within range or extend deadlines.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["enforcement:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/enforcement-actions/{id}/transitions/{code}":{"post":{"operationId":"transitionEnforcementAction","tags":["Enforcement"],"summary":"Execute a warning/fine workflow transition","x-summary-ar":"تنفيذ انتقال حالة للإنذار أو المخالفة","description":"Enforces workflow guards and separation of duties (e.g. cancellation approval).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"code","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["enforcement:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/enforcement-actions/{id}/payments":{"post":{"operationId":"recordFinePayment","tags":["Enforcement"],"summary":"Record fine payment with automatic UAE early-payment discount","x-summary-ar":"تسجيل سداد مخالفة مع حساب خصم السداد المبكر تلقائياً","description":"Applies `computeEarlyPaymentDiscount`, updates paid balance, and transitions the fine to `paid` or `partly_paid`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/IdempotencyKey"}],"security":[{"BearerAuth":["payments:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"amount":1875,"method":"tahseel","receiptNo":"TAH-2026-881234"}}}}}},"/api/v1/enforcement-actions/{id}/objections":{"get":{"operationId":"listActionObjections","tags":["Enforcement"],"summary":"List objections for an enforcement action","x-summary-ar":"عرض الاعتراضات المقدمة على المخالفة","description":"Returns all objections filed against the enforcement action.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["enforcement:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createActionObjection","tags":["Enforcement"],"summary":"Submit or decide an objection","x-summary-ar":"تقديم اعتراض أو البت فيه","description":"Files a new objection (transitioning fine to `objected`) or records an objection decision.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["enforcement:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"submittedByName":"خلفان الزعابي","reason":"تم تصحيح الخلل وتقديم فواتير الصيانة"}}}}}},"/api/v1/enforcement-actions/{id}/notice":{"get":{"operationId":"renderEnforcementNotice","tags":["Enforcement"],"summary":"Render official bilingual Warning / Fine / Closure HTML notice with QR","x-summary-ar":"إصدار إشعار الإنذار / المخالفة / الإغلاق الرسمي ثنائي اللغة","description":"Renders official print-ready bilingual HTML notice with embedded verification QR SVG via @bridges/documents.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["enforcement:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}}},"/api/v1/fine-books":{"get":{"operationId":"listFineBooks","tags":["Enforcement"],"summary":"List electronic & paper fine books","x-summary-ar":"عرض دفاتر المخالفات الإلكترونية والورقية","description":"Lists fine books with remaining serial counts and active custodians.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":["enforcement:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createFineBook","tags":["Enforcement"],"summary":"Register a new fine book range","x-summary-ar":"إنشاء دفتر مخالفات جديد وتحديد النطاق التسلسلي","description":"Registers a new electronic or paper fine book with strict non-overlapping serial range.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["enforcement:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"code":"FB-KM-PH-2026-E02","kind":"electronic","prefix":"KM-PH-E","rangeStart":2001,"rangeEnd":2500}}}}}},"/api/v1/fine-books/{id}/custody":{"post":{"operationId":"recordFineBookCustody","tags":["Enforcement"],"summary":"Transfer or return fine book custody","x-summary-ar":"نقل أو استلام عهدة دفتر المخالفات","description":"Records an immutable custody transfer, issuance, audit, or return event for a fine book.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["enforcement:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/fine-books/{id}/serials":{"get":{"operationId":"listFineBookSerials","tags":["Enforcement"],"summary":"List serials in a fine book","x-summary-ar":"عرض الأرقام التسلسلية في دفتر المخالفات","description":"Lists allocated, reserved, used, and voided serials.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["enforcement:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"manageFineBookSerial","tags":["Enforcement"],"summary":"Allocate, reserve, or void a fine book serial","x-summary-ar":"حجز أو تخصيص أو إلغاء رقم تسلسلي في الدفتر","description":"Allocates the next serial or voids a leaf with a mandatory void reason code.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["enforcement:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/holdings":{"get":{"operationId":"listHoldings","tags":["Holdings"],"summary":"List impounded vehicles & held goods with accrued storage fees","x-summary-ar":"عرض المركبات والمضبوطات المحجوزة ورسوم الأرضية","description":"Lists active and released holdings with live `computeHoldingStorageFee` calculation.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":["enforcement:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createHolding","tags":["Holdings"],"summary":"Order a new vehicle impoundment or goods holding","x-summary-ar":"إصدار أمر حجز مركبة أو مضبوطات","description":"Creates a holding record in `hold_ordered` state with itemized inventory.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["enforcement:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"kind":"vehicle","subjectId":"01950000-0016-7000-8000-000000000006","plateNumber":"SHJ 3 / 54821","foundLocation":"Al Corniche Parking C","dailyFee":50}}}}}},"/api/v1/holdings/{id}":{"get":{"operationId":"getHolding","tags":["Holdings"],"summary":"Get holding details, storage fee calculation, and release checklist","x-summary-ar":"عرض تفاصيل الحجز ورسوم الأرضية وقائمة التحقق للإفراج","description":"Returns holding record, accrued storage fee, release checklist status, and allowed transitions.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["enforcement:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"patch":{"operationId":"updateHolding","tags":["Holdings"],"summary":"Update holding yard bay, items, or release checklist","x-summary-ar":"تحديث موقع الساحة أو بنود قائمة التحقق للإفراج","description":"Updates release checklist flags (feesPaid, idVerified, ownershipVerified, finesCleared, supervisorApproved).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["enforcement:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/holdings/{id}/transitions/{code}":{"post":{"operationId":"transitionHolding","tags":["Holdings"],"summary":"Transition holding state (enforces release checklist gate!)","x-summary-ar":"تنفيذ انتقال حالة الحجز (يطبق بوابة التحقق قبل الإفراج)","description":"Validates holding workflow transitions and blocks `release` until all release checklist gates are satisfied.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"code","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":["enforcement:write"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/config/forms":{"get":{"operationId":"listConfigForms","tags":["Configuration"],"summary":"List configurable inspection form templates","x-summary-ar":"عرض قوالب نماذج وقوائم التفتيش","description":"Returns bilingual form templates and their JSON schemas.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":["config:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createConfigForm","tags":["Configuration"],"summary":"Create a draft inspection form template","x-summary-ar":"إنشاء مسودة نموذج تفتيش جديد","description":"Creates a new versioned form template draft.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/config/forms/{id}/publish":{"post":{"operationId":"publishConfigForm","tags":["Configuration"],"summary":"Validate via validateFormDefinition and publish form version","x-summary-ar":"التحقق من صحة النموذج ونشره","description":"Runs full static validation via `@bridges/forms` (`validateFormDefinition`) before publishing.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/config/workflows":{"get":{"operationId":"listConfigWorkflows","tags":["Configuration"],"summary":"List workflow state machine definitions","x-summary-ar":"عرض تعريفات سير العمل","description":"Lists configurable workflows for requests, inspections, warnings, fines, objections, and holdings.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":["config:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createConfigWorkflow","tags":["Configuration"],"summary":"Create a draft workflow definition","x-summary-ar":"إنشاء مسودة سير عمل جديد","description":"Creates a draft workflow definition ready for validation and publishing.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/config/workflows/{id}/publish":{"post":{"operationId":"publishConfigWorkflow","tags":["Configuration"],"summary":"Validate via validateWorkflowDefinition and publish workflow","x-summary-ar":"التحقق من صحة سير العمل ونشره","description":"Runs reachability, terminal state, and JSONLogic validation via `@bridges/workflow` before publishing.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/config/violations":{"get":{"operationId":"listViolations","tags":["Configuration"],"summary":"List violation catalog with repeat ladders & discounts","x-summary-ar":"عرض لائحة المخالفات وسلم التكرار والخصم المبكر","description":"Returns bilingual violation catalog items, legal references, penalties, and repeat ladders.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":["config:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createViolation","tags":["Configuration"],"summary":"Add a violation catalog entry","x-summary-ar":"إضافة بند مخالفة جديد إلى اللائحة","description":"Creates a bilingual violation catalog item with legal reference, penalty, and repeat ladder.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/config/inspection-types":{"get":{"operationId":"listInspectionTypes","tags":["Configuration"],"summary":"List inspection types","x-summary-ar":"عرض أنواع التفتيش","description":"Returns configured inspection types mapped to form templates, workflows, and SLAs.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":["config:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createInspectionType","tags":["Configuration"],"summary":"Create an inspection type","x-summary-ar":"إنشاء نوع تفتيش جديد","description":"Creates a new inspection type linking form template, workflow, required skill, and SLA.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/config/lookup-lists":{"get":{"operationId":"listLookupLists","tags":["Configuration"],"summary":"List reference lookup lists","x-summary-ar":"عرض القوائم المرجعية (الأنشطة، اللوحات، الأسباب)","description":"Returns bilingual reference lookup lists (activities, UAE/GCC plate sources, hold/return/reject/void reasons).","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":["config:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}}},"/api/v1/config/packages/export":{"get":{"operationId":"exportConfigPackage","tags":["Configuration"],"summary":"Export full entity configuration pack as versioned JSON","x-summary-ar":"تصدير حزمة إعدادات الجهة بالكامل كملف JSON","description":"Exports forms, workflows, violations, inspection types, request types, and lookup lists for promotion across environments.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":["config:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}}},"/api/v1/connections":{"get":{"operationId":"listConnections","tags":["Integrations"],"summary":"List external integration connections","x-summary-ar":"عرض اتصالات التكامل مع الأنظمة الخارجية","description":"Lists configured REST, inbound HTTP, and webhook connections for the active entity.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createConnection","tags":["Integrations"],"summary":"Create an external integration connection","x-summary-ar":"إنشاء اتصال تكامل جديد","description":"Creates a configurable external connection without writing custom code.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/connections/{id}/test":{"post":{"operationId":"testConnection","tags":["Integrations"],"summary":"Live test console against external URL + JSONata mapping preview","x-summary-ar":"وحدة الاختبار الحي للاتصال ومعاينة تحويل JSONata","description":"Executes a live HTTP call (e.g. against mock-external) and previews field mapping via `@bridges/integrations` without using eval.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"operation":"lookupLicense","params":{"licenseNo":"SHJ-KM-44012"}}}}}}},"/api/v1/connections/{id}/spec":{"get":{"operationId":"getConnectionSpec","tags":["Integrations"],"summary":"Auto-generated Integration Specification (Markdown or JSON)","x-summary-ar":"مواصفة التكامل المولدة تلقائياً (Markdown / JSON)","description":"Generates a complete bilingual integration specification via `generateIntegrationSpec` (`?format=markdown|json`).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}}},"/api/v1/flows":{"get":{"operationId":"listFlows","tags":["Integrations"],"summary":"List integration orchestration flows","x-summary-ar":"عرض تدفقات التكامل","description":"Lists event-driven and on-demand integration flows.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createFlow","tags":["Integrations"],"summary":"Create an integration flow","x-summary-ar":"إنشاء تدفق تكامل جديد","description":"Defines trigger, mapping steps, and retry/DLQ error policy.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/api/v1/integration-transactions":{"get":{"operationId":"listIntegrationTransactions","tags":["Integrations"],"summary":"List integration execution logs & transaction traces","x-summary-ar":"عرض سجل معاملات وتتبع التكامل","description":"Returns masked request/response logs, latencies, statuses, and correlation IDs.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}}},"/api/v1/webhook-endpoints":{"get":{"operationId":"listWebhookEndpoints","tags":["Integrations"],"summary":"List outbound webhook subscriptions","x-summary-ar":"عرض نقاط Webhook الصادرة","description":"Lists HMAC-SHA256 signed webhook subscriptions.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createWebhookEndpoint","tags":["Integrations"],"summary":"Register an outbound webhook endpoint","x-summary-ar":"تسجيل نقطة Webhook جديدة","description":"Registers an outbound URL, subscribed events, and generates an HMAC-SHA256 signing secret.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Finance ERP Listener","url":"http://localhost:4010/api/webhooks/finance","events":["fine.issued","fine.paid"]}}}}}},"/api/v1/api-clients":{"get":{"operationId":"listApiClients","tags":["Integrations"],"summary":"List single-entity machine API clients (SCP-7)","x-summary-ar":"عرض عملاء واجهة البرمجة المرتبطين بالجهة","description":"Lists active and revoked API clients scoped strictly to the active entity.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}},"post":{"operationId":"createApiClient","tags":["Integrations"],"summary":"Issue a new API client secret (shown once)","x-summary-ar":"إصدار عميل ومفتاح API جديد","description":"Creates a machine API client bound strictly to the active entity and returns the one-time Bearer secret.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"External Smart Portal Client","scopes":["requests:write","requests:read","subjects:read"]}}}}}},"/api/v1/in/{connectionKey}":{"post":{"operationId":"inboundEndpoint","tags":["Integrations"],"summary":"Dynamic Inbound HTTP Endpoint (INT-036) with dedupe & mapping","x-summary-ar":"نقطة الاستقبال الديناميكية للأنظمة الخارجية (INT-036)","description":"Maps external portal payloads into Bridges inspection requests via configured mapping rules with automatic deduplication.","parameters":[{"name":"connectionKey","in":"path","required":true,"schema":{"type":"string"}}],"security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"ticketId":"EXT-PORTAL-2026-9910","applicant":{"name":"سالم الظاهري","phone":"+971509876543","email":"salem@example.ae"},"urgency":"HIGH","details":"شكوى خارجية حول عدم التزام منشأة غذائية بمعايير التبريد"}}}}}},"/api/v1/sync/pull":{"get":{"operationId":"syncPull","tags":["Field Sync"],"summary":"Pull offline delta bundle for field inspector device","x-summary-ar":"سحب حزمة التحديثات الميدانية للعمل بدون إنترنت","description":"Returns assigned inspections, subjects, published form schemas, and violation catalog since `since` cursor.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}}},"/api/v1/sync/push":{"post":{"operationId":"syncPush","tags":["Field Sync"],"summary":"Push offline outbox mutations with opId idempotency & conflict detection","x-summary-ar":"رفع عمليات المزامنة الميدانية مع منع التكرار وكشف التعارض","description":"Replays queued offline field operations idempotently by `opId` and detects optimistic concurrency version conflicts.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"deviceId":"ipad-field-01","operations":[{"opId":"op-demo-0001","type":"inspection.save_answers","recordId":"01950000-0018-7000-8000-000000000004","baseVersion":1,"payload":{"answers":{"q_waste_manifest":"no","q_air_noise_compliance":"yes"}}}]}}}}}},"/api/v1/sync/reserve":{"post":{"operationId":"syncReserve","tags":["Field Sync"],"summary":"Reserve offline reference numbers & fine book serial block","x-summary-ar":"حجز نطاق أرقام مرجعية وتسلسلية للعمل الميداني دون اتصال","description":"Reserves an exclusive block of offline inspection references and/or fine book serials for an inspector device.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"deviceId":"ipad-field-01","recordType":"inspection","count":5}}}}}},"/api/v1/reports/dashboard":{"get":{"operationId":"getDashboardKpis","tags":["Reports & Audit"],"summary":"Executive & operational KPIs + chart datasets (BRD 18.1)","x-summary-ar":"مؤشرات الأداء التنفيذية والتشغيلية والرسوم البيانية","description":"Computes compliance rate, SLA adherence, fine collection, inspection volume by department/outcome, and holding yard stats.","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":["reports:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}}},"/api/v1/reports/export":{"get":{"operationId":"exportReport","tags":["Reports & Audit"],"summary":"Export bilingual UTF-8 BOM CSV or JSON via @bridges/analytics","x-summary-ar":"تصدير التقارير بصيغة CSV (UTF-8 BOM للعربية) أو JSON","description":"Exports `inspections`, `enforcement`, `requests`, or `subjects` with RPT-014 sensitive-field masking (`?dataset=inspections&format=csv|json`).","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":["reports:read"]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}}},"/api/v1/audit-events":{"get":{"operationId":"listAuditEvents","tags":["Reports & Audit"],"summary":"List immutable hash-chained audit events & Merkle checkpoint seals","x-summary-ar":"عرض سجل التدقيق غير القابل للتعديل وحالة أختام Merkle","description":"Returns append-only audit trail events and cryptographic checkpoint verification status (ADR-002).","parameters":[{"$ref":"#/components/parameters/XEntityId"},{"$ref":"#/components/parameters/AcceptLanguage"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"security":[{"BearerAuth":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}}},"/api/v1/public/status":{"get":{"operationId":"getPublicRequestStatus","tags":["Public"],"summary":"Track public request status by reference & tracking code","x-summary-ar":"الاستعلام العام عن حالة طلب بالرقم المرجعي ورمز التتبع","description":"Public, zero-PII request tracker (`?referenceNo=KM-PH-REQ-2026-000001&trackingCode=TRK-KM-1001`).","parameters":[],"security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}}},"/api/v1/public/verify/{code}":{"get":{"operationId":"verifyPublicDocument","tags":["Public"],"summary":"Verify official document authenticity by QR verification code (ENF-007)","x-summary-ar":"التحقق العام من صحة الوثيقة الرسمية عبر رمز QR","description":"Returns authenticity status, document type, reference number, issuing entity, and issue date with zero sensitive PII.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/ProblemResponse"},"403":{"$ref":"#/components/responses/ProblemResponse"},"404":{"$ref":"#/components/responses/ProblemResponse"},"409":{"$ref":"#/components/responses/ProblemResponse"},"422":{"$ref":"#/components/responses/ProblemResponse"},"429":{"$ref":"#/components/responses/ProblemResponse"}}}}},"webhooks":{"request.created":{"post":{"summary":"Emitted when a new inspection or service request is registered.","x-summary-ar":"يُرسل عند تسجيل طلب تفتيش أو خدمة جديد.","description":"Delivered with `X-Bridges-Signature: sha256=<hex>`, `X-Bridges-Timestamp`, `X-Bridges-Event`, and `X-Bridges-Delivery-Id` headers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"200":{"description":"Webhook acknowledged by receiver"}}}},"request.status_changed":{"post":{"summary":"Emitted whenever a request transitions between workflow states.","x-summary-ar":"يُرسل عند انتقال الطلب بين حالات سير العمل.","description":"Delivered with `X-Bridges-Signature: sha256=<hex>`, `X-Bridges-Timestamp`, `X-Bridges-Event`, and `X-Bridges-Delivery-Id` headers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"200":{"description":"Webhook acknowledged by receiver"}}}},"inspection.scheduled":{"post":{"summary":"Emitted when an inspection visit is scheduled for a subject.","x-summary-ar":"يُرسل عند جدولة زيارة تفتيش ميدانية.","description":"Delivered with `X-Bridges-Signature: sha256=<hex>`, `X-Bridges-Timestamp`, `X-Bridges-Event`, and `X-Bridges-Delivery-Id` headers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"200":{"description":"Webhook acknowledged by receiver"}}}},"inspection.completed":{"post":{"summary":"Emitted when a field inspection is submitted or approved with final score and outcome.","x-summary-ar":"يُرسل عند إتمام واعتماد التفتيش الميداني مع النتيجة والتقييم.","description":"Delivered with `X-Bridges-Signature: sha256=<hex>`, `X-Bridges-Timestamp`, `X-Bridges-Event`, and `X-Bridges-Delivery-Id` headers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"200":{"description":"Webhook acknowledged by receiver"}}}},"warning.issued":{"post":{"summary":"Emitted when an official bilingual municipal warning notice is issued.","x-summary-ar":"يُرسل عند إصدار إشعار إنذار بلدي رسمي.","description":"Delivered with `X-Bridges-Signature: sha256=<hex>`, `X-Bridges-Timestamp`, `X-Bridges-Event`, and `X-Bridges-Delivery-Id` headers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"200":{"description":"Webhook acknowledged by receiver"}}}},"fine.issued":{"post":{"summary":"Emitted when a fine is issued (including repeat-offender ladder & early-payment discount metadata).","x-summary-ar":"يُرسل عند إصدار مخالفة مالية مع تفاصيل سلم التكرار وخصم السداد المبكر.","description":"Delivered with `X-Bridges-Signature: sha256=<hex>`, `X-Bridges-Timestamp`, `X-Bridges-Event`, and `X-Bridges-Delivery-Id` headers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"200":{"description":"Webhook acknowledged by receiver"}}}},"fine.paid":{"post":{"summary":"Emitted when full or partial payment is recorded against a fine.","x-summary-ar":"يُرسل عند تسجيل سداد كامل أو جزئي لمخالفة مالية.","description":"Delivered with `X-Bridges-Signature: sha256=<hex>`, `X-Bridges-Timestamp`, `X-Bridges-Event`, and `X-Bridges-Delivery-Id` headers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"200":{"description":"Webhook acknowledged by receiver"}}}},"fine.cancelled":{"post":{"summary":"Emitted when a fine cancellation is approved under separation of duties.","x-summary-ar":"يُرسل عند اعتماد إلغاء مخالفة وفق فصل الصلاحيات.","description":"Delivered with `X-Bridges-Signature: sha256=<hex>`, `X-Bridges-Timestamp`, `X-Bridges-Event`, and `X-Bridges-Delivery-Id` headers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"200":{"description":"Webhook acknowledged by receiver"}}}},"objection.submitted":{"post":{"summary":"Emitted when a subject files an objection against an enforcement action.","x-summary-ar":"يُرسل عند تقديم اعتراض على مخالفة أو إجراء تنفيذي.","description":"Delivered with `X-Bridges-Signature: sha256=<hex>`, `X-Bridges-Timestamp`, `X-Bridges-Event`, and `X-Bridges-Delivery-Id` headers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"200":{"description":"Webhook acknowledged by receiver"}}}},"objection.decided":{"post":{"summary":"Emitted when an objection decision (upheld, reduced, or cancelled) is finalized.","x-summary-ar":"يُرسل عند البت النهائي في الاعتراض.","description":"Delivered with `X-Bridges-Signature: sha256=<hex>`, `X-Bridges-Timestamp`, `X-Bridges-Event`, and `X-Bridges-Delivery-Id` headers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"200":{"description":"Webhook acknowledged by receiver"}}}},"holding.ordered":{"post":{"summary":"Emitted when a vehicle impoundment or goods holding order is created.","x-summary-ar":"يُرسل عند إصدار أمر حجز مركبة أو مضبوطات.","description":"Delivered with `X-Bridges-Signature: sha256=<hex>`, `X-Bridges-Timestamp`, `X-Bridges-Event`, and `X-Bridges-Delivery-Id` headers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"200":{"description":"Webhook acknowledged by receiver"}}}},"holding.held":{"post":{"summary":"Emitted when the yard officer confirms physical receipt of a held vehicle or goods.","x-summary-ar":"يُرسل عند استلام المركبة أو المضبوطات فعلياً في ساحة الحجز.","description":"Delivered with `X-Bridges-Signature: sha256=<hex>`, `X-Bridges-Timestamp`, `X-Bridges-Event`, and `X-Bridges-Delivery-Id` headers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"200":{"description":"Webhook acknowledged by receiver"}}}},"holding.released":{"post":{"summary":"Emitted when release checklist gates pass and the asset is released.","x-summary-ar":"يُرسل عند استيفاء متطلبات الإفراج وتسليم المركبة أو المضبوطات.","description":"Delivered with `X-Bridges-Signature: sha256=<hex>`, `X-Bridges-Timestamp`, `X-Bridges-Event`, and `X-Bridges-Delivery-Id` headers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"200":{"description":"Webhook acknowledged by receiver"}}}},"sample.result_recorded":{"post":{"summary":"Emitted when laboratory analysis results are recorded for a public health sample.","x-summary-ar":"يُرسل عند تسجيل نتيجة الفحص المخبري لعينة الصحة العامة.","description":"Delivered with `X-Bridges-Signature: sha256=<hex>`, `X-Bridges-Timestamp`, `X-Bridges-Event`, and `X-Bridges-Delivery-Id` headers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"200":{"description":"Webhook acknowledged by receiver"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Bridges API Token","description":"Single-entity machine API client token (SCP-7). Available scopes: subjects:read, subjects:write, requests:read, requests:write, inspections:read, inspections:write, enforcement:read, enforcement:write, payments:write, evidence:read, evidence:write, reports:read, config:read."},"SessionCookie":{"type":"apiKey","in":"cookie","name":"BRIDGES_SESSION","description":"Authenticated interactive browser session cookie."}},"parameters":{"XEntityId":{"name":"X-Entity-Id","in":"header","required":false,"description":"Active entity UUID or code (e.g. `KALBA-MUN` or `SEPA-DEMO`) for multi-entity isolation.","schema":{"type":"string","example":"KALBA-MUN"}},"AcceptLanguage":{"name":"Accept-Language","in":"header","required":false,"description":"Preferred response & rendered document language (`ar` or `en`).","schema":{"type":"string","enum":["ar","en"],"default":"ar"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Client-generated idempotency key for safe retries without duplicate records (INT-003, REQ-005).","schema":{"type":"string","format":"uuid"}},"Limit":{"name":"limit","in":"query","required":false,"description":"Maximum number of records per page (1-200, default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},"Cursor":{"name":"cursor","in":"query","required":false,"description":"Opaque pagination cursor returned by the previous response.","schema":{"type":"string"}}},"responses":{"ProblemResponse":{"description":"RFC 9457 Problem Details error response","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"schemas":{"ProblemDetail":{"type":"object","required":["type","title","status","code","detail","correlationId"],"properties":{"type":{"type":"string","format":"uri","example":"https://bridges.inspect/errors/validation_failed"},"title":{"type":"string","example":"Validation Failed"},"status":{"type":"integer","example":422},"code":{"type":"string","enum":["unauthenticated","forbidden","module_disabled","not_found","validation_failed","conflict","transition_not_allowed","duplicate","rate_limited","integration_unavailable","internal_error"]},"detail":{"type":"string","example":"Request payload failed validation"},"instance":{"type":"string"},"correlationId":{"type":"string","format":"uuid"},"fields":{"type":"array","items":{"type":"object","required":["field","message"],"properties":{"field":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}}}},"PaginationMeta":{"type":"object","required":["total","limit","nextCursor","hasMore"],"properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"nextCursor":{"type":["string","null"]},"hasMore":{"type":"boolean"}}},"WebhookEnvelope":{"type":"object","required":["id","event","apiVersion","tenantId","entityId","occurredAt","data"],"properties":{"id":{"type":"string","format":"uuid"},"event":{"type":"string","enum":["request.created","request.status_changed","inspection.scheduled","inspection.completed","warning.issued","fine.issued","fine.paid","fine.cancelled","objection.submitted","objection.decided","holding.ordered","holding.held","holding.released","sample.result_recorded"]},"apiVersion":{"type":"string","example":"2026-01-01"},"tenantId":{"type":"string","format":"uuid"},"entityId":{"type":"string","format":"uuid"},"correlationId":{"type":"string","format":"uuid"},"occurredAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true}}}}}}