{ "openapi": "3.1.0", "info": { "title": "GroundIT — Comply", "version": "0.1.0", "license": { "name": "Proprietary — GroundIT/Sysmedac internal" }, "description": "The statutory compliance & filing surface — India EPFO/ESIC/PT/TDS dashboards with challan history and period filing; KSA WPS (via Mudad)/GOSI filing with Nitaqat/Saudization monitoring and Iqama & document-expiry alerting; and the unified cross-market compliance calendar & alert centre. Reads `pay` statutory outputs and `people` headcount/Iqama by service API/event — never recomputes payroll math. Submitted filings are immutable regulatory evidence. See ../../api-docs/00-api-overview-and-conventions.md.\n" }, "servers": [ { "url": "/api/v1" } ], "security": [ { "bearerJWT": [] } ], "tags": [ { "name": "comply", "description": "Statutory compliance & filing — India + KSA at parity, plus the cross-market calendar/alerts." }, { "name": "compliance_status", "description": "Rolling per-entity compliance standing (event-built projection, XC-F09)." }, { "name": "compliance_calendar", "description": "The unified cross-market statutory due-date timeline." }, { "name": "compliance_alert", "description": "Deadline reminder/overdue/escalation dispatch queue." }, { "name": "expiry_alert", "description": "Per-document (Iqama/passport/visa/…) expiry warning stream." }, { "name": "iqama_record", "description": "KSA residency-permit monitoring register." }, { "name": "statutory_filing", "description": "The shared immutable filing parent (India + KSA statutes)." }, { "name": "epfo_filing", "description": "India EPFO (PF/EPS ECR) filing detail." }, { "name": "esic_filing", "description": "India ESIC contribution filing detail." }, { "name": "pt_filing", "description": "India per-state Professional Tax filing detail." }, { "name": "tds_filing", "description": "India quarterly TDS-return (Form 24Q) filing detail." }, { "name": "wps_filing", "description": "KSA WPS (Wage Protection, via Mudad) filing detail." }, { "name": "gosi_filing", "description": "KSA GOSI social-insurance filing detail." }, { "name": "challan", "description": "India statutory deposit (challan/CIN/CRN) history." }, { "name": "mudad_record", "description": "KSA WPS money-movement tracking (read-only; executed via the xc interpay adapter)." }, { "name": "nitaqat_status", "description": "KSA Nitaqat/Saudization band standing." }, { "name": "saudization_ratio", "description": "Point-in-time Saudization ratio history behind a Nitaqat status." } ], "x-reuse-anchors": { "parameters": { "path_id": { "$ref": "#/components/parameters/PathId" }, "page_size": { "name": "page[size]", "in": "query", "required": false, "description": "Max items per page (cursor pagination only, 03 §2; offset pagination is rejected, ADR 0015). A non-integer, zero, negative or over-cap value is a `422 VALIDATION_FAILED` naming `/page[size]` — never a 500 and never a silent clamp. These reads return ONE capped page: there is no keyset cursor, `page.next_cursor` is always `null`, and `page.has_more` tells the caller whether the cap cut the result (#1253).\n", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "idempotency_key": { "$ref": "#/components/parameters/IdempotencyKey" }, "if_match": { "$ref": "#/components/parameters/IfMatch" } }, "responses": { "unauthorized": { "$ref": "#/components/responses/Unauthorized" }, "forbidden": { "$ref": "#/components/responses/Forbidden" }, "not_found": { "$ref": "#/components/responses/NotFound" }, "conflict": { "$ref": "#/components/responses/Conflict" }, "unprocessable": { "$ref": "#/components/responses/UnprocessableEntity" }, "locked": { "$ref": "#/components/responses/Locked" }, "too_many": { "$ref": "#/components/responses/TooManyRequests" }, "precondition_required": { "$ref": "#/components/responses/PreconditionRequired" }, "precondition_failed": { "$ref": "#/components/responses/PreconditionFailed" } }, "headers": { "etag": { "$ref": "#/components/headers/ETag" }, "location": { "$ref": "#/components/headers/Location" }, "idem_replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "paths": { "/compliance-status": { "get": { "operationId": "comply.compliance_status.list", "summary": "List compliance standing rollups", "description": "The role-aware compliance-command-centre read model — one row per legal entity per fiscal year with overall posture, open/overdue/at-risk counts, next due date and the per-statute rollup snapshot (CMP-S01 hero KPIs + statute card grid; also the mobile posture card, CMP-S10). Event-built projection (XC-F09); never the source of truth for an individual filing (fsd 11 §CMP-S01, db 12 §1).\n", "tags": [ "comply", "compliance_status" ], "x-token": "comply.compliance_status.list", "x-realizes-features": [ "CMP-F01", "CMP-F02", "CMP-F05" ], "x-screens": [ "CMP-S01", "CMP-S10" ], "x-touches-entities": [ "comply.compliance_status", "org.legal_entities", "org.compliance_packs" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "legal_entity_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UuidRef" } }, { "name": "fiscal_year", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "overall_status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/OverallStatus" } }, { "name": "page[size]", "in": "query", "required": false, "description": "Max items per page (cursor pagination only, 03 §2; offset pagination is rejected, ADR 0015). A non-integer, zero, negative or over-cap value is a `422 VALIDATION_FAILED` naming `/page[size]` — never a 500 and never a silent clamp. These reads return ONE capped page: there is no keyset cursor, `page.next_cursor` is always `null`, and `page.has_more` tells the caller whether the cap cut the result (#1253).\n", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `next_due_date`, `-next_due_date`, `fiscal_year`, `-fiscal_year`. Default `-fiscal_year`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of compliance standing rollups.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceStatusPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/compliance-status/{id}": { "get": { "operationId": "comply.compliance_status.get", "summary": "Get one compliance standing rollup", "description": "Single legal-entity/fiscal-year rollup, e.g. deep-linked from an alert or the calendar (fsd 11 §CMP-S01, db 12 §1).", "tags": [ "comply", "compliance_status" ], "x-token": "comply.compliance_status.get", "x-realizes-features": [ "CMP-F01", "CMP-F02", "CMP-F05" ], "x-screens": [ "CMP-S01", "CMP-S10" ], "x-touches-entities": [ "comply.compliance_status" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "The compliance standing rollup.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/compliance-status/sync": { "post": { "operationId": "comply.compliance_status.sync_portals", "summary": "Sync all statutory portals for a legal entity", "description": "Triggers a jobs-tier portal sync (XC-F08) that refreshes `compliance_status` and reads `ref→org.statutory_config` connection state — `comply` holds no portal credentials (CMP-S01 **Sync all portals**, Finance-gated, db 12 §1). Async.\n", "tags": [ "comply", "compliance_status" ], "x-token": "comply.compliance_status.sync_portals", "x-realizes-features": [ "CMP-F01", "CMP-F02", "CMP-F05" ], "x-screens": [ "CMP-S01" ], "x-touches-entities": [ "comply.compliance_status", "org.legal_entities", "org.statutory_config" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "async", "x-emits-event": "comply.compliance_status.synced", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncPortalsRequest" } } } }, "responses": { "202": { "description": "Portal sync enqueued; poll `GET` or subscribe to `comply.compliance_status.synced`.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncPortalsAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/compliance-calendar": { "get": { "operationId": "comply.compliance_calendar.list", "summary": "List the cross-market compliance calendar", "description": "Every India and KSA statutory due date for a legal entity on one timeline — EPFO/ESIC/PT/TDS, WPS/GOSI, Nitaqat review, Iqama renewal — with prep status and the filing that satisfied it (CMP-S08; also feeds the period grids on CMP-S02/CMP-S05 and the mobile upcoming-deadlines card, CMP-S10; db 12 §1).\n", "tags": [ "comply", "compliance_calendar" ], "x-token": "comply.compliance_calendar.list", "x-realizes-features": [ "CMP-F05" ], "x-screens": [ "CMP-S08", "CMP-S02", "CMP-S05", "CMP-S10" ], "x-touches-entities": [ "comply.compliance_calendar", "comply.statutory_filings", "org.legal_entities", "org.compliance_packs" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "legal_entity_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UuidRef" } }, { "name": "market", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/MarketCode" } }, { "name": "obligation_type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ObligationType" } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/CalendarStatus" } }, { "name": "due_date[from]", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DateOnlyRef" } }, { "name": "due_date[to]", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DateOnlyRef" } }, { "name": "page[size]", "in": "query", "required": false, "description": "Max items per page (cursor pagination only, 03 §2; offset pagination is rejected, ADR 0015). A non-integer, zero, negative or over-cap value is a `422 VALIDATION_FAILED` naming `/page[size]` — never a 500 and never a silent clamp. These reads return ONE capped page: there is no keyset cursor, `page.next_cursor` is always `null`, and `page.has_more` tells the caller whether the cap cut the result (#1253).\n", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `due_date`, `-due_date`, `status`. Default `due_date`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of calendar obligations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceCalendarPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/compliance-calendar/{id}": { "get": { "operationId": "comply.compliance_calendar.get", "summary": "Get one calendar obligation", "description": "A single obligation, deep-linked from the alert centre or a dashboard critical-alert (fsd 11 §CMP-S08, db 12 §1).", "tags": [ "comply", "compliance_calendar" ], "x-token": "comply.compliance_calendar.get", "x-realizes-features": [ "CMP-F05" ], "x-screens": [ "CMP-S08" ], "x-touches-entities": [ "comply.compliance_calendar" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "The calendar obligation.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceCalendarItem" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/compliance-calendar/{id}/mark-preparing": { "post": { "operationId": "comply.compliance_calendar.mark_preparing", "summary": "Mark an obligation as being prepared", "description": "`UPCOMING`/`DUE` → `PREPARING` — the worksheet is being assembled from `pay`/`tax` outputs, not yet submitted; there is no draft-filing row (CMP-S08 **Mark preparing**; mirrored implicitly when CMP-S02/CMP-S05 **Prepare** is used, gap 5, db 12 §1 lifecycle).\n", "tags": [ "comply", "compliance_calendar" ], "x-token": "comply.compliance_calendar.mark_preparing", "x-realizes-features": [ "CMP-F05" ], "x-screens": [ "CMP-S08", "CMP-S02", "CMP-S05" ], "x-touches-entities": [ "comply.compliance_calendar" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": "comply.compliance_calendar.marked_preparing", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": true, "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionNote" } } } }, "responses": { "200": { "description": "Obligation marked preparing.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceCalendarItem" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/compliance-calendar/{id}/waive": { "post": { "operationId": "comply.compliance_calendar.waive", "summary": "Waive an obligation", "description": "Marks a pre-`FILED` obligation as not applicable/exempted this period; the justification and actor are recorded in `audit` (XC-F06), **not** a `compliance_calendar` column — surfaced, not patched (CMP-S08 **Waive**, gap 6, db 12 §1).\n", "tags": [ "comply", "compliance_calendar" ], "x-token": "comply.compliance_calendar.waive", "x-realizes-features": [ "CMP-F05" ], "x-screens": [ "CMP-S08" ], "x-touches-entities": [ "comply.compliance_calendar" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": "comply.compliance_calendar.waived", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": true, "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaiveRequest" } } } }, "responses": { "200": { "description": "Obligation waived.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceCalendarItem" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/compliance-alerts": { "get": { "operationId": "comply.compliance_alert.list", "summary": "List statutory deadline alerts", "description": "The reminder/due-soon/overdue/escalation dispatch queue over calendar obligations (CMP-S09 deadline-alerts feed, db 12 §1).", "tags": [ "comply", "compliance_alert" ], "x-token": "comply.compliance_alert.list", "x-realizes-features": [ "CMP-F05" ], "x-screens": [ "CMP-S09" ], "x-touches-entities": [ "comply.compliance_alerts", "comply.compliance_calendar" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "compliance_calendar_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UuidRef" } }, { "name": "alert_type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/AlertType" } }, { "name": "tier", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/AlertTier" } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ComplianceAlertStatus" } }, { "name": "page[size]", "in": "query", "required": false, "description": "Max items per page (cursor pagination only, 03 §2; offset pagination is rejected, ADR 0015). A non-integer, zero, negative or over-cap value is a `422 VALIDATION_FAILED` naming `/page[size]` — never a 500 and never a silent clamp. These reads return ONE capped page: there is no keyset cursor, `page.next_cursor` is always `null`, and `page.has_more` tells the caller whether the cap cut the result (#1253).\n", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `scheduled_at`, `-scheduled_at`, `tier`. Default `-scheduled_at`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of compliance alerts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceAlertPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/compliance-alerts/{id}/acknowledge": { "post": { "operationId": "comply.compliance_alert.acknowledge", "summary": "Acknowledge a deadline alert", "description": "Stamps `acknowledged_at`/`acknowledged_by`, `status = 'ACKNOWLEDGED'` (CMP-S09 **Acknowledge**, gap 2, db 12 §1).", "tags": [ "comply", "compliance_alert" ], "x-token": "comply.compliance_alert.acknowledge", "x-realizes-features": [ "CMP-F05" ], "x-screens": [ "CMP-S09" ], "x-touches-entities": [ "comply.compliance_alerts" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": "comply.compliance_alert.acknowledged", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": true, "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionNote" } } } }, "responses": { "200": { "description": "Alert acknowledged.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceAlert" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/expiry-alerts": { "get": { "operationId": "comply.expiry_alert.list", "summary": "List document-expiry alerts", "description": "Tiered advance-warning stream over Iqama/passport/visa/work-permit/statutory documents (CMP-S07 expiry-alert grid; also CMP-S09's expiry feed, db 12 §4). KSA-first — Iqama/visa/work-permit are KSA obligations; passport/`STATUTORY_DOC` apply where a pack defines them.\n", "tags": [ "comply", "expiry_alert" ], "x-token": "comply.expiry_alert.list", "x-realizes-features": [ "CMP-F04", "CMP-F05" ], "x-screens": [ "CMP-S07", "CMP-S09" ], "x-touches-entities": [ "comply.expiry_alerts", "comply.iqama_records", "people.employees" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "iqama_record_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UuidRef" } }, { "name": "employee_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UuidRef" } }, { "name": "document_type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ExpiryDocumentType" } }, { "name": "tier", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ExpiryTier" } }, { "name": "severity", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ExpirySeverity" } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ExpiryAlertStatus" } }, { "name": "page[size]", "in": "query", "required": false, "description": "Max items per page (cursor pagination only, 03 §2; offset pagination is rejected, ADR 0015). A non-integer, zero, negative or over-cap value is a `422 VALIDATION_FAILED` naming `/page[size]` — never a 500 and never a silent clamp. These reads return ONE capped page: there is no keyset cursor, `page.next_cursor` is always `null`, and `page.has_more` tells the caller whether the cap cut the result (#1253).\n", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `expiry_date`, `-expiry_date`, `tier`. Default `expiry_date`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of document-expiry alerts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpiryAlertPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/expiry-alerts/{id}/acknowledge": { "post": { "operationId": "comply.expiry_alert.acknowledge", "summary": "Acknowledge a document-expiry alert", "description": "Stamps `acknowledged_at`/`acknowledged_by`, `status = 'ACKNOWLEDGED'` (CMP-S07/CMP-S09 **Acknowledge**, gap 2, db 12 §4).", "tags": [ "comply", "expiry_alert" ], "x-token": "comply.expiry_alert.acknowledge", "x-realizes-features": [ "CMP-F04", "CMP-F05" ], "x-screens": [ "CMP-S07", "CMP-S09" ], "x-touches-entities": [ "comply.expiry_alerts" ], "x-idempotent": true, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": "comply.expiry_alert.acknowledged", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": true, "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionNote" } } } }, "responses": { "200": { "description": "Alert acknowledged.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpiryAlert" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/iqama-records": { "get": { "operationId": "comply.iqama_record.list", "summary": "List Iqama records", "description": "The residency-compliance monitoring register — permit number, profession, expiry status (CMP-S07 Iqama register grid, db 12 §4). `comply`'s projection of `people`'s Iqama master, read via service API/event — never a join.\n", "tags": [ "comply", "iqama_record" ], "x-token": "comply.iqama_record.list", "x-realizes-features": [ "CMP-F04" ], "x-screens": [ "CMP-S07" ], "x-touches-entities": [ "comply.iqama_records", "people.employees" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "employee_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UuidRef" } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/IqamaStatus" } }, { "name": "expiry_date[from]", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DateOnlyRef" } }, { "name": "expiry_date[to]", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DateOnlyRef" } }, { "name": "page[size]", "in": "query", "required": false, "description": "Max items per page (cursor pagination only, 03 §2; offset pagination is rejected, ADR 0015). A non-integer, zero, negative or over-cap value is a `422 VALIDATION_FAILED` naming `/page[size]` — never a 500 and never a silent clamp. These reads return ONE capped page: there is no keyset cursor, `page.next_cursor` is always `null`, and `page.has_more` tells the caller whether the cap cut the result (#1253).\n", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `expiry_date`, `-expiry_date`, `status`. Default `expiry_date`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of Iqama records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IqamaRecordPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/iqama-records/{id}": { "get": { "operationId": "comply.iqama_record.get", "summary": "Get one Iqama record (with its expiry alerts)", "description": "The Iqama record plus its embedded per-document expiry alerts, for the register's detail drawer (CMP-S07 `PT-DETAIL`, db 12 §4).", "tags": [ "comply", "iqama_record" ], "x-token": "comply.iqama_record.get", "x-realizes-features": [ "CMP-F04" ], "x-screens": [ "CMP-S07" ], "x-touches-entities": [ "comply.iqama_records", "comply.expiry_alerts" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "The Iqama record with its expiry alerts.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IqamaRecordDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/iqama-records/{id}/mark-under-renewal": { "post": { "operationId": "comply.iqama_record.mark_under_renewal", "summary": "Mark an Iqama as under renewal", "description": "`status = 'UNDER_RENEWAL'` while a renewal is in progress (CMP-S07 **Mark under renewal**, db 12 §4 lifecycle).", "tags": [ "comply", "iqama_record" ], "x-token": "comply.iqama_record.mark_under_renewal", "x-realizes-features": [ "CMP-F04" ], "x-screens": [ "CMP-S07" ], "x-touches-entities": [ "comply.iqama_records" ], "x-idempotent": true, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": "comply.iqama_record.renewal_started", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": true, "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionNote" } } } }, "responses": { "200": { "description": "Marked under renewal.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IqamaRecord" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/iqama-records/{id}/record-renewal": { "post": { "operationId": "comply.iqama_record.record_renewal", "summary": "Record a completed Iqama renewal", "description": "`status = 'VALID'`, stamps `last_renewed_at`, and resolves the record's open expiry alerts (`status = 'RESOLVED'`, `resolved_at`) (CMP-S07 **Record renewal**, db 12 §4 lifecycle).\n", "tags": [ "comply", "iqama_record" ], "x-token": "comply.iqama_record.record_renewal", "x-realizes-features": [ "CMP-F04" ], "x-screens": [ "CMP-S07" ], "x-touches-entities": [ "comply.iqama_records", "comply.expiry_alerts" ], "x-idempotent": true, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": "comply.iqama_record.renewed", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": true, "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordRenewalRequest" } } } }, "responses": { "200": { "description": "Renewal recorded.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IqamaRecord" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/filing-worksheets": { "get": { "operationId": "comply.filing_worksheet.list", "summary": "List filing worksheets (the computed, not-yet-filed position)", "description": "`comply.filing_worksheets` (migration `0174`, #95) — what the payroll tier COMPUTED for a period, before anything is lodged. The SECOND of the three reads behind `CMP-S02`'s grid: the calendar supplies the obligation and its due date, this supplies `total_amount`/`headcount`/the artifact refs, and `comply.statutory_filing.list` supplies the filed figure once one exists — and once it does, it wins (`04-spec-cmp-s02` §2). A MUTABLE projection, not evidence: it is re-derivable from `payroll_run_id` and a re-execution refreshes it in place. PT is one row PER STATE for a period (`state_code` set); every other statute is period-level and carries `null`.\n", "tags": [ "comply", "filing_worksheet" ], "x-token": "comply.statutory_filing.list", "x-realizes-features": [ "CMP-F01" ], "x-screens": [ "CMP-S02" ], "x-touches-entities": [ "comply.filing_worksheets", "org.legal_entities", "pay.payroll_runs" ], "x-idempotent": false, "x-market": "India", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "legal_entity_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UuidRef" } }, { "name": "statute", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Statute" } }, { "name": "period", "in": "query", "required": false, "description": "Pack period mask — `YYYY-MM` for EPFO/ESIC/PT, `YYYY-Qn` for TDS.", "schema": { "type": "string" } }, { "name": "page[size]", "in": "query", "required": false, "description": "Max items per page (cursor pagination only, 03 §2; offset pagination is rejected, ADR 0015). A non-integer, zero, negative or over-cap value is a `422 VALIDATION_FAILED` naming `/page[size]` — never a 500 and never a silent clamp. These reads return ONE capped page: there is no keyset cursor, `page.next_cursor` is always `null`, and `page.has_more` tells the caller whether the cap cut the result (#1253).\n", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Page of filing worksheets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingWorksheetPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/statutory-filings": { "get": { "operationId": "comply.statutory_filing.list", "summary": "List statutory filings", "description": "The immutable filing parent, both markets — period-by-period rows behind the India filing console (CMP-S02) and KSA console (CMP-S05); filter by `(legal_entity_id, statute, period)` for a filing's compensating-row lineage (CMP-S03, db 12 §2/§3).\n", "tags": [ "comply", "statutory_filing" ], "x-token": "comply.statutory_filing.list", "x-realizes-features": [ "CMP-F01", "CMP-F02" ], "x-screens": [ "CMP-S02", "CMP-S03", "CMP-S05" ], "x-touches-entities": [ "comply.statutory_filings", "org.legal_entities", "org.compliance_packs" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "legal_entity_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UuidRef" } }, { "name": "statute", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Statute" } }, { "name": "market", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/MarketCode" } }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/FilingStatus" } }, { "name": "page[size]", "in": "query", "required": false, "description": "Max items per page (cursor pagination only, 03 §2; offset pagination is rejected, ADR 0015). A non-integer, zero, negative or over-cap value is a `422 VALIDATION_FAILED` naming `/page[size]` — never a 500 and never a silent clamp. These reads return ONE capped page: there is no keyset cursor, `page.next_cursor` is always `null`, and `page.has_more` tells the caller whether the cap cut the result (#1253).\n", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `filed_at`, `-filed_at`, `period`. Default `-filed_at`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of statutory filings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatutoryFilingPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/statutory-filings/{id}": { "get": { "operationId": "comply.statutory_filing.get", "summary": "Get one statutory filing (evidence detail)", "description": "The immutable evidence view — parent facts, the per-statute child detail, and the compensating-row lineage sharing `(legal_entity_id, statute, period)` (CMP-S03, db 12 §2/§3).\n", "tags": [ "comply", "statutory_filing" ], "x-token": "comply.statutory_filing.get", "x-realizes-features": [ "CMP-F01", "CMP-F02" ], "x-screens": [ "CMP-S03" ], "x-touches-entities": [ "comply.statutory_filings", "comply.epfo_filings", "comply.esic_filings", "comply.pt_filings", "comply.tds_filings", "comply.wps_filings", "comply.gosi_filings", "people.employees", "org.compliance_packs" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "The filing with its per-statute child detail and lineage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatutoryFilingDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/statutory-filings/{id}/download": { "get": { "operationId": "comply.statutory_filing.download_artifact", "summary": "Download the filed return artifact", "description": "Mints a time-limited presigned URL for the submitted-return artifact; integrity by `content_hash` SHA-256 (CMP-S03 **Download artifact**, XC-F07, db 12 §2).", "tags": [ "comply", "statutory_filing" ], "x-token": "comply.statutory_filing.download_artifact", "x-realizes-features": [ "CMP-F01", "CMP-F02" ], "x-screens": [ "CMP-S03" ], "x-touches-entities": [ "comply.statutory_filings" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "Presigned download handle for the filed return.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDownloadRef" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/statutory-filings/{id}/acknowledgements": { "post": { "operationId": "comply.statutory_filing.record_acknowledgement", "summary": "Record a regulator acknowledgement/acceptance", "description": "Writes a NEW compensating `statutory_filings` row (new `filing_no`, same `legal_entity_id`+`statute`+`period`) with `acknowledgement_ref` set and `status` `ACKNOWLEDGED`/`ACCEPTED` — never an in-place edit of the original (CMP-S03 **Record acknowledgement**, db 12 §2 Notes). Audited (XC-F06).\n", "tags": [ "comply", "statutory_filing" ], "x-token": "comply.statutory_filing.record_acknowledgement", "x-realizes-features": [ "CMP-F01", "CMP-F02" ], "x-screens": [ "CMP-S03" ], "x-touches-entities": [ "comply.statutory_filings" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": "comply.statutory_filing.acknowledged", "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgementRequest" } } } }, "responses": { "201": { "description": "Compensating acknowledgement row created.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatutoryFiling" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/statutory-filings/{id}/rejections": { "post": { "operationId": "comply.statutory_filing.record_rejection", "summary": "Record a regulator rejection", "description": "Writes a NEW compensating `statutory_filings` row (`status = 'REJECTED'`) — a **File revised return** (the corresponding `*_filing.submit` op with `revises_filing_id` set) typically follows (CMP-S03 **Record rejection**, db 12 §2 Notes). Audited (XC-F06).\n", "tags": [ "comply", "statutory_filing" ], "x-token": "comply.statutory_filing.record_rejection", "x-realizes-features": [ "CMP-F01", "CMP-F02" ], "x-screens": [ "CMP-S03" ], "x-touches-entities": [ "comply.statutory_filings" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": "comply.statutory_filing.rejected", "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectionRequest" } } } }, "responses": { "201": { "description": "Compensating rejection row created.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatutoryFiling" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/epfo-filings": { "post": { "operationId": "comply.epfo_filing.submit", "summary": "Prepare & file an EPFO (PF/EPS ECR) return", "description": "Builds the ECR from `ref→pay.payroll_runs`/`pay.payslips` EPF/EPS deductions (never recomputed), raises maker/checker approval (XC-F12), and — once approved — writes the shared `comply.statutory_filings` parent (`statute = 'EPFO'`) + the `epfo_filings` child, stamps `compliance_pack_version`, and advances the satisfied `compliance_calendar` item to `FILED` (CMP-S02 **Submit**, fsd 11 §2.2, db 12 §2). Set `revises_filing_id` to file a compensating **revised return**. Runs on the jobs tier (XC-F08); async.\n", "tags": [ "comply", "epfo_filing" ], "x-token": "comply.epfo_filing.submit", "x-realizes-features": [ "CMP-F01" ], "x-screens": [ "CMP-S02" ], "x-touches-entities": [ "comply.statutory_filings", "comply.epfo_filings", "comply.compliance_calendar", "pay.payroll_runs", "pay.payslips", "org.compliance_packs", "org.statutory_config" ], "x-idempotent": true, "x-market": "India", "x-sync-async": "async", "x-emits-event": "comply.epfo_filing.submitted", "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpfoFilingSubmit" } } } }, "responses": { "202": { "description": "Submission enqueued; poll `comply.statutory_filing.list` or subscribe to `comply.epfo_filing.submitted`.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingSubmitAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/esic-filings": { "post": { "operationId": "comply.esic_filing.submit", "summary": "Prepare & file an ESIC contribution return", "description": "Builds the ESI return from `ref→pay.payroll_runs`/`pay.payslips` ESI deductions, raises maker/checker approval (XC-F12), and — once approved — writes the shared parent (`statute = 'ESIC'`) + `esic_filings` child and advances the calendar item (CMP-S02 **Submit**, fsd 11 §2.2, db 12 §2). Set `revises_filing_id` for a compensating revised return. Async (XC-F08).\n", "tags": [ "comply", "esic_filing" ], "x-token": "comply.esic_filing.submit", "x-realizes-features": [ "CMP-F01" ], "x-screens": [ "CMP-S02" ], "x-touches-entities": [ "comply.statutory_filings", "comply.esic_filings", "comply.compliance_calendar", "pay.payroll_runs", "pay.payslips", "org.compliance_packs", "org.statutory_config" ], "x-idempotent": true, "x-market": "India", "x-sync-async": "async", "x-emits-event": "comply.esic_filing.submitted", "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsicFilingSubmit" } } } }, "responses": { "202": { "description": "Submission enqueued; poll `comply.statutory_filing.list` or subscribe to `comply.esic_filing.submitted`.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingSubmitAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pt-filings": { "post": { "operationId": "comply.pt_filing.submit", "summary": "Prepare & file a Professional Tax return (per state)", "description": "PT is state-divergent — one `pt_filings` child per state under a single filing parent (`statute = 'PT'`); the per-state slab/registration set is pack-supplied. Raises maker/checker approval (XC-F12) and — once approved — writes the shared parent + one child per submitted state and advances the calendar item (CMP-S02 **Submit**, fsd 11 §2.2, db 12 §2). Set `revises_filing_id` for a compensating revised return. Async (XC-F08).\n", "tags": [ "comply", "pt_filing" ], "x-token": "comply.pt_filing.submit", "x-realizes-features": [ "CMP-F01" ], "x-screens": [ "CMP-S02" ], "x-touches-entities": [ "comply.statutory_filings", "comply.pt_filings", "comply.compliance_calendar", "pay.payroll_runs", "pay.payslips", "org.compliance_packs", "org.statutory_config" ], "x-idempotent": true, "x-market": "India", "x-sync-async": "async", "x-emits-event": "comply.pt_filing.submitted", "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PtFilingSubmit" } } } }, "responses": { "202": { "description": "Submission enqueued; poll `comply.statutory_filing.list` or subscribe to `comply.pt_filing.submitted`.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingSubmitAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tds-filings": { "post": { "operationId": "comply.tds_filing.submit", "summary": "Prepare & file a quarterly TDS return (Form 24Q)", "description": "Aggregates `ref→tax.tds_records` across the quarter (TAX-F04) — never recomputed — raises maker/checker approval (XC-F12), and — once approved — writes the shared parent (`statute = 'TDS'`) + `tds_filings` child and advances the calendar item (CMP-S02 **Submit**, fsd 11 §2.2, db 12 §2). Set `revises_filing_id` to file a correction statement. Async (XC-F08).\n", "tags": [ "comply", "tds_filing" ], "x-token": "comply.tds_filing.submit", "x-realizes-features": [ "CMP-F01" ], "x-screens": [ "CMP-S02" ], "x-touches-entities": [ "comply.statutory_filings", "comply.tds_filings", "comply.compliance_calendar", "tax.tds_records", "pay.payroll_runs", "org.compliance_packs" ], "x-idempotent": true, "x-market": "India", "x-sync-async": "async", "x-emits-event": "comply.tds_filing.submitted", "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TdsFilingSubmit" } } } }, "responses": { "202": { "description": "Submission enqueued; poll `comply.statutory_filing.list` or subscribe to `comply.tds_filing.submitted`.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingSubmitAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/wps-filings": { "post": { "operationId": "comply.wps_filing.submit", "summary": "Build & submit the WPS wage file via Mudad", "description": "Lodges the wage file for a period. The SIF itself is generated by the payroll tier (`comply.generate_ksa_wps`), which since #1250 writes only a `comply.filing_worksheets` projection and lodges nothing — this operation is the ONLY writer of `comply.statutory_filings` (db 12 §1). It derives `total_amount` (net wages disbursed) and `headcount` server-side from the reviewed `payroll_run_id`, takes the file's storage key and digest from that period's worksheet (never from the body), writes the shared parent (`statute = 'WPS'`) + `wps_filings` child, and opens the money-movement tracking row (`comply.mudad_records`, read via `comply.mudad_record.*`) through the **`xc` interpay adapter** (ADR 0013) — `comply` records `interpay_ref`, it never moves money itself (CMP-S05 **Prepare WPS file → Submit via Mudad**, fsd 11 §3.1, db 12 §3). A period that already has a live filing is a `409 STATE_TRANSITION_INVALID`; a correction is a revised return — set `revises_filing_id` to the filing that CURRENTLY stands. A period whose run produced no SIF is a `422` naming `/payrollRunId`. Async (XC-F08).\n", "tags": [ "comply", "wps_filing" ], "x-token": "comply.wps_filing.submit", "x-realizes-features": [ "CMP-F02" ], "x-screens": [ "CMP-S05" ], "x-touches-entities": [ "comply.statutory_filings", "comply.wps_filings", "comply.mudad_records", "comply.filing_worksheets", "comply.compliance_calendar", "pay.payroll_runs", "pay.payslips", "pay.deductions", "org.compliance_packs", "org.statutory_config" ], "x-idempotent": true, "x-market": "KSA", "x-sync-async": "async", "x-emits-event": "comply.wps_filing.submitted", "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WpsFilingSubmit" } } } }, "responses": { "202": { "description": "Submission enqueued; poll `comply.statutory_filing.list` or subscribe to `comply.wps_filing.submitted`.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingSubmitAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/gosi-filings": { "post": { "operationId": "comply.gosi_filing.submit", "summary": "Prepare & file a GOSI contribution return", "description": "Lodges the GOSI contribution return for a month. Since #1250 the employee/employer contribution amounts and the contributory wage base are derived server-side from the reviewed `payroll_run_id` (`pay.deductions` `GOSI` lines) and are no longer accepted on the wire; only the Saudi/non-Saudi headcount split is the maker's attestation, because nothing in the model can derive it. **Currently refuses every submission with a `422` naming `/payrollRunId`:** `packages/pay-calc` emits no `GOSI` deduction line yet, so no run carries a contribution to file, and a `0.00` return is indistinguishable from a genuine nil-liability one. Writes the shared parent (`statute = 'GOSI'`) + `gosi_filings` child and advances the calendar item (CMP-S05 **Submit GOSI**, fsd 11 §3.1, db 12 §3). A period that already has a live filing is a `409 STATE_TRANSITION_INVALID`; set `revises_filing_id` to the filing that CURRENTLY stands for a compensating revised return. Async (XC-F08).\n", "tags": [ "comply", "gosi_filing" ], "x-token": "comply.gosi_filing.submit", "x-realizes-features": [ "CMP-F02" ], "x-screens": [ "CMP-S05" ], "x-touches-entities": [ "comply.statutory_filings", "comply.gosi_filings", "comply.compliance_calendar", "pay.payroll_runs", "pay.payslips", "pay.deductions", "org.compliance_packs", "org.statutory_config" ], "x-idempotent": true, "x-market": "KSA", "x-sync-async": "async", "x-emits-event": "comply.gosi_filing.submitted", "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GosiFilingSubmit" } } } }, "responses": { "202": { "description": "Submission enqueued; poll `comply.statutory_filing.list` or subscribe to `comply.gosi_filing.submitted`.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingSubmitAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/challans": { "get": { "operationId": "comply.challan.list", "summary": "List the India statutory deposit (challan) history", "description": "Every challan (CIN/CRN) paid against a filing's liability, with bank/portal reference and receipt (CMP-S04 grid, db 12 §2).", "tags": [ "comply", "challan" ], "x-token": "comply.challan.list", "x-realizes-features": [ "CMP-F01" ], "x-screens": [ "CMP-S04" ], "x-touches-entities": [ "comply.challan_history", "comply.statutory_filings" ], "x-idempotent": false, "x-market": "India", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "statutory_filing_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UuidRef" } }, { "name": "statute", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/IndiaStatute" } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ChallanStatus" } }, { "name": "source", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ChallanSource" } }, { "name": "payment_date[from]", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DateOnlyRef" } }, { "name": "payment_date[to]", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DateOnlyRef" } }, { "name": "page[size]", "in": "query", "required": false, "description": "Max items per page (cursor pagination only, 03 §2; offset pagination is rejected, ADR 0015). A non-integer, zero, negative or over-cap value is a `422 VALIDATION_FAILED` naming `/page[size]` — never a 500 and never a silent clamp. These reads return ONE capped page: there is no keyset cursor, `page.next_cursor` is always `null`, and `page.has_more` tells the caller whether the cap cut the result (#1253).\n", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `payment_date`, `-payment_date`, `status`. Default `-payment_date`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of challan deposits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChallanPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "comply.challan.upload_manual", "summary": "Upload a manual challan", "description": "Records a deposit the portal sync missed as a new append-only row (`source = 'MANUAL'`) — challans are immutable; a reversal/reconciliation outcome is a compensating row, never an edit (CMP-S04 **Upload Manual Challan**, gap 2, db 12 §2). Portal-synced deposits arrive via the jobs-tier sync (XC-F08, `source = 'PORTAL_SYNC'`) and are not created through this endpoint.\n", "tags": [ "comply", "challan" ], "x-token": "comply.challan.upload_manual", "x-realizes-features": [ "CMP-F01" ], "x-screens": [ "CMP-S04" ], "x-touches-entities": [ "comply.challan_history", "comply.statutory_filings" ], "x-idempotent": true, "x-market": "India", "x-sync-async": "sync", "x-emits-event": "comply.challan.uploaded", "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChallanUploadRequest" } } } }, "responses": { "201": { "description": "Manual challan recorded.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChallanRecord" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/challans/{id}/download": { "get": { "operationId": "comply.challan.download_receipt", "summary": "Download the stamped challan receipt", "description": "Mints a time-limited presigned URL for the receipt artifact; integrity by `content_hash` SHA-256 (CMP-S04 row **Download receipt**, XC-F07, db 12 §2).", "tags": [ "comply", "challan" ], "x-token": "comply.challan.download_receipt", "x-realizes-features": [ "CMP-F01" ], "x-screens": [ "CMP-S04" ], "x-touches-entities": [ "comply.challan_history" ], "x-idempotent": false, "x-market": "India", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "Presigned download handle for the challan receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDownloadRef" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/mudad-records": { "get": { "operationId": "comply.mudad_record.list", "summary": "List Mudad money-movement records", "description": "The SAR salary-disbursement tracking behind a WPS filing, queued through confirmed, executed via the **`xc` interpay adapter** (ADR 0013) — read-only here; `comply` records the result but never moves money itself (CMP-S03/CMP-S05 Mudad movement panel, db 12 §3).\n", "tags": [ "comply", "mudad_record" ], "x-token": "comply.mudad_record.list", "x-realizes-features": [ "CMP-F02" ], "x-screens": [ "CMP-S03", "CMP-S05" ], "x-touches-entities": [ "comply.mudad_records", "comply.wps_filings" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "wps_filing_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UuidRef" } }, { "name": "movement_status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/MudadMovementStatus" } }, { "name": "page[size]", "in": "query", "required": false, "description": "Max items per page (cursor pagination only, 03 §2; offset pagination is rejected, ADR 0015). A non-integer, zero, negative or over-cap value is a `422 VALIDATION_FAILED` naming `/page[size]` — never a 500 and never a silent clamp. These reads return ONE capped page: there is no keyset cursor, `page.next_cursor` is always `null`, and `page.has_more` tells the caller whether the cap cut the result (#1253).\n", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `submitted_at`, `-submitted_at`. Default `-submitted_at`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of Mudad money-movement records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MudadRecordPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/mudad-records/{id}": { "get": { "operationId": "comply.mudad_record.get", "summary": "Get one Mudad money-movement record", "description": "Single movement's rail response summary (db 12 §3).", "tags": [ "comply", "mudad_record" ], "x-token": "comply.mudad_record.get", "x-realizes-features": [ "CMP-F02" ], "x-screens": [ "CMP-S03", "CMP-S05" ], "x-touches-entities": [ "comply.mudad_records" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "The Mudad money-movement record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MudadRecord" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/nitaqat-status": { "get": { "operationId": "comply.nitaqat_status.list", "summary": "List Nitaqat/Saudization band standings", "description": "The legal entity's live Saudization ratio against size/activity thresholds, band/colour, and distance to the next band (CMP-S06 hero card; also the KSA tiles on CMP-S01 and the mobile Saudization band, CMP-S10, db 12 §4). Read-only projection recomputed by the jobs tier (XC-F08).\n", "tags": [ "comply", "nitaqat_status" ], "x-token": "comply.nitaqat_status.list", "x-realizes-features": [ "CMP-F03" ], "x-screens": [ "CMP-S06", "CMP-S01", "CMP-S10" ], "x-touches-entities": [ "comply.nitaqat_status", "org.legal_entities", "org.compliance_packs", "people.employees" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "legal_entity_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UuidRef" } }, { "name": "band", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/NitaqatBand" } }, { "name": "page[size]", "in": "query", "required": false, "description": "Max items per page (cursor pagination only, 03 §2; offset pagination is rejected, ADR 0015). A non-integer, zero, negative or over-cap value is a `422 VALIDATION_FAILED` naming `/page[size]` — never a 500 and never a silent clamp. These reads return ONE capped page: there is no keyset cursor, `page.next_cursor` is always `null`, and `page.has_more` tells the caller whether the cap cut the result (#1253).\n", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `computed_at`, `-computed_at`. Default `-computed_at`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of Nitaqat/Saudization band standings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NitaqatStatusPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/nitaqat-status/{id}": { "get": { "operationId": "comply.nitaqat_status.get", "summary": "Get one Nitaqat/Saudization band standing", "description": "The single legal entity's live band standing, drilled from CMP-S01/CMP-S10 (fsd 11 §3.2, db 12 §4).", "tags": [ "comply", "nitaqat_status" ], "x-token": "comply.nitaqat_status.get", "x-realizes-features": [ "CMP-F03" ], "x-screens": [ "CMP-S06" ], "x-touches-entities": [ "comply.nitaqat_status" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "The Nitaqat/Saudization band standing.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NitaqatStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/saudization-ratios": { "get": { "operationId": "comply.saudization_ratio.list", "summary": "List the Saudization ratio trend under a Nitaqat status", "description": "The point-in-time ratio history (with the band it fell in) driving the CMP-S06 trend chart and distance-to-next-band (db 12 §4).", "tags": [ "comply", "saudization_ratio" ], "x-token": "comply.saudization_ratio.list", "x-realizes-features": [ "CMP-F03" ], "x-screens": [ "CMP-S06" ], "x-touches-entities": [ "comply.saudization_ratios", "comply.nitaqat_status" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "comply", "x-provisional": null, "parameters": [ { "name": "nitaqat_status_id", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/UuidRef" } }, { "name": "as_of_date[from]", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DateOnlyRef" } }, { "name": "as_of_date[to]", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DateOnlyRef" } }, { "name": "page[size]", "in": "query", "required": false, "description": "Max items per page (cursor pagination only, 03 §2; offset pagination is rejected, ADR 0015). A non-integer, zero, negative or over-cap value is a `422 VALIDATION_FAILED` naming `/page[size]` — never a 500 and never a silent clamp. These reads return ONE capped page: there is no keyset cursor, `page.next_cursor` is always `null`, and `page.has_more` tells the caller whether the cap cut the result (#1253).\n", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `as_of_date`, `-as_of_date`. Default `as_of_date`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of Saudization ratio history points.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaudizationRatioPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "securitySchemes": { "bearerJWT": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Product session token. Two mint paths, one contract (ADR 0010): employees/managers authenticate against Keycloak (mobile + web); workspace staff arrive from the One portal via bridge-token SSO (`POST /api/sso/exchange` verifies the platform's Ed25519 token and mints the product session). The token carries IDENTITY ONLY — `sub`, `tenantUid`, `principal_class`, MFA level, session ref, `exp`. Roles/permissions are re-resolved server-side per request. Enforcement is layered: gateway (TLS/WAF/routing only — NEVER trusted for auth) → NestJS auth guard (validates token, builds the request auth-context) → entitlement middleware (subscription-status → feature-flag → numeric-limit, ADR 0009) → `SET LOCAL app.tenant_id` / `app.user_id` → Postgres FORCED RLS. `tenantUid` is NEVER a path, query, or body parameter.\n" } }, "schemas": { "UuidRef": { "$ref": "#/components/schemas/Uuid" }, "DateOnlyRef": { "$ref": "#/components/schemas/DateOnly" }, "TimestampRef": { "$ref": "#/components/schemas/Timestamp" }, "RateRef": { "$ref": "#/components/schemas/Rate" }, "MoneyRef": { "$ref": "#/components/schemas/Money" }, "BusinessNoRef": { "$ref": "#/components/schemas/BusinessNo" }, "HijriDisplayRef": { "$ref": "#/components/schemas/HijriDisplay" }, "AuditMetaRef": { "$ref": "#/components/schemas/AuditMeta" }, "AppendOnlyMetaRef": { "$ref": "#/components/schemas/AppendOnlyMeta" }, "CursorPageRef": { "$ref": "#/components/schemas/CursorPage" }, "FileDownloadRef": { "$ref": "#/components/schemas/FileDownload" }, "MarketCode": { "type": "string", "enum": [ "IN", "KSA" ], "description": "comply.market — the pack-resolved jurisdiction of the row (db 12 §intro market split). Distinct from the x-market op-metadata axis." }, "OverallStatus": { "type": "string", "enum": [ "COMPLIANT", "AT_RISK", "OVERDUE", "UNDER_REVIEW" ], "description": "comply.compliance_status.overall_status (db 12 §1)." }, "ObligationType": { "type": "string", "enum": [ "EPFO", "ESIC", "PT", "TDS", "WPS", "GOSI", "NITAQAT_REVIEW", "IQAMA_RENEWAL", "OTHER" ], "description": "comply.compliance_calendar.obligation_type (db 12 §1)." }, "CalendarFrequency": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "ANNUAL", "EVENT" ], "description": "comply.compliance_calendar.frequency (db 12 §1)." }, "CalendarStatus": { "type": "string", "enum": [ "UPCOMING", "DUE", "PREPARING", "FILED", "OVERDUE", "WAIVED" ], "description": "comply.compliance_calendar.status (db 12 §1)." }, "AlertType": { "type": "string", "enum": [ "REMINDER", "DUE_SOON", "OVERDUE", "ESCALATION" ], "description": "comply.compliance_alerts.alert_type (db 12 §1)." }, "AlertTier": { "type": "string", "enum": [ "INFO", "WARNING", "CRITICAL" ], "description": "comply.compliance_alerts.tier (db 12 §1)." }, "AlertChannel": { "type": "string", "enum": [ "IN_APP", "EMAIL", "SMS", "PUSH" ], "description": "comply.compliance_alerts.channel (db 12 §1, XC-F05)." }, "ComplianceAlertStatus": { "type": "string", "enum": [ "PENDING", "SENT", "ACKNOWLEDGED", "SUPPRESSED" ], "description": "comply.compliance_alerts.status (db 12 §1)." }, "Statute": { "type": "string", "enum": [ "EPFO", "ESIC", "PT", "TDS", "WPS", "GOSI" ], "description": "comply.statutory_filings.statute (db 12 §2/§3)." }, "IndiaStatute": { "type": "string", "enum": [ "EPFO", "ESIC", "PT", "TDS" ], "description": "comply.challan_history.statute — India deposit statutes only (db 12 §2)." }, "FilingStatus": { "type": "string", "enum": [ "SUBMITTED", "ACKNOWLEDGED", "ACCEPTED", "REJECTED", "REVISED" ], "description": "comply.statutory_filings.status (db 12 §2)." }, "ChallanStatus": { "type": "string", "enum": [ "GENERATED", "PAID", "RECONCILED", "FAILED" ], "description": "comply.challan_history.status (db 12 §2)." }, "ChallanSource": { "type": "string", "enum": [ "PORTAL_SYNC", "MANUAL" ], "description": "comply.challan_history.source (db 12 §2, gap 2)." }, "TdsFormType": { "type": "string", "enum": [ "FORM_24Q", "FORM_26Q" ], "description": "comply.tds_filings.form_type (db 12 §2)." }, "TdsQuarter": { "type": "string", "enum": [ "Q1", "Q2", "Q3", "Q4" ], "description": "comply.tds_filings.quarter (db 12 §2)." }, "MudadMovementStatus": { "type": "string", "enum": [ "QUEUED", "SUBMITTED", "CONFIRMED", "RETURNED", "FAILED" ], "description": "comply.mudad_records.movement_status (db 12 §3)." }, "NitaqatBand": { "type": "string", "enum": [ "RED", "GREEN", "PLATINUM" ], "description": "comply.nitaqat_status.band / comply.saudization_ratios.band_at (db 12 §4). GREEN sub-bands (Low/Mid/High) are a pack-driven display classification over the ratio, not distinct stored enum values (db 12 §4 Enum semantics) — ⚠ flagged for KSA-SME confirmation (fsd 11 §3.2).\n" }, "SizeBand": { "type": "string", "enum": [ "MICRO", "SMALL", "MEDIUM", "LARGE", "GIANT" ], "description": "comply.nitaqat_status.size_band (db 12 §4)." }, "IqamaStatus": { "type": "string", "enum": [ "VALID", "EXPIRING", "EXPIRED", "UNDER_RENEWAL", "CANCELLED" ], "description": "comply.iqama_records.status (db 12 §4)." }, "ExpiryDocumentType": { "type": "string", "enum": [ "IQAMA", "PASSPORT", "VISA", "WORK_PERMIT", "GOSI_CERTIFICATE", "CR_LICENSE", "STATUTORY_DOC" ], "description": "comply.expiry_alerts.document_type (db 12 §4)." }, "ExpiryTier": { "type": "string", "enum": [ "T_90", "T_60", "T_30", "T_7", "EXPIRED" ], "description": "comply.expiry_alerts.tier (db 12 §4)." }, "ExpirySeverity": { "type": "string", "enum": [ "INFO", "WARNING", "CRITICAL" ], "description": "comply.expiry_alerts.severity (db 12 §4)." }, "ExpiryAlertStatus": { "type": "string", "enum": [ "OPEN", "NOTIFIED", "ACKNOWLEDGED", "RESOLVED", "SUPPRESSED" ], "description": "comply.expiry_alerts.status (db 12 §4)." }, "ActionNote": { "type": "object", "description": "Generic optional-note body shared by state-transition/acknowledge actions in this file.", "additionalProperties": false, "properties": { "note": { "type": "string" } } }, "StatuteRollupEntry": { "type": "object", "readOnly": true, "description": "One entry of `compliance_status.statute_rollup` (db 12 §1 JSONB payload shape).", "properties": { "statute": { "type": "string" }, "status": { "type": "string" }, "open": { "type": "integer" }, "overdue": { "type": "integer" }, "last_filed_period": { "type": [ "string", "null" ] }, "next_due": { "anyOf": [ { "$ref": "#/components/schemas/DateOnlyRef" }, { "type": "null" } ] } } }, "ComplianceStatus": { "description": "comply.compliance_status — rolling compliance standing for a legal entity/fiscal year; event-built projection, not evidence (db 12 §1).", "allOf": [ { "type": "object", "required": [ "id", "legal_entity_id", "market", "fiscal_year", "overall_status", "open_obligations_count", "overdue_count", "at_risk_count", "last_computed_at" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "legal_entity_id": { "$ref": "#/components/schemas/UuidRef" }, "market": { "$ref": "#/components/schemas/MarketCode" }, "fiscal_year": { "type": "integer" }, "overall_status": { "$ref": "#/components/schemas/OverallStatus" }, "open_obligations_count": { "type": "integer", "minimum": 0 }, "overdue_count": { "type": "integer", "minimum": 0 }, "at_risk_count": { "type": "integer", "minimum": 0 }, "next_due_date": { "anyOf": [ { "$ref": "#/components/schemas/DateOnlyRef" }, { "type": "null" } ] }, "statute_rollup": { "type": "array", "items": { "$ref": "#/components/schemas/StatuteRollupEntry" } }, "compliance_pack_version": { "type": [ "integer", "null" ] }, "last_computed_at": { "$ref": "#/components/schemas/TimestampRef" } } }, { "$ref": "#/components/schemas/AuditMetaRef" } ] }, "ComplianceStatusPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ComplianceStatus" } } } } ] }, "SyncPortalsRequest": { "type": "object", "required": [ "legal_entity_id" ], "additionalProperties": false, "properties": { "legal_entity_id": { "$ref": "#/components/schemas/UuidRef" } } }, "SyncPortalsAccepted": { "type": "object", "readOnly": true, "description": "Acceptance envelope for the async portal-sync job.", "required": [ "legal_entity_id", "status" ], "properties": { "legal_entity_id": { "$ref": "#/components/schemas/UuidRef" }, "status": { "type": "string", "enum": [ "ACCEPTED" ] } } }, "ComplianceCalendarItem": { "description": "comply.compliance_calendar — one statutory due-date obligation on the unified timeline (db 12 §1).", "allOf": [ { "type": "object", "required": [ "id", "legal_entity_id", "market", "obligation_type", "title", "period", "frequency", "due_date", "status" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "legal_entity_id": { "$ref": "#/components/schemas/UuidRef" }, "market": { "$ref": "#/components/schemas/MarketCode" }, "obligation_type": { "$ref": "#/components/schemas/ObligationType" }, "title": { "type": "string" }, "period": { "type": "string" }, "frequency": { "$ref": "#/components/schemas/CalendarFrequency" }, "due_date": { "$ref": "#/components/schemas/DateOnlyRef" }, "due_date_hijri": { "anyOf": [ { "$ref": "#/components/schemas/HijriDisplayRef" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/CalendarStatus" }, "satisfied_by_filing_id": { "anyOf": [ { "$ref": "#/components/schemas/UuidRef" }, { "type": "null" } ] }, "compliance_pack_version": { "type": [ "integer", "null" ] }, "filed_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] } } }, { "$ref": "#/components/schemas/AuditMetaRef" } ] }, "ComplianceCalendarPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ComplianceCalendarItem" } } } } ] }, "WaiveRequest": { "type": "object", "required": [ "reason" ], "additionalProperties": false, "properties": { "reason": { "type": "string", "description": "Recorded to the `audit` trail (XC-F06) — not a `compliance_calendar` column (db 12 §1 Notes, gap 6)." } } }, "ComplianceAlert": { "description": "comply.compliance_alerts — a reminder/overdue/escalation alert raised against a calendar obligation (db 12 §1).", "allOf": [ { "type": "object", "required": [ "id", "compliance_calendar_id", "alert_type", "tier", "due_date", "status", "scheduled_at" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "compliance_calendar_id": { "$ref": "#/components/schemas/UuidRef" }, "alert_type": { "$ref": "#/components/schemas/AlertType" }, "tier": { "$ref": "#/components/schemas/AlertTier" }, "due_date": { "$ref": "#/components/schemas/DateOnlyRef" }, "channel": { "anyOf": [ { "$ref": "#/components/schemas/AlertChannel" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ComplianceAlertStatus" }, "scheduled_at": { "$ref": "#/components/schemas/TimestampRef" }, "sent_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] }, "acknowledged_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] }, "acknowledged_by": { "anyOf": [ { "$ref": "#/components/schemas/UuidRef" }, { "type": "null" } ] } } }, { "$ref": "#/components/schemas/AuditMetaRef" } ] }, "ComplianceAlertPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ComplianceAlert" } } } } ] }, "ExpiryAlert": { "description": "comply.expiry_alerts — a tiered document-expiry warning (Iqama/passport/visa/…) (db 12 §4).", "allOf": [ { "type": "object", "required": [ "id", "document_type", "expiry_date", "tier", "severity", "status" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "iqama_record_id": { "anyOf": [ { "$ref": "#/components/schemas/UuidRef" }, { "type": "null" } ] }, "employee_id": { "anyOf": [ { "$ref": "#/components/schemas/UuidRef" }, { "type": "null" } ] }, "document_type": { "$ref": "#/components/schemas/ExpiryDocumentType" }, "expiry_date": { "$ref": "#/components/schemas/DateOnlyRef" }, "expiry_date_hijri": { "anyOf": [ { "$ref": "#/components/schemas/HijriDisplayRef" }, { "type": "null" } ] }, "tier": { "$ref": "#/components/schemas/ExpiryTier" }, "severity": { "$ref": "#/components/schemas/ExpirySeverity" }, "status": { "$ref": "#/components/schemas/ExpiryAlertStatus" }, "notified_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] }, "acknowledged_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] }, "acknowledged_by": { "anyOf": [ { "$ref": "#/components/schemas/UuidRef" }, { "type": "null" } ] }, "resolved_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] } } }, { "$ref": "#/components/schemas/AuditMetaRef" } ] }, "ExpiryAlertPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExpiryAlert" } } } } ] }, "IqamaRecord": { "description": "comply.iqama_records — an employee's Iqama (residency permit) monitoring record; comply's projection of the people master (db 12 §4).", "allOf": [ { "type": "object", "required": [ "id", "employee_id", "iqama_no", "expiry_date", "status" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "employee_id": { "$ref": "#/components/schemas/UuidRef" }, "iqama_no": { "type": "string" }, "profession": { "type": [ "string", "null" ] }, "sponsor_id": { "type": [ "string", "null" ] }, "border_no": { "type": [ "string", "null" ] }, "issue_date": { "anyOf": [ { "$ref": "#/components/schemas/DateOnlyRef" }, { "type": "null" } ] }, "expiry_date": { "$ref": "#/components/schemas/DateOnlyRef" }, "expiry_date_hijri": { "anyOf": [ { "$ref": "#/components/schemas/HijriDisplayRef" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/IqamaStatus" }, "last_renewed_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] } } }, { "$ref": "#/components/schemas/AuditMetaRef" } ] }, "IqamaRecordDetail": { "allOf": [ { "$ref": "#/components/schemas/IqamaRecord" }, { "type": "object", "properties": { "expiry_alerts": { "type": "array", "items": { "$ref": "#/components/schemas/ExpiryAlert" } } } } ] }, "IqamaRecordPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IqamaRecord" } } } } ] }, "RecordRenewalRequest": { "type": "object", "additionalProperties": false, "properties": { "renewed_iqama_no": { "type": "string", "description": "Optional new Iqama number if reissued on renewal." }, "new_expiry_date": { "$ref": "#/components/schemas/DateOnlyRef" } } }, "FilingWorksheet": { "description": "`comply.filing_worksheets` — the payroll tier's computed statutory position for a period, before anything is lodged (migration `0174`, #95). Mutable and re-derivable from its payroll run; NOT regulatory evidence — that is `StatutoryFiling`.\n", "allOf": [ { "type": "object", "required": [ "id", "legal_entity_id", "market", "statute", "period", "payroll_run_id", "total_amount", "currency_code", "headcount", "compliance_pack_version", "generated_at" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "legal_entity_id": { "$ref": "#/components/schemas/UuidRef" }, "market": { "$ref": "#/components/schemas/MarketCode" }, "statute": { "$ref": "#/components/schemas/Statute" }, "period": { "type": "string", "description": "Pack period mask — `YYYY-MM` (EPFO/ESIC/PT) or `YYYY-Qn` (TDS)." }, "state_code": { "type": [ "string", "null" ], "description": "Set for PT ONLY — its lineage is per state, so one PT period yields one worksheet per state (db 12 §2, `04-spec-cmp-s02` §3). `null` for every other statute, enforced by a CHECK.\n" }, "payroll_run_id": { "allOf": [ { "$ref": "#/components/schemas/UuidRef" } ], "description": "`ref→pay.payroll_runs` — NOT NULL. The provenance link `CMP-S02` §4.2's \"View source run →\" uses; a worksheet with no source run is the untraceable figure that rule exists to forbid.\n" }, "total_amount": { "$ref": "#/components/schemas/MoneyRef" }, "currency_code": { "type": "string", "description": "`INR` — every worksheet producer is an India statute today." }, "headcount": { "type": "integer", "minimum": 0 }, "storage_key": { "type": [ "string", "null" ], "description": "The generated artifact (EPFO ECR / ESIC return). PT carries none — its submit takes no artifact fields." }, "content_hash": { "type": [ "string", "null" ], "description": "SHA-256 of the artifact; present whenever `storage_key` is (CHECK constraint)." }, "compliance_pack_version": { "type": "integer" }, "generated_at": { "$ref": "#/components/schemas/TimestampRef" } } }, { "$ref": "#/components/schemas/AuditMetaRef" } ] }, "FilingWorksheetPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FilingWorksheet" } } } } ] }, "StatutoryFiling": { "description": "comply.statutory_filings — the append-only parent filing record, shared by both markets (db 12 §2/§3).", "allOf": [ { "type": "object", "required": [ "id", "filing_no", "legal_entity_id", "statute", "market", "period", "total_amount", "headcount", "status", "filed_at" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "filing_no": { "$ref": "#/components/schemas/BusinessNoRef" }, "legal_entity_id": { "$ref": "#/components/schemas/UuidRef" }, "statute": { "$ref": "#/components/schemas/Statute" }, "market": { "$ref": "#/components/schemas/MarketCode" }, "period": { "type": "string" }, "payroll_run_id": { "anyOf": [ { "$ref": "#/components/schemas/UuidRef" }, { "type": "null" } ] }, "total_amount": { "$ref": "#/components/schemas/MoneyRef" }, "headcount": { "type": "integer", "minimum": 0 }, "status": { "$ref": "#/components/schemas/FilingStatus" }, "acknowledgement_ref": { "type": [ "string", "null" ] }, "submitted_by": { "anyOf": [ { "$ref": "#/components/schemas/UuidRef" }, { "type": "null" } ] }, "compliance_pack_version": { "type": "integer" }, "content_hash": { "type": [ "string", "null" ], "description": "SHA-256 of the stored artifact; bytes available via `comply.statutory_filing.download_artifact` (00 §14)." }, "filed_at": { "$ref": "#/components/schemas/TimestampRef" } } }, { "$ref": "#/components/schemas/AppendOnlyMetaRef" } ] }, "StatutoryFilingPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StatutoryFiling" } } } } ] }, "StatutoryFilingLineageEntry": { "type": "object", "readOnly": true, "description": "A sibling row sharing `(legal_entity_id, statute, period)` — the compensating-row lineage (db 12 §2 Notes).", "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "filing_no": { "$ref": "#/components/schemas/BusinessNoRef" }, "status": { "$ref": "#/components/schemas/FilingStatus" }, "filed_at": { "$ref": "#/components/schemas/TimestampRef" } } }, "EpfoFilingDetail": { "type": "object", "readOnly": true, "description": "comply.epfo_filings child detail (India-only, db 12 §2).", "properties": { "establishment_code": { "type": "string" }, "wage_month": { "type": "string" }, "member_count": { "type": "integer" }, "total_wages_amount": { "$ref": "#/components/schemas/MoneyRef" }, "employee_epf_amount": { "$ref": "#/components/schemas/MoneyRef" }, "employer_epf_amount": { "$ref": "#/components/schemas/MoneyRef" }, "employer_eps_amount": { "$ref": "#/components/schemas/MoneyRef" }, "edli_amount": { "$ref": "#/components/schemas/MoneyRef" }, "trrn": { "type": [ "string", "null" ] } } }, "EsicFilingDetail": { "type": "object", "readOnly": true, "description": "comply.esic_filings child detail (India-only, db 12 §2).", "properties": { "establishment_code": { "type": "string" }, "contribution_period": { "type": "string" }, "insured_person_count": { "type": "integer" }, "total_wages_amount": { "$ref": "#/components/schemas/MoneyRef" }, "employee_contribution_amount": { "$ref": "#/components/schemas/MoneyRef" }, "employer_contribution_amount": { "$ref": "#/components/schemas/MoneyRef" }, "challan_ref": { "type": [ "string", "null" ] } } }, "PtFilingStateEntry": { "type": "object", "readOnly": true, "description": "One per-state PT child row under a multi-state filing parent (db 12 §2).", "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "state_code": { "type": "string" }, "pt_registration_no": { "type": [ "string", "null" ] }, "pt_period": { "type": "string" }, "employee_count": { "type": "integer" }, "total_pt_amount": { "$ref": "#/components/schemas/MoneyRef" }, "challan_ref": { "type": [ "string", "null" ] } } }, "PtFilingDetail": { "type": "object", "readOnly": true, "description": "comply.pt_filings — 1:N per-state child detail (India-only, state-divergent, db 12 §2).", "properties": { "states": { "type": "array", "items": { "$ref": "#/components/schemas/PtFilingStateEntry" } } } }, "TdsFilingDetail": { "type": "object", "readOnly": true, "description": "comply.tds_filings child detail (India-only, db 12 §2).", "properties": { "tan": { "type": "string" }, "form_type": { "$ref": "#/components/schemas/TdsFormType" }, "fiscal_year": { "type": "integer" }, "quarter": { "$ref": "#/components/schemas/TdsQuarter" }, "deductee_count": { "type": "integer" }, "total_tds_amount": { "$ref": "#/components/schemas/MoneyRef" }, "traces_token": { "type": [ "string", "null" ] } } }, "WpsFilingDetail": { "type": "object", "readOnly": true, "description": "comply.wps_filings child detail (KSA-only, db 12 §3).", "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "mol_establishment_no": { "type": "string" }, "wage_month": { "type": "string" }, "wage_month_hijri": { "anyOf": [ { "$ref": "#/components/schemas/HijriDisplayRef" }, { "type": "null" } ] }, "employee_count": { "type": "integer" }, "total_wages_amount": { "$ref": "#/components/schemas/MoneyRef" }, "mudad_reference": { "type": [ "string", "null" ] }, "mol_match_pct": { "anyOf": [ { "$ref": "#/components/schemas/RateRef" }, { "type": "null" } ] } } }, "GosiFilingDetail": { "type": "object", "readOnly": true, "description": "comply.gosi_filings child detail (KSA-only, db 12 §3).", "properties": { "gosi_establishment_no": { "type": "string" }, "contribution_month": { "type": "string" }, "contribution_month_hijri": { "anyOf": [ { "$ref": "#/components/schemas/HijriDisplayRef" }, { "type": "null" } ] }, "saudi_employee_count": { "type": "integer" }, "non_saudi_employee_count": { "type": "integer" }, "total_wages_amount": { "$ref": "#/components/schemas/MoneyRef" }, "employee_contribution_amount": { "$ref": "#/components/schemas/MoneyRef" }, "employer_contribution_amount": { "$ref": "#/components/schemas/MoneyRef" }, "total_contribution_amount": { "$ref": "#/components/schemas/MoneyRef" }, "gosi_reference": { "type": [ "string", "null" ] } } }, "StatutoryFilingDetail": { "allOf": [ { "$ref": "#/components/schemas/StatutoryFiling" }, { "type": "object", "properties": { "detail": { "description": "Exactly one branch is populated, matching `statute`.", "oneOf": [ { "$ref": "#/components/schemas/EpfoFilingDetail" }, { "$ref": "#/components/schemas/EsicFilingDetail" }, { "$ref": "#/components/schemas/PtFilingDetail" }, { "$ref": "#/components/schemas/TdsFilingDetail" }, { "$ref": "#/components/schemas/WpsFilingDetail" }, { "$ref": "#/components/schemas/GosiFilingDetail" } ] }, "lineage": { "type": "array", "items": { "$ref": "#/components/schemas/StatutoryFilingLineageEntry" } } } } ] }, "AcknowledgementRequest": { "type": "object", "required": [ "acknowledgement_ref" ], "additionalProperties": false, "properties": { "acknowledgement_ref": { "type": "string" }, "status": { "type": "string", "enum": [ "ACKNOWLEDGED", "ACCEPTED" ], "default": "ACKNOWLEDGED" } } }, "RejectionRequest": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "description": "Recorded to the `audit` trail (XC-F06) — statutory_filings carries no rejection-reason column." } } }, "FilingSubmitAccepted": { "type": "object", "readOnly": true, "description": "Acceptance envelope for an async per-statute filing submission (maker/checker via XC-F12, jobs tier XC-F08).", "required": [ "legal_entity_id", "statute", "period", "status" ], "properties": { "legal_entity_id": { "$ref": "#/components/schemas/UuidRef" }, "statute": { "$ref": "#/components/schemas/Statute" }, "period": { "type": "string" }, "status": { "type": "string", "enum": [ "ACCEPTED" ] } } }, "EpfoFilingSubmit": { "type": "object", "required": [ "legal_entity_id", "payroll_run_id", "wage_month", "establishment_code", "member_count" ], "additionalProperties": false, "properties": { "legal_entity_id": { "$ref": "#/components/schemas/UuidRef" }, "payroll_run_id": { "$ref": "#/components/schemas/UuidRef" }, "wage_month": { "type": "string" }, "establishment_code": { "type": "string" }, "member_count": { "type": "integer", "minimum": 0 }, "revises_filing_id": { "$ref": "#/components/schemas/UuidRef", "description": "Set to file a compensating REVISED return over the filing that CURRENTLY stands for this (legal entity, statute, period) lineage. A superseded target is a 409." }, "ecr_storage_key": { "type": "string", "description": "Storage key of the generated ECR — from the period's filing worksheet, never typed by a maker. Server-corroborated against that worksheet; a mismatch is a 422." }, "ecr_hash": { "type": "string", "description": "SHA-256 of the ECR bytes. Required whenever `ecr_storage_key` is present (`statutory_filings_content_hash_when_key`), and corroborated against the period's worksheet." } } }, "EsicFilingSubmit": { "type": "object", "required": [ "legal_entity_id", "payroll_run_id", "contribution_period", "establishment_code", "insured_person_count" ], "additionalProperties": false, "properties": { "legal_entity_id": { "$ref": "#/components/schemas/UuidRef" }, "payroll_run_id": { "$ref": "#/components/schemas/UuidRef" }, "contribution_period": { "type": "string" }, "establishment_code": { "type": "string" }, "insured_person_count": { "type": "integer", "minimum": 0 }, "revises_filing_id": { "$ref": "#/components/schemas/UuidRef" }, "monthly_contribution_storage_key": { "type": "string", "description": "Storage key of the generated ESI monthly-contribution return, from the period's filing worksheet." }, "monthly_contribution_hash": { "type": "string", "description": "SHA-256 of those bytes. Required whenever the storage key is present." } } }, "PtFilingStateInput": { "type": "object", "required": [ "state_code", "employee_count" ], "additionalProperties": false, "properties": { "state_code": { "type": "string" }, "pt_registration_no": { "type": "string" }, "employee_count": { "type": "integer", "minimum": 0 } } }, "PtFilingSubmit": { "type": "object", "required": [ "legal_entity_id", "payroll_run_id", "pt_period", "states" ], "additionalProperties": false, "properties": { "legal_entity_id": { "$ref": "#/components/schemas/UuidRef" }, "payroll_run_id": { "$ref": "#/components/schemas/UuidRef" }, "pt_period": { "type": "string" }, "states": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/PtFilingStateInput" } }, "revises_filing_id": { "$ref": "#/components/schemas/UuidRef" } } }, "TdsFilingSubmit": { "type": "object", "required": [ "legal_entity_id", "payroll_run_id", "fiscal_year", "quarter", "tan" ], "additionalProperties": false, "properties": { "legal_entity_id": { "$ref": "#/components/schemas/UuidRef" }, "payroll_run_id": { "$ref": "#/components/schemas/UuidRef" }, "fiscal_year": { "type": "integer" }, "quarter": { "$ref": "#/components/schemas/TdsQuarter" }, "tan": { "type": "string" }, "form_type": { "$ref": "#/components/schemas/TdsFormType", "default": "FORM_24Q" }, "revises_filing_id": { "$ref": "#/components/schemas/UuidRef" } } }, "WpsFilingSubmit": { "type": "object", "required": [ "legal_entity_id", "payroll_run_id", "wage_month", "mol_establishment_no" ], "additionalProperties": false, "properties": { "legal_entity_id": { "$ref": "#/components/schemas/UuidRef" }, "payroll_run_id": { "$ref": "#/components/schemas/UuidRef", "description": "The reviewed run the SIF was computed from. `total_amount` (net wages disbursed) and `headcount` are derived from it; the file's storage key and digest come from that period's `comply.filing_worksheets` row." }, "wage_month": { "type": "string" }, "mol_establishment_no": { "type": "string" }, "employee_count": { "type": "integer", "minimum": 0, "description": "The maker's attestation of what the Review step showed. The persisted headcount is derived from the run." }, "wps_format": { "type": "string", "enum": [ "SIF_V3", "SIF_V4" ], "default": "SIF_V3" }, "file_reference": { "type": "string" }, "value_date": { "type": "string", "format": "date" }, "wage_month_hijri": { "type": "string", "description": "Umm al-Qura render of `wage_month` — display only; the Gregorian value is the canonical one (db 12 §Hijri)." }, "revises_filing_id": { "$ref": "#/components/schemas/UuidRef", "description": "Set to file a compensating REVISED return over the filing that CURRENTLY stands for this (legal entity, statute, period) lineage. A superseded target is a 409." } } }, "GosiFilingSubmit": { "type": "object", "required": [ "legal_entity_id", "payroll_run_id", "contribution_month", "gosi_establishment_no", "saudi_employee_count", "non_saudi_employee_count" ], "additionalProperties": false, "properties": { "legal_entity_id": { "$ref": "#/components/schemas/UuidRef" }, "payroll_run_id": { "$ref": "#/components/schemas/UuidRef", "description": "The reviewed run the contributions are derived from (`pay.deductions` `GOSI` lines). Required since #1250; a run carrying no GOSI line is a 422, never a 0.00 return." }, "contribution_month": { "type": "string" }, "gosi_establishment_no": { "type": "string" }, "saudi_employee_count": { "type": "integer", "minimum": 0, "description": "Maker-attested and persisted as sent — the Saudi/non-Saudi split is not derivable from this model." }, "non_saudi_employee_count": { "type": "integer", "minimum": 0, "description": "Maker-attested and persisted as sent — see `saudi_employee_count`." }, "contribution_month_hijri": { "type": "string", "description": "Umm al-Qura render of `contribution_month` — display only." }, "revises_filing_id": { "$ref": "#/components/schemas/UuidRef", "description": "Set to file a compensating REVISED return over the filing that CURRENTLY stands. A superseded target is a 409." } } }, "ChallanRecord": { "description": "comply.challan_history — one immutable India statutory deposit (db 12 §2).", "allOf": [ { "type": "object", "required": [ "id", "statutory_filing_id", "legal_entity_id", "period", "statute", "challan_no", "amount", "payment_date", "status", "source", "paid_at" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "statutory_filing_id": { "$ref": "#/components/schemas/UuidRef" }, "legal_entity_id": { "allOf": [ { "$ref": "#/components/schemas/UuidRef" } ], "readOnly": true, "description": "Projected read-only from the parent `comply.statutory_filings` row — `challan_history` has no `legal_entity_id` column of its own (db 12 §2). Without it `CMP-S04` cannot say which entity a deposit belongs to (issue #95)." }, "period": { "type": "string", "readOnly": true, "description": "Projected read-only from the parent filing's `period` — `challan_history` has no period column. Reconciling a deposit against its filing is this screen's job (spec `CMP-S04` §5), and it needs the period the deposit satisfies." }, "statute": { "$ref": "#/components/schemas/IndiaStatute" }, "challan_no": { "type": "string" }, "amount": { "$ref": "#/components/schemas/MoneyRef" }, "payment_date": { "$ref": "#/components/schemas/DateOnlyRef" }, "bank_ref": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ChallanStatus" }, "source": { "$ref": "#/components/schemas/ChallanSource" }, "content_hash": { "type": [ "string", "null" ], "description": "SHA-256 of the receipt; bytes via `comply.challan.download_receipt` (00 §14)." }, "paid_at": { "$ref": "#/components/schemas/TimestampRef" } } }, { "$ref": "#/components/schemas/AppendOnlyMetaRef" } ] }, "ChallanPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChallanRecord" } } } } ] }, "ChallanUploadRequest": { "type": "object", "required": [ "statutory_filing_id", "statute", "challan_no", "amount", "payment_date" ], "additionalProperties": false, "properties": { "statutory_filing_id": { "$ref": "#/components/schemas/UuidRef" }, "statute": { "$ref": "#/components/schemas/IndiaStatute" }, "challan_no": { "type": "string" }, "amount": { "$ref": "#/components/schemas/MoneyRef" }, "payment_date": { "$ref": "#/components/schemas/DateOnlyRef" }, "bank_ref": { "type": "string" }, "receipt_file_id": { "$ref": "#/components/schemas/UuidRef", "description": "Handle of a receipt previously uploaded via the files API (00 §14); bytes never transit this endpoint." } } }, "MudadRecord": { "description": "comply.mudad_records — SAR salary-disbursement tracking for a WPS filing, executed through the xc interpay adapter (ADR 0013, db 12 §3). Read-only here. `AuditMeta` carries `created_at`/`updated_at` only: the table has no `created_by`/`updated_by`, `deleted_at` or `version` (migration 0024), and every property of `AuditMeta` is optional, so the omission is conformant. Until #1250 the server claimed all six and consequently failed with `42703` on every read and write of this entity.", "allOf": [ { "type": "object", "required": [ "id", "wps_filing_id", "amount", "employee_count", "movement_status" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "wps_filing_id": { "$ref": "#/components/schemas/UuidRef" }, "bank_code": { "type": [ "string", "null" ] }, "batch_ref": { "type": [ "string", "null" ] }, "interpay_ref": { "type": [ "string", "null" ] }, "amount": { "$ref": "#/components/schemas/MoneyRef" }, "employee_count": { "type": "integer", "minimum": 0 }, "movement_status": { "$ref": "#/components/schemas/MudadMovementStatus" }, "submitted_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] }, "confirmed_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] } } }, { "$ref": "#/components/schemas/AuditMetaRef" } ] }, "MudadRecordPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MudadRecord" } } } } ] }, "NitaqatStatus": { "description": "comply.nitaqat_status — the legal entity's current Nitaqat band; mutable projection recomputed by the jobs tier (db 12 §4).", "allOf": [ { "type": "object", "required": [ "id", "legal_entity_id", "size_band", "band", "current_ratio", "total_workforce_count", "saudi_headcount", "computed_at" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "legal_entity_id": { "$ref": "#/components/schemas/UuidRef" }, "mol_establishment_no": { "type": [ "string", "null" ] }, "activity_sector": { "type": [ "string", "null" ] }, "size_band": { "$ref": "#/components/schemas/SizeBand" }, "band": { "$ref": "#/components/schemas/NitaqatBand" }, "current_ratio": { "$ref": "#/components/schemas/RateRef" }, "required_ratio": { "anyOf": [ { "$ref": "#/components/schemas/RateRef" }, { "type": "null" } ] }, "total_workforce_count": { "type": "integer", "minimum": 0 }, "saudi_headcount": { "type": "integer", "minimum": 0 }, "distance_to_next_band": { "anyOf": [ { "$ref": "#/components/schemas/RateRef" }, { "type": "null" } ] }, "compliance_pack_version": { "type": [ "integer", "null" ] }, "computed_at": { "$ref": "#/components/schemas/TimestampRef" } } }, { "$ref": "#/components/schemas/AuditMetaRef" } ] }, "NitaqatStatusPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NitaqatStatus" } } } } ] }, "SaudizationRatio": { "type": "object", "readOnly": true, "description": "comply.saudization_ratios — a point-in-time ratio under a Nitaqat status; the band-transition history (db 12 §4).", "required": [ "id", "nitaqat_status_id", "as_of_date", "saudi_headcount", "total_workforce_count", "ratio", "band_at", "computed_at" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "nitaqat_status_id": { "$ref": "#/components/schemas/UuidRef" }, "as_of_date": { "$ref": "#/components/schemas/DateOnlyRef" }, "saudi_headcount": { "type": "integer", "minimum": 0 }, "total_workforce_count": { "type": "integer", "minimum": 0 }, "ratio": { "$ref": "#/components/schemas/RateRef" }, "band_at": { "$ref": "#/components/schemas/NitaqatBand" }, "computed_at": { "$ref": "#/components/schemas/TimestampRef" } } }, "SaudizationRatioPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaudizationRatio" } } } } ] }, "Uuid": { "type": "string", "format": "uuid", "description": "UUIDv7 surrogate primary key (db-docs/00 §3). Never the business identifier." }, "DateOnly": { "type": "string", "format": "date", "description": "Calendar-only value (pay-period date, leave date, due date)." }, "Timestamp": { "type": "string", "format": "date-time", "description": "timestamptz, serialized UTC ISO-8601. Presentation timezone is a client concern." }, "Rate": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,6})?$", "description": "numeric(9,6) fraction as a string, e.g. \"0.120000\" for the 12% EPF rate. Never a float; percentages are stored as fractions." }, "Money": { "type": "object", "description": "Exact decimal money (db-docs/00 §6). `amount` is a STRING so float never enters the wire.", "required": [ "amount", "currency_code" ], "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,2})?$", "description": "numeric(18,2) as a string, e.g. \"45000.00\"." }, "currency_code": { "$ref": "#/components/schemas/CurrencyCode" } } }, "BusinessNo": { "type": "string", "description": "Tenant-unique, prefixed human reference (`employee_no`, `requisition_no`, `offer_no`, `payslip_no`, `claim_no`, `ticket_no`, `asset_no`, `case_no`). Read-model field; never a path key.\n" }, "HijriDisplay": { "type": "string", "readOnly": true, "description": "Formatted Umm al-Qura display string (`*_hijri`, db-docs/00 §6) accompanying a canonical Gregorian value on KSA-facing read-models (GOSI/WPS periods, Iqama expiry, KSA payslips). NEVER the source of truth; never accepted as input.\n" }, "AuditMeta": { "type": "object", "description": "Standard mutable-entity columns (db-docs/00 §5). Read-only; present on every mutable read-model.", "readOnly": true, "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "created_by": { "anyOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ], "description": "null = system/jobs" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_by": { "anyOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "deleted_at": { "anyOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ], "description": "soft-delete marker; live rows are null. Deleted rows are excluded by default scope." }, "version": { "type": "integer", "description": "Optimistic-lock counter (where present); surfaces as the ETag." } } }, "AppendOnlyMeta": { "type": "object", "description": "Standard append-only/immutable columns (db-docs/00 §5/§8). No update/version/delete; corrections are new compensating rows.", "readOnly": true, "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "created_by": { "anyOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] } } }, "CursorPage": { "type": "object", "description": "Generic cursor-pagination envelope. List operations compose it via allOf to type `data`, e.g. `allOf: [ {$ref CursorPage}, { properties: { data: { items: {$ref Employee} } } } ]`.\n", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": {} }, "page": { "type": "object", "required": [ "has_more" ], "properties": { "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" }, "total_est": { "type": [ "integer", "null" ], "description": "Optional, capped, APPROXIMATE row estimate for grid \"X of Z\" display only — never an exact COUNT(*) on large tables (attend.attendance_records, xc.notifications, audit.*).\n" } } } } }, "FileDownload": { "type": "object", "description": "Authorized file handle (db-docs/00 §14, xc.files). Bytes never transit the API — the backend mints a time-limited presigned URL after authorization. Clients never see storage keys or hold storage credentials; the presigned URL is never persisted.\n", "required": [ "file_id", "file_name", "url", "expires_at" ], "properties": { "file_id": { "$ref": "#/components/schemas/Uuid" }, "file_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "content_hash": { "type": [ "string", "null" ], "description": "SHA-256", "present where tamper-evidence matters (payslips": null, "letters": null, "e-sign artifacts).": null }, "url": { "type": "string", "format": "uri", "description": "Time-limited presigned URL." }, "expires_at": { "$ref": "#/components/schemas/Timestamp" } } }, "Problem": { "type": "object", "description": "RFC 9457 problem detail (application/problem+json). The platform-wide error envelope (03 §1).", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "format": "uri", "default": "about:blank", "description": "Problem-type URI." }, "title": { "type": "string", "description": "Short, human-readable summary (stable per type)." }, "status": { "type": "integer", "description": "HTTP status code, duplicated for convenience." }, "detail": { "type": "string", "description": "Human-readable explanation specific to this occurrence." }, "instance": { "type": "string", "description": "URI reference for this specific occurrence." }, "code": { "$ref": "#/components/schemas/ErrorCode" }, "correlation_id": { "$ref": "#/components/schemas/Uuid" } } }, "ValidationProblem": { "description": "422 field-level validation failure; extends Problem with a per-field error array. `detail` is ALWAYS present on a 422 (#1251) and is the human summary of `errors[]`: one offending field renders as `\": \"` (`withholding_amount: is required for an India entity`), several as `\"N fields were refused: a, b, c.\"`, capped at five names. It is display copy derived from members already in the same body — clients keep branching on `code` and mapping `errors[].pointer` back to a control, never parsing this sentence.\n", "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "type": "object", "required": [ "detail", "errors" ], "properties": { "detail": { "type": "string", "description": "Human summary of `errors[]`, always populated on a 422 so a client never has to fall back to generic copy for the one status that names a fixable field.\n", "example": "withholding_amount: is required for an India entity" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "pointer", "rule" ], "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the offending field, e.g. /claim_amount" }, "rule": { "type": "string", "enum": [ "required", "format", "length", "range", "cross-field", "async-server", "consent-gated", "uniqueness-business", "not_found" ], "description": "FSD validation taxonomy rule (fsd-docs/00 §8.2). `not_found` is the server-side-lookup arm: a body field that REFERENCES another resource (e.g. `project_id` on a work entry) and did not resolve for this caller. It is reported here, under the field's pointer, and NOT as a 404 — the request addresses its own resource, so the failure belongs on the form field the client can actually fix (#805).\n" }, "message": { "type": "string" } } } } } } ] }, "CurrencyCode": { "type": "string", "enum": [ "INR", "SAR" ], "description": "ISO-4217. A legal entity operates in a single currency (db-docs/00 §6)." }, "ErrorCode": { "type": "string", "description": "Machine-stable error code (paired with the HTTP status; drives client handling, not display copy).", "enum": [ "VALIDATION_FAILED", "IDEMPOTENCY_KEY_REUSE", "VERSION_CONFLICT", "PRECONDITION_REQUIRED", "MAKER_EQUALS_CHECKER", "STEP_UP_REQUIRED", "CONSENT_REQUIRED", "TOKEN_DENIED", "SCOPE_DENIED", "OWNERSHIP_DENIED", "STATE_TRANSITION_INVALID", "FACE_MISMATCH", "FACE_VERIFICATION_REQUIRED", "WITHHOLDING_REVIEW_REQUIRED", "FEATURE_NOT_IN_PLAN", "PLAN_LIMIT_EXCEEDED", "TENANT_PAST_DUE", "TENANT_SUSPENDED", "TENANT_CANCELLED", "RATE_LIMITED", "NOT_FOUND" ] } }, "parameters": { "PathId": { "name": "id", "in": "path", "required": true, "description": "UUIDv7 surrogate key of the target resource. Business numbers (`employee_no`, `claim_no`, …) are read-model fields, never path keys.", "schema": { "$ref": "#/components/schemas/Uuid" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated unique key. REQUIRED on every mutation (this round tightens ADR 0015's \"platform + retryable mutations\" floor to ALL mutations for uniformity — offline punch/leave sync depends on it). Scoped (tenant, principal, route, key); a replay within the ~24h window returns the stored response with `Idempotency-Replayed: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSE (04 §1).\n", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, "IfMatch": { "name": "If-Match", "in": "header", "required": true, "description": "Optimistic-concurrency precondition for mutating a VERSIONED mutable entity (db-docs/00 §5 applies `version` where concurrent edits are likely). Value is the entity's current ETag (the row `version`). Absent → 428; stale → 412 (04 §2). N/A for append-only entities and for unversioned low-contention entities (their update ops simply omit this parameter).\n", "schema": { "type": "string" } } }, "responses": { "Unauthorized": { "description": "Missing, expired, or invalid session token (no authenticated principal).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Forbidden": { "description": "Authenticated but denied — permission token not granted, out of scope (self/team/branch), not the owner, tenant suspended, or an MC-2 operation without a fresh step-up challenge. `code` ∈ TOKEN_DENIED | SCOPE_DENIED | OWNERSHIP_DENIED | MAKER_EQUALS_CHECKER | STEP_UP_REQUIRED | CONSENT_REQUIRED | TENANT_SUSPENDED. A plan feature-flag being off is 402 FEATURE_NOT_IN_PLAN, not 403 (see PaymentRequired).\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "Resource does not exist OR is masked by RLS (tenant/self/team/branch scope) — the API does not distinguish, so existence is never confirmed across a scope boundary (02 §4 disclosure posture).\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Conflict": { "description": "Idempotency-key reuse with a different body, an invalid state transition, or a uniqueness/business-rule violation (fsd 00 §8.2). For database-backed uniqueness rules, detail names the exact violated rule; unmapped constraints are not collapsed into a generic 409.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "UnprocessableEntity": { "description": "Field-level validation failed. The body carries both `errors[]` (per-field, pointer-addressed) and a `detail` summarising them — never an empty `detail` (#1251).\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" }, "examples": { "singleField": { "summary": "One refused field — `detail` names it", "value": { "type": "about:blank", "title": "Unprocessable Entity", "status": 422, "code": "VALIDATION_FAILED", "detail": "withholding_amount: is required for an India entity", "errors": [ { "pointer": "/withholding_amount", "rule": "required", "message": "is required for an India entity" } ] } }, "severalFields": { "summary": "Several refused fields — `detail` counts and names them", "value": { "type": "about:blank", "title": "Unprocessable Entity", "status": 422, "code": "VALIDATION_FAILED", "detail": "2 fields were refused: effective_from, cap_amount.amount.", "errors": [ { "pointer": "/effective_from", "rule": "cross-field", "message": "Overlaps an existing version." }, { "pointer": "/cap_amount/amount", "rule": "range", "message": "Must be a non-negative decimal string." } ] } } } } } }, "Locked": { "description": "Tenant subscription `past_due` (ADR 0009): WRITES are blocked (423), reads still succeed. `code` = TENANT_PAST_DUE. Mutations return this; list/get operations do not.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "TooManyRequests": { "description": "Per-principal/route rate limit exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PreconditionRequired": { "description": "If-Match header absent on a mutation of a versioned mutable entity (428).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PreconditionFailed": { "description": "If-Match / ETag mismatch — the row changed since it was read (412, VERSION_CONFLICT).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "headers": { "ETag": { "description": "Strong validator of the row `version` (e.g. `\"v7\"`). Use as `If-Match` on the next mutation.", "schema": { "type": "string" } }, "Location": { "description": "URI of the created/affected resource.", "schema": { "type": "string", "format": "uri-reference" } }, "IdempotencyReplayed": { "description": "`true` when a stored idempotent response was replayed rather than freshly computed.", "schema": { "type": "boolean" } }, "RetryAfter": { "description": "Seconds to wait before retrying (on 429 / 503).", "schema": { "type": "integer" } } } } }