{ "openapi": "3.1.1", "info": { "title": "Trusted Records — Proposed Integration Contract", "version": "1.2.0-proposed", "description": "Design proposal derived from user business requirements and reference architecture. Not a production API. Examples are synthetic. No actual SDK, endpoint, limits or signing profile is verified.", "contact": { "name": "Mobile-ID", "email": "info@mobile-id.vn", "url": "https://www.mobile-id.vn/vi" } }, "servers": [ { "url": "https://records.example.invalid", "description": "Example host only — intentionally non-resolving" } ], "paths": { "/v1/ingest-packages": { "post": { "operationId": "ingest", "summary": "Ingest packages", "description": "Submit manifests for validation and asynchronous jobs; examples use synthetic fileRefs, not actual uploads. PROPOSED CONTRACT. Idempotency, pagination and limit policies require confirmation.\n\nLifecycle: RECEIVED → VALIDATING → ACCEPTED / QUARANTINED. Accepted ingest does not imply declaration.\nRecovery: Missing manifests or invalid checksums/schemas return 422; key reuse with changed bodies returns 409.", "security": [ { "oauth2": [ "ingest:write" ] } ], "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Project-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Correlation-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "202": { "description": "Synthetic successful result, not a production guarantee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestResponse" }, "example": { "jobId": "synthetic-job-001", "status": "VALIDATING", "packageId": "synthetic-package-001" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "UNAUTHENTICATED", "message": "Synthetic Authentication failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "403": { "description": "Scope/context denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SCOPE_DENIED", "message": "Synthetic Scope/context denied", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "404": { "description": "Object not found within scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NOT_FOUND", "message": "Synthetic Object not found within scope", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "409": { "description": "Version/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VERSION_OR_KEY_CONFLICT", "message": "Synthetic Version/idempotency conflict", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VALIDATION_FAILED", "message": "Synthetic Validation failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "429": { "description": "Rate limited; retry policy to be agreed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RATE_LIMITED", "message": "Synthetic Rate limited; retry policy to be agreed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Unavailable; retry eligible under contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Synthetic Unavailable; retry eligible under contract", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "504": { "description": "Synthetic outcome unknown. Query/reconcile before retry; not a provider timeout commitment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "OUTCOME_UNKNOWN", "message": "Synthetic response lost; outcome unknown", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestRequest" }, "example": { "sourceRef": "synthetic-source-001", "schemaVersion": "1.0", "manifest": [ { "fileRef": "synthetic-file-001", "sha256": "0000000000000000000000000000000000000000000000000000000000000000" } ] } } } }, "tags": [ "Intake" ], "x-release-status": "PROPOSED", "x-description-vi": "Gửi manifest để kiểm tra và tạo job bất đồng bộ; ví dụ chỉ dùng fileRef tổng hợp, không tải file thật." } }, "/v1/records/declarations": { "post": { "operationId": "declare", "summary": "Registration and declaration", "description": "Request declaration for validated/QC packages under file plans and approval authority. PROPOSED CONTRACT. Idempotency, pagination and limit policies require confirmation.\n\nLifecycle: REQUESTED → REVIEW_PENDING → APPROVED / REJECTED → DECLARED. Jobs cannot bypass approval.\nRecovery: Missing QC or invalid classifications return 422; insufficient permission returns 403.", "security": [ { "oauth2": [ "records:declare" ] } ], "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Project-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Correlation-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "202": { "description": "Synthetic successful result, not a production guarantee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclareResponse" }, "example": { "jobId": "synthetic-job-002", "status": "REVIEW_PENDING", "declarationRef": "synthetic-declaration-001" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "UNAUTHENTICATED", "message": "Synthetic Authentication failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "403": { "description": "Scope/context denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SCOPE_DENIED", "message": "Synthetic Scope/context denied", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "404": { "description": "Object not found within scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NOT_FOUND", "message": "Synthetic Object not found within scope", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "409": { "description": "Version/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VERSION_OR_KEY_CONFLICT", "message": "Synthetic Version/idempotency conflict", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VALIDATION_FAILED", "message": "Synthetic Validation failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "429": { "description": "Rate limited; retry policy to be agreed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RATE_LIMITED", "message": "Synthetic Rate limited; retry policy to be agreed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Unavailable; retry eligible under contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Synthetic Unavailable; retry eligible under contract", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "504": { "description": "Synthetic outcome unknown. Query/reconcile before retry; not a provider timeout commitment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "OUTCOME_UNKNOWN", "message": "Synthetic response lost; outcome unknown", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclareRequest" }, "example": { "packageId": "synthetic-package-001", "recordClass": "synthetic-class-001", "qcRef": "synthetic-qc-001" } } } }, "tags": [ "Records" ], "x-release-status": "PROPOSED", "x-description-vi": "Đề nghị declaration cho package đã kiểm/QC, theo file plan và quyền phê duyệt." } }, "/v1/records/{recordId}/metadata": { "patch": { "operationId": "metadata", "summary": "Controlled metadata updates", "description": "Create correction requests with expectedVersion/reason; do not silently edit declared records. PROPOSED CONTRACT. Idempotency, pagination and limit policies require confirmation.\n\nLifecycle: REQUESTED → REVIEW → APPROVED → VERSIONED. Retain previous versions and audit.\nRecovery: Version conflicts return 409, field/schema defects 422, insufficient metadata permissions 403.", "security": [ { "oauth2": [ "records:metadata" ] } ], "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Project-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Correlation-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "202": { "description": "Synthetic successful result, not a production guarantee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataResponse" }, "example": { "jobId": "synthetic-job-003", "status": "REVIEW_PENDING", "correctionRef": "synthetic-correction-001" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "UNAUTHENTICATED", "message": "Synthetic Authentication failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "403": { "description": "Scope/context denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SCOPE_DENIED", "message": "Synthetic Scope/context denied", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "404": { "description": "Object not found within scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NOT_FOUND", "message": "Synthetic Object not found within scope", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "409": { "description": "Version/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VERSION_OR_KEY_CONFLICT", "message": "Synthetic Version/idempotency conflict", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VALIDATION_FAILED", "message": "Synthetic Validation failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "429": { "description": "Rate limited; retry policy to be agreed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RATE_LIMITED", "message": "Synthetic Rate limited; retry policy to be agreed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Unavailable; retry eligible under contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Synthetic Unavailable; retry eligible under contract", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "504": { "description": "Synthetic outcome unknown. Query/reconcile before retry; not a provider timeout commitment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "OUTCOME_UNKNOWN", "message": "Synthetic response lost; outcome unknown", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataRequest" }, "example": { "expectedVersion": 1, "reason": "synthetic correction", "metadata": { "title": "Synthetic record" } } } } }, "tags": [ "Records" ], "x-release-status": "PROPOSED", "x-description-vi": "Tạo yêu cầu correction; giữ expectedVersion và lý do, không sửa âm thầm hồ sơ đã declaration." } }, "/v1/jobs/{jobId}": { "get": { "operationId": "job", "summary": "Processing jobs and status", "description": "Track asynchronous jobs and object-level errors. Tool progress is synthetic. PROPOSED CONTRACT. Idempotency, pagination and limit policies require confirmation.\n\nLifecycle: QUEUED → RUNNING / VALIDATING → SUCCEEDED / FAILED / REVIEW_PENDING. SUCCEEDED describes the job only.\nRecovery: 404 for missing jobs within scope; 403 for authorization failures; illustrative 503 for service unavailability.", "security": [ { "oauth2": [ "jobs:read" ] } ], "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Project-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Correlation-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Synthetic successful result, not a production guarantee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "jobId": "synthetic-job-001", "status": "VALIDATING", "progress": { "processed": 1, "total": 2 }, "errors": [], "correlationId": "synthetic-correlation-001" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "UNAUTHENTICATED", "message": "Synthetic Authentication failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "403": { "description": "Scope/context denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SCOPE_DENIED", "message": "Synthetic Scope/context denied", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "404": { "description": "Object not found within scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NOT_FOUND", "message": "Synthetic Object not found within scope", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "409": { "description": "Version/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VERSION_OR_KEY_CONFLICT", "message": "Synthetic Version/idempotency conflict", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VALIDATION_FAILED", "message": "Synthetic Validation failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "429": { "description": "Rate limited; retry policy to be agreed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RATE_LIMITED", "message": "Synthetic Rate limited; retry policy to be agreed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Unavailable; retry eligible under contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Synthetic Unavailable; retry eligible under contract", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "504": { "description": "Synthetic outcome unknown. Query/reconcile before retry; not a provider timeout commitment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "OUTCOME_UNKNOWN", "message": "Synthetic response lost; outcome unknown", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } } } }, "tags": [ "Jobs" ], "x-release-status": "PROPOSED", "x-description-vi": "Theo dõi job không đồng bộ và lỗi theo đối tượng. Progress là dữ liệu tổng hợp của công cụ.", "x-simulator-request-schema": { "$ref": "#/components/schemas/JobRequest" } } }, "/v1/records/search": { "post": { "operationId": "search", "summary": "Record search", "description": "Query authorized metadata/full text. Cursors are opaque; proposed pageSize range is 1–100. PROPOSED CONTRACT. Idempotency, pagination and limit policies require confirmation.\n\nLifecycle: REQUEST → AUTHORIZED QUERY → FILTERED RESULT. Every viewer/download rechecks permission.\nRecovery: Invalid query/pageSize returns 422; mismatched context/permissions return 403; errors must not disclose out-of-scope records.", "security": [ { "oauth2": [ "records:read" ] } ], "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Project-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Correlation-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Synthetic successful result, not a production guarantee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "example": { "items": [ { "recordId": "synthetic-record-001", "title": "Synthetic record" } ], "nextCursor": null } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "UNAUTHENTICATED", "message": "Synthetic Authentication failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "403": { "description": "Scope/context denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SCOPE_DENIED", "message": "Synthetic Scope/context denied", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "404": { "description": "Object not found within scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NOT_FOUND", "message": "Synthetic Object not found within scope", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "409": { "description": "Version/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VERSION_OR_KEY_CONFLICT", "message": "Synthetic Version/idempotency conflict", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VALIDATION_FAILED", "message": "Synthetic Validation failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "429": { "description": "Rate limited; retry policy to be agreed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RATE_LIMITED", "message": "Synthetic Rate limited; retry policy to be agreed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Unavailable; retry eligible under contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Synthetic Unavailable; retry eligible under contract", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "504": { "description": "Synthetic outcome unknown. Query/reconcile before retry; not a provider timeout commitment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "OUTCOME_UNKNOWN", "message": "Synthetic response lost; outcome unknown", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" }, "example": { "query": "synthetic", "pageSize": 10, "cursor": null } } } }, "tags": [ "Access" ], "x-release-status": "PROPOSED", "x-description-vi": "Truy vấn metadata/full-text theo quyền. Cursor opaque; pageSize hợp lệ 1–100 trong contract đề xuất." } }, "/v1/access-requests": { "post": { "operationId": "access", "summary": "Access requests", "description": "Request expiring, purpose-bound access; grants follow authorized approval. PROPOSED CONTRACT. Idempotency, pagination and limit policies require confirmation.\n\nLifecycle: REQUESTED → APPROVED / DENIED → ACTIVE → EXPIRED / REVOKED.\nRecovery: Invalid purpose/expiry returns 422; inappropriate request authority returns 403; hold/access policy may block.", "security": [ { "oauth2": [ "access:request" ] } ], "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Project-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Correlation-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "202": { "description": "Synthetic successful result, not a production guarantee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessResponse" }, "example": { "requestId": "synthetic-access-001", "status": "APPROVAL_PENDING" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "UNAUTHENTICATED", "message": "Synthetic Authentication failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "403": { "description": "Scope/context denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SCOPE_DENIED", "message": "Synthetic Scope/context denied", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "404": { "description": "Object not found within scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NOT_FOUND", "message": "Synthetic Object not found within scope", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "409": { "description": "Version/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VERSION_OR_KEY_CONFLICT", "message": "Synthetic Version/idempotency conflict", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VALIDATION_FAILED", "message": "Synthetic Validation failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "429": { "description": "Rate limited; retry policy to be agreed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RATE_LIMITED", "message": "Synthetic Rate limited; retry policy to be agreed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Unavailable; retry eligible under contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Synthetic Unavailable; retry eligible under contract", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "504": { "description": "Synthetic outcome unknown. Query/reconcile before retry; not a provider timeout commitment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "OUTCOME_UNKNOWN", "message": "Synthetic response lost; outcome unknown", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessRequest" }, "example": { "recordId": "synthetic-record-001", "purpose": "synthetic audit", "expiresAt": "2026-10-08T00:00:00Z" } } } }, "tags": [ "Access" ], "x-release-status": "PROPOSED", "x-description-vi": "Đề nghị quyền có thời hạn và mục đích; grant chỉ sau người có thẩm quyền duyệt." } }, "/v1/preservation-packages": { "post": { "operationId": "preserve", "summary": "Preservation packages", "description": "Request SIP validation and AIP creation/management under approved profiles. PROPOSED CONTRACT. Idempotency, pagination and limit policies require confirmation.\n\nLifecycle: SIP_VALIDATING → AIP_PENDING → PRESERVED / EXCEPTION. Fixity/format checks continue over time.\nRecovery: Missing representations/profiles return 422; policy/version conflicts return 409; fixity mismatches create exceptions.\nV4 mock stops at PROFILE_REVIEW. Provider receipt, LTANS verification and renewal need an authorized provider contract.", "security": [ { "oauth2": [ "preservation:write" ] } ], "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Project-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Correlation-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "202": { "description": "Synthetic successful result, not a production guarantee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreserveResponse" }, "example": { "jobId": "synthetic-job-004", "status": "SIP_VALIDATING", "packageRef": "synthetic-aip-001" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "UNAUTHENTICATED", "message": "Synthetic Authentication failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "403": { "description": "Scope/context denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SCOPE_DENIED", "message": "Synthetic Scope/context denied", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "404": { "description": "Object not found within scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NOT_FOUND", "message": "Synthetic Object not found within scope", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "409": { "description": "Version/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VERSION_OR_KEY_CONFLICT", "message": "Synthetic Version/idempotency conflict", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VALIDATION_FAILED", "message": "Synthetic Validation failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "429": { "description": "Rate limited; retry policy to be agreed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RATE_LIMITED", "message": "Synthetic Rate limited; retry policy to be agreed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Unavailable; retry eligible under contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Synthetic Unavailable; retry eligible under contract", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "504": { "description": "Synthetic outcome unknown. Query/reconcile before retry; not a provider timeout commitment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "OUTCOME_UNKNOWN", "message": "Synthetic response lost; outcome unknown", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreserveRequest" }, "example": { "recordIds": [ "synthetic-record-001" ], "profileRef": "synthetic-preservation-001" } } } }, "tags": [ "Preservation" ], "x-release-status": "PROPOSED", "x-description-vi": "Đề nghị validate SIP và tạo/quản lý AIP theo profile được duyệt." } }, "/v1/deliveries/{deliveryId}/acceptance": { "post": { "operationId": "deliver", "summary": "Delivery and acceptance", "description": "Record accepted sets/decisions against manifests; billing is separately reconciled. PROPOSED CONTRACT. Idempotency, pagination and limit policies require confirmation.\n\nLifecycle: DELIVERED → REVIEW → PARTIAL_ACCEPTANCE / ACCEPTED / CORRECTION. No automatic invoice.\nRecovery: Manifest version mismatches return 409; out-of-manifest sets or permissions return 422/403.", "security": [ { "oauth2": [ "delivery:accept" ] } ], "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Project-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Correlation-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "202": { "description": "Synthetic successful result, not a production guarantee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliverResponse" }, "example": { "acceptanceRef": "synthetic-acceptance-001", "status": "RECONCILING", "billableEvaluated": false } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "UNAUTHENTICATED", "message": "Synthetic Authentication failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "403": { "description": "Scope/context denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SCOPE_DENIED", "message": "Synthetic Scope/context denied", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "404": { "description": "Object not found within scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NOT_FOUND", "message": "Synthetic Object not found within scope", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "409": { "description": "Version/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VERSION_OR_KEY_CONFLICT", "message": "Synthetic Version/idempotency conflict", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VALIDATION_FAILED", "message": "Synthetic Validation failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "429": { "description": "Rate limited; retry policy to be agreed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RATE_LIMITED", "message": "Synthetic Rate limited; retry policy to be agreed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Unavailable; retry eligible under contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Synthetic Unavailable; retry eligible under contract", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "504": { "description": "Synthetic outcome unknown. Query/reconcile before retry; not a provider timeout commitment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "OUTCOME_UNKNOWN", "message": "Synthetic response lost; outcome unknown", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliverRequest" }, "example": { "manifestVersion": 1, "acceptedRefs": [ "synthetic-record-001" ], "decision": "PARTIAL_ACCEPTANCE" } } } }, "tags": [ "Acceptance" ], "x-release-status": "PROPOSED", "x-description-vi": "Ghi tập chấp nhận và quyết định theo manifest; billing là bước đối soát riêng." } }, "/v1/evidence/verification": { "post": { "operationId": "verify", "summary": "Evidence verification", "description": "Verify integrity against manifest/reference hashes; do not infer provenance or legal status. PROPOSED CONTRACT. Idempotency, pagination and limit policies require confirmation.\n\nLifecycle: CHECKED → MATCH / MISMATCH / INDETERMINATE. Simulator results do not verify actual files.\nRecovery: Invalid hash formats return 422; insufficient permissions 403; missing reference evidence is INDETERMINATE.", "security": [ { "oauth2": [ "evidence:verify" ] } ], "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Project-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Correlation-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Synthetic successful result, not a production guarantee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResponse" }, "example": { "verificationRef": "synthetic-verification-001", "integrity": "MATCH", "provenance": "NOT_EVALUATED", "legalStatus": "NOT_EVALUATED" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "UNAUTHENTICATED", "message": "Synthetic Authentication failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "403": { "description": "Scope/context denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SCOPE_DENIED", "message": "Synthetic Scope/context denied", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "404": { "description": "Object not found within scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NOT_FOUND", "message": "Synthetic Object not found within scope", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "409": { "description": "Version/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VERSION_OR_KEY_CONFLICT", "message": "Synthetic Version/idempotency conflict", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VALIDATION_FAILED", "message": "Synthetic Validation failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "429": { "description": "Rate limited; retry policy to be agreed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RATE_LIMITED", "message": "Synthetic Rate limited; retry policy to be agreed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Unavailable; retry eligible under contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Synthetic Unavailable; retry eligible under contract", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "504": { "description": "Synthetic outcome unknown. Query/reconcile before retry; not a provider timeout commitment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "OUTCOME_UNKNOWN", "message": "Synthetic response lost; outcome unknown", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" }, "example": { "manifestRef": "synthetic-manifest-001", "expectedHash": "0000000000000000000000000000000000000000000000000000000000000000" } } } }, "tags": [ "Evidence" ], "x-release-status": "PROPOSED", "x-description-vi": "Kiểm toàn vẹn theo manifest/hash tham chiếu; không tự kết luận nguồn gốc hoặc giá trị pháp lý." } }, "/v1/device-commands": { "post": { "operationId": "device-command", "summary": "Flow R routing decision", "description": "Adapter design for discussion; RECEIVED does not confirm paper arrival. PROPOSED CONTRACT. Idempotency, pagination and limit policies require confirmation.\n\nLifecycle: Illustrative states; agree contract mappings.\nRecovery: 422 invalid data; 403 denied; 409 key/version conflict; 503 unavailable.", "security": [ { "oauth2": [ "devices:command" ] } ], "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Project-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Correlation-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "202": { "description": "Synthetic successful result, not a production guarantee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Device-CommandResponse" }, "example": { "commandId": "synthetic-command-001", "state": "RECEIVED", "executionConfirmed": false } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "UNAUTHENTICATED", "message": "Synthetic Authentication failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "403": { "description": "Scope/context denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SCOPE_DENIED", "message": "Synthetic Scope/context denied", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "404": { "description": "Object not found within scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NOT_FOUND", "message": "Synthetic Object not found within scope", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "409": { "description": "Version/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VERSION_OR_KEY_CONFLICT", "message": "Synthetic Version/idempotency conflict", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VALIDATION_FAILED", "message": "Synthetic Validation failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "429": { "description": "Rate limited; retry policy to be agreed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RATE_LIMITED", "message": "Synthetic Rate limited; retry policy to be agreed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Unavailable; retry eligible under contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Synthetic Unavailable; retry eligible under contract", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "504": { "description": "Synthetic outcome unknown. Query/reconcile before retry; not a provider timeout commitment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "OUTCOME_UNKNOWN", "message": "Synthetic response lost; outcome unknown", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceCommandRequest" }, "example": { "commandId": "synthetic-command-001", "stationId": "synthetic-station-001", "sheetId": "synthetic-sheet-001", "dossierId": "synthetic-dossier-001", "trayId": "synthetic-tray-001", "targetSheetIndex": 1, "decisionVersion": 1, "deadline": "2026-10-08T00:00:05Z" } } } }, "tags": [ "Device/Edge" ], "x-release-status": "PROPOSED", "x-description-vi": "Thiết kế adapter để thảo luận; RECEIVED không xác nhận giấy đã đến khay." } }, "/v1/payment-requests": { "post": { "operationId": "payment-request", "summary": "Payment request", "description": "Design payment requests from acceptance; no payable QR is generated. PROPOSED CONTRACT. Idempotency, pagination and limit policies require confirmation.\n\nLifecycle: Illustrative states; agree contract mappings.\nRecovery: 422 invalid data; 403 denied; 409 key/version conflict; 503 unavailable.", "security": [ { "oauth2": [ "billing:write" ] } ], "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Project-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Correlation-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "202": { "description": "Synthetic successful result, not a production guarantee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment-RequestResponse" }, "example": { "paymentRequestId": "synthetic-payment-001", "state": "PENDING", "payableQr": null } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "UNAUTHENTICATED", "message": "Synthetic Authentication failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "403": { "description": "Scope/context denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SCOPE_DENIED", "message": "Synthetic Scope/context denied", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "404": { "description": "Object not found within scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NOT_FOUND", "message": "Synthetic Object not found within scope", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "409": { "description": "Version/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VERSION_OR_KEY_CONFLICT", "message": "Synthetic Version/idempotency conflict", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VALIDATION_FAILED", "message": "Synthetic Validation failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "429": { "description": "Rate limited; retry policy to be agreed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RATE_LIMITED", "message": "Synthetic Rate limited; retry policy to be agreed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Unavailable; retry eligible under contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Synthetic Unavailable; retry eligible under contract", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "504": { "description": "Synthetic outcome unknown. Query/reconcile before retry; not a provider timeout commitment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "OUTCOME_UNKNOWN", "message": "Synthetic response lost; outcome unknown", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequestRequest" }, "example": { "acceptanceRef": "synthetic-acceptance-001", "billingVersion": 1, "amountMinor": 125000, "currency": "VND", "channel": "NAPAS_QR_PROPOSED" } } } }, "tags": [ "Billing" ], "x-release-status": "PROPOSED", "x-description-vi": "Thiết kế yêu cầu thanh toán từ nghiệm thu; không sinh QR thanh toán thật." } }, "/v1/payment-requests/{paymentRequestId}": { "get": { "operationId": "payment-status", "summary": "Payment status", "description": "Illustrative confirmation is not reconciliation or invoice issuance. PROPOSED CONTRACT. Idempotency, pagination and limit policies require confirmation.\n\nLifecycle: Illustrative states; agree contract mappings.\nRecovery: 422 invalid data; 403 denied; 409 key/version conflict; 503 unavailable.", "security": [ { "oauth2": [ "billing:read" ] } ], "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Project-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Correlation-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Synthetic successful result, not a production guarantee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment-StatusResponse" }, "example": { "paymentRequestId": "synthetic-payment-001", "state": "CONFIRMED", "providerRef": "synthetic-provider-001", "reconciled": false } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "UNAUTHENTICATED", "message": "Synthetic Authentication failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "403": { "description": "Scope/context denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SCOPE_DENIED", "message": "Synthetic Scope/context denied", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "404": { "description": "Object not found within scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NOT_FOUND", "message": "Synthetic Object not found within scope", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "409": { "description": "Version/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VERSION_OR_KEY_CONFLICT", "message": "Synthetic Version/idempotency conflict", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VALIDATION_FAILED", "message": "Synthetic Validation failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "429": { "description": "Rate limited; retry policy to be agreed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RATE_LIMITED", "message": "Synthetic Rate limited; retry policy to be agreed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Unavailable; retry eligible under contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Synthetic Unavailable; retry eligible under contract", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "504": { "description": "Synthetic outcome unknown. Query/reconcile before retry; not a provider timeout commitment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "OUTCOME_UNKNOWN", "message": "Synthetic response lost; outcome unknown", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } } } }, "tags": [ "Billing" ], "x-release-status": "PROPOSED", "x-description-vi": "Ví dụ confirmation chưa là reconciliation hoặc hóa đơn issued.", "x-simulator-request-schema": { "$ref": "#/components/schemas/PaymentStatusRequest" } } }, "/v1/invoice-requests": { "post": { "operationId": "invoice-request", "summary": "Invoice request", "description": "Proposed Trusted Billing submission; confirm schemas/provider mapping. PROPOSED CONTRACT. Idempotency, pagination and limit policies require confirmation.\n\nLifecycle: Illustrative states; agree contract mappings.\nRecovery: 422 invalid data; 403 denied; 409 key/version conflict; 503 unavailable.", "security": [ { "oauth2": [ "billing:write" ] } ], "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Project-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Correlation-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "202": { "description": "Synthetic successful result, not a production guarantee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice-RequestResponse" }, "example": { "invoiceRequestId": "synthetic-invoice-001", "state": "REQUESTED" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "UNAUTHENTICATED", "message": "Synthetic Authentication failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "403": { "description": "Scope/context denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SCOPE_DENIED", "message": "Synthetic Scope/context denied", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "404": { "description": "Object not found within scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NOT_FOUND", "message": "Synthetic Object not found within scope", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "409": { "description": "Version/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VERSION_OR_KEY_CONFLICT", "message": "Synthetic Version/idempotency conflict", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VALIDATION_FAILED", "message": "Synthetic Validation failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "429": { "description": "Rate limited; retry policy to be agreed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RATE_LIMITED", "message": "Synthetic Rate limited; retry policy to be agreed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Unavailable; retry eligible under contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Synthetic Unavailable; retry eligible under contract", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "504": { "description": "Synthetic outcome unknown. Query/reconcile before retry; not a provider timeout commitment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "OUTCOME_UNKNOWN", "message": "Synthetic response lost; outcome unknown", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRequestRequest" }, "example": { "paymentRequestId": "synthetic-payment-001", "acceptanceRef": "synthetic-acceptance-001", "recipientRef": "synthetic-recipient-001" } } } }, "tags": [ "Billing" ], "x-release-status": "PROPOSED", "x-description-vi": "Đề xuất gửi Trusted Billing; schema/provider mapping cần xác nhận." } }, "/v1/invoice-requests/{invoiceRequestId}": { "get": { "operationId": "invoice-status", "summary": "Invoice status", "description": "Track asynchronous processing; no document is available while PROCESSING. PROPOSED CONTRACT. Idempotency, pagination and limit policies require confirmation.\n\nLifecycle: Illustrative states; agree contract mappings.\nRecovery: 422 invalid data; 403 denied; 409 key/version conflict; 503 unavailable.", "security": [ { "oauth2": [ "billing:read" ] } ], "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Project-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Correlation-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "invoiceRequestId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Synthetic successful result, not a production guarantee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice-StatusResponse" }, "example": { "invoiceRequestId": "synthetic-invoice-001", "state": "PROCESSING", "documentRef": null } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "UNAUTHENTICATED", "message": "Synthetic Authentication failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "403": { "description": "Scope/context denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SCOPE_DENIED", "message": "Synthetic Scope/context denied", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "404": { "description": "Object not found within scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NOT_FOUND", "message": "Synthetic Object not found within scope", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "409": { "description": "Version/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VERSION_OR_KEY_CONFLICT", "message": "Synthetic Version/idempotency conflict", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "VALIDATION_FAILED", "message": "Synthetic Validation failed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": false, "details": [] } } } }, "429": { "description": "Rate limited; retry policy to be agreed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RATE_LIMITED", "message": "Synthetic Rate limited; retry policy to be agreed", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Unavailable; retry eligible under contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Synthetic Unavailable; retry eligible under contract", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } }, "headers": { "Retry-After": { "description": "Optional provider-defined delay; not an approved quota or SLA.", "schema": { "type": "integer", "minimum": 0 } } } }, "504": { "description": "Synthetic outcome unknown. Query/reconcile before retry; not a provider timeout commitment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "OUTCOME_UNKNOWN", "message": "Synthetic response lost; outcome unknown", "requestId": "synthetic-request-001", "correlationId": "synthetic-correlation-001", "retryable": true, "details": [] } } } } }, "tags": [ "Billing" ], "x-release-status": "PROPOSED", "x-description-vi": "Theo dõi bất đồng bộ; chưa có chứng từ để tải khi PROCESSING.", "x-simulator-request-schema": { "$ref": "#/components/schemas/InvoiceStatusRequest" } } } }, "webhooks": { "recordEvent": { "post": { "description": "Proposed event delivery. Verify HMAC-SHA256(timestamp + dot + rawBody), timestamp window and eventId replay state server-side. Confirm actual signing contract.", "parameters": [ { "name": "X-TR-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-TR-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventEnvelope" } } } }, "responses": { "204": { "description": "Durably received or previously processed duplicate" }, "400": { "description": "Invalid signature/timestamp/envelope" } }, "operationId": "receiveRecordEvent", "x-release-status": "PROPOSED", "security": [] } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "code", "message", "requestId", "correlationId", "retryable", "details" ], "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "requestId": { "type": "string", "minLength": 1 }, "correlationId": { "type": "string", "minLength": 1 }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object" } } } }, "IngestRequest": { "type": "object", "properties": { "sourceRef": { "type": "string", "minLength": 1, "description": "Synthetic source identifier; custody reference in a real contract.", "maxLength": 128 }, "schemaVersion": { "type": "string", "minLength": 1, "description": "Metadata schema version agreed for admission." }, "manifest": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "fileRef", "sha256" ], "properties": { "fileRef": { "type": "string", "minLength": 1 }, "sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" } } }, "description": "File references and expected SHA-256 values; source bytes are not uploaded by the website." } }, "required": [ "sourceRef", "schemaVersion", "manifest" ], "example": { "sourceRef": "synthetic-source-001", "schemaVersion": "1.0", "manifest": [ { "fileRef": "synthetic-file-001", "sha256": "0000000000000000000000000000000000000000000000000000000000000000" } ] }, "additionalProperties": false }, "IngestResponse": { "type": "object", "required": [ "jobId", "status", "packageId" ], "properties": { "jobId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "packageId": { "type": "string", "minLength": 1 } } }, "DeclareRequest": { "type": "object", "properties": { "packageId": { "type": "string", "minLength": 1, "description": "Intake package identifier linked to validation jobs.", "maxLength": 128 }, "recordClass": { "type": "string", "minLength": 1, "description": "Classification code under the agreed records scheme." }, "qcRef": { "type": "string", "minLength": 1, "description": "QC decision reference; registration must follow successful validation and authorized review.", "maxLength": 128 } }, "required": [ "packageId", "recordClass", "qcRef" ], "example": { "packageId": "synthetic-package-001", "recordClass": "synthetic-class-001", "qcRef": "synthetic-qc-001" }, "additionalProperties": false }, "DeclareResponse": { "type": "object", "required": [ "jobId", "status", "declarationRef" ], "properties": { "jobId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "declarationRef": { "type": "string", "minLength": 1 } } }, "MetadataRequest": { "type": "object", "properties": { "expectedVersion": { "type": "integer", "minimum": 1, "description": "Proposed expectedVersion field. Synthetic identifiers must not contain personal data." }, "reason": { "type": "string", "minLength": 1, "description": "Proposed reason field. Synthetic identifiers must not contain personal data." }, "metadata": { "type": "object", "description": "Proposed metadata field. Synthetic identifiers must not contain personal data.", "minProperties": 1 } }, "required": [ "expectedVersion", "reason", "metadata" ], "example": { "expectedVersion": 1, "reason": "synthetic correction", "metadata": { "title": "Synthetic record" } }, "additionalProperties": false }, "MetadataResponse": { "type": "object", "required": [ "jobId", "status", "correctionRef" ], "properties": { "jobId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "correctionRef": { "type": "string", "minLength": 1 } } }, "JobRequest": { "type": "object", "properties": {}, "required": [], "example": {}, "additionalProperties": false }, "JobResponse": { "type": "object", "required": [ "jobId", "status", "progress", "errors", "correlationId" ], "properties": { "jobId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "progress": { "type": "object", "required": [ "processed", "total" ], "properties": { "processed": { "type": "integer" }, "total": { "type": "integer" } } }, "errors": { "type": "array", "items": {} }, "correlationId": { "type": "string", "minLength": 1 } } }, "SearchRequest": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "Synthetic search expression; production query grammar is unverified." }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Requested page size, at most 100 in this proposal." }, "cursor": { "type": [ "string", "null" ], "description": "Opaque pagination cursor or null for the first page." } }, "required": [ "query", "pageSize" ], "example": { "query": "synthetic", "pageSize": 10, "cursor": null }, "additionalProperties": false }, "SearchResponse": { "type": "object", "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "recordId", "title" ], "properties": { "recordId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 } } } }, "nextCursor": { "type": [ "string", "null" ] } } }, "AccessRequest": { "type": "object", "properties": { "recordId": { "type": "string", "minLength": 1, "description": "Registered record identifier; token scope alone does not confer object access.", "maxLength": 128 }, "purpose": { "type": "string", "minLength": 1, "description": "Purpose of access to evaluate against object-level authority." }, "expiresAt": { "type": "string", "minLength": 1, "format": "date-time", "description": "UTC expiry of the proposed access request, not an issued grant." } }, "required": [ "recordId", "purpose", "expiresAt" ], "example": { "recordId": "synthetic-record-001", "purpose": "synthetic audit", "expiresAt": "2026-10-08T00:00:00Z" }, "additionalProperties": false }, "AccessResponse": { "type": "object", "required": [ "requestId", "status" ], "properties": { "requestId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 } } }, "PreserveRequest": { "type": "object", "properties": { "recordIds": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "Registered records eligible for the preservation request." }, "profileRef": { "type": "string", "minLength": 1, "description": "Preservation profile identifier; synthetic examples are unapproved reference profiles.", "maxLength": 128, "enum": [ "synthetic-preservation-001", "synthetic-signed-evidence-001", "synthetic-born-digital-001" ] } }, "required": [ "recordIds", "profileRef" ], "example": { "recordIds": [ "synthetic-record-001" ], "profileRef": "synthetic-preservation-001" }, "additionalProperties": false }, "PreserveResponse": { "type": "object", "required": [ "jobId", "status", "packageRef" ], "properties": { "jobId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "packageRef": { "type": "string", "minLength": 1 } } }, "DeliverRequest": { "type": "object", "properties": { "manifestVersion": { "type": "integer", "minimum": 1, "description": "Expected version of the delivery manifest; refresh after a conflict." }, "acceptedRefs": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "Subset of records in the delivered manifest; no out-of-manifest acceptance." }, "decision": { "type": "string", "minLength": 1, "enum": [ "PARTIAL_ACCEPTANCE", "ACCEPTED", "CORRECTION" ], "description": "Authorized acceptance, partial acceptance or correction decision." } }, "required": [ "manifestVersion", "acceptedRefs", "decision" ], "example": { "manifestVersion": 1, "acceptedRefs": [ "synthetic-record-001" ], "decision": "PARTIAL_ACCEPTANCE" }, "additionalProperties": false }, "DeliverResponse": { "type": "object", "required": [ "acceptanceRef", "status", "billableEvaluated" ], "properties": { "acceptanceRef": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "billableEvaluated": { "type": "boolean" } } }, "VerifyRequest": { "type": "object", "properties": { "manifestRef": { "type": "string", "minLength": 1, "description": "Proposed manifestRef field. Synthetic identifiers must not contain personal data.", "maxLength": 128 }, "expectedHash": { "type": "string", "minLength": 1, "pattern": "^[a-fA-F0-9]{64}$", "description": "Expected SHA-256 of referenced content; agreement does not establish manifest authenticity." } }, "required": [ "manifestRef", "expectedHash" ], "example": { "manifestRef": "synthetic-manifest-001", "expectedHash": "0000000000000000000000000000000000000000000000000000000000000000" }, "additionalProperties": false }, "VerifyResponse": { "type": "object", "required": [ "verificationRef", "integrity", "provenance", "legalStatus" ], "properties": { "verificationRef": { "type": "string", "minLength": 1 }, "integrity": { "type": "string", "minLength": 1 }, "provenance": { "type": "string", "minLength": 1 }, "legalStatus": { "type": "string", "minLength": 1 } } }, "DeviceCommandRequest": { "type": "object", "properties": { "commandId": { "type": "string", "minLength": 1, "description": "Proposed commandId field. Synthetic identifiers must not contain personal data.", "maxLength": 128 }, "stationId": { "type": "string", "minLength": 1, "description": "Proposed stationId field. Synthetic identifiers must not contain personal data.", "maxLength": 128 }, "sheetId": { "type": "string", "minLength": 1, "description": "Proposed sheetId field. Synthetic identifiers must not contain personal data.", "maxLength": 128 }, "dossierId": { "type": "string", "minLength": 1, "description": "Proposed dossierId field. Synthetic identifiers must not contain personal data.", "maxLength": 128 }, "trayId": { "type": "string", "minLength": 1, "description": "Proposed trayId field. Synthetic identifiers must not contain personal data.", "maxLength": 128 }, "targetSheetIndex": { "type": "integer", "minimum": 1, "description": "One-based intended position within the dossier, not capture order." }, "decisionVersion": { "type": "integer", "minimum": 1, "description": "Proposed decisionVersion field. Synthetic identifiers must not contain personal data." }, "deadline": { "type": "string", "minLength": 1, "description": "Proposed deadline field. Synthetic identifiers must not contain personal data.", "format": "date-time" } }, "required": [ "commandId", "stationId", "sheetId", "dossierId", "trayId", "targetSheetIndex", "decisionVersion", "deadline" ], "example": { "commandId": "synthetic-command-001", "stationId": "synthetic-station-001", "sheetId": "synthetic-sheet-001", "dossierId": "synthetic-dossier-001", "trayId": "synthetic-tray-001", "targetSheetIndex": 1, "decisionVersion": 1, "deadline": "2026-10-08T00:00:05Z" }, "additionalProperties": false }, "Device-CommandResponse": { "type": "object", "required": [ "commandId", "state", "executionConfirmed" ], "properties": { "commandId": { "type": "string", "minLength": 1 }, "state": { "type": "string", "minLength": 1 }, "executionConfirmed": { "type": "boolean" } } }, "PaymentRequestRequest": { "type": "object", "properties": { "acceptanceRef": { "type": "string", "minLength": 1, "description": "Proposed acceptanceRef field. Synthetic identifiers must not contain personal data.", "maxLength": 128 }, "billingVersion": { "type": "integer", "minimum": 1, "description": "Proposed billingVersion field. Synthetic identifiers must not contain personal data." }, "amountMinor": { "type": "integer", "minimum": 1, "description": "Amount in minor units; synthetic VND uses whole dong and implies no approved price." }, "currency": { "type": "string", "minLength": 1, "description": "Proposed currency field. Synthetic identifiers must not contain personal data.", "enum": [ "VND" ] }, "channel": { "type": "string", "minLength": 1, "description": "Proposed channel field. Synthetic identifiers must not contain personal data.", "enum": [ "NAPAS_QR_PROPOSED" ] } }, "required": [ "acceptanceRef", "billingVersion", "amountMinor", "currency", "channel" ], "example": { "acceptanceRef": "synthetic-acceptance-001", "billingVersion": 1, "amountMinor": 125000, "currency": "VND", "channel": "NAPAS_QR_PROPOSED" }, "additionalProperties": false }, "Payment-RequestResponse": { "type": "object", "required": [ "paymentRequestId", "state", "payableQr" ], "properties": { "paymentRequestId": { "type": "string", "minLength": 1 }, "state": { "type": "string", "minLength": 1 }, "payableQr": { "type": [ "string", "null" ] } } }, "PaymentStatusRequest": { "type": "object", "properties": {}, "required": [], "example": {}, "additionalProperties": false }, "Payment-StatusResponse": { "type": "object", "required": [ "paymentRequestId", "state", "providerRef", "reconciled" ], "properties": { "paymentRequestId": { "type": "string", "minLength": 1 }, "state": { "type": "string", "minLength": 1 }, "providerRef": { "type": "string", "minLength": 1 }, "reconciled": { "type": "boolean" } } }, "InvoiceRequestRequest": { "type": "object", "properties": { "paymentRequestId": { "type": "string", "minLength": 1, "description": "Proposed paymentRequestId field. Synthetic identifiers must not contain personal data.", "maxLength": 128 }, "acceptanceRef": { "type": "string", "minLength": 1, "description": "Proposed acceptanceRef field. Synthetic identifiers must not contain personal data.", "maxLength": 128 }, "recipientRef": { "type": "string", "minLength": 1, "description": "Proposed recipientRef field. Synthetic identifiers must not contain personal data.", "maxLength": 128 } }, "required": [ "paymentRequestId", "acceptanceRef", "recipientRef" ], "example": { "paymentRequestId": "synthetic-payment-001", "acceptanceRef": "synthetic-acceptance-001", "recipientRef": "synthetic-recipient-001" }, "additionalProperties": false }, "Invoice-RequestResponse": { "type": "object", "required": [ "invoiceRequestId", "state" ], "properties": { "invoiceRequestId": { "type": "string", "minLength": 1 }, "state": { "type": "string", "minLength": 1 } } }, "InvoiceStatusRequest": { "type": "object", "properties": {}, "required": [], "example": {}, "additionalProperties": false }, "Invoice-StatusResponse": { "type": "object", "required": [ "invoiceRequestId", "state", "documentRef" ], "properties": { "invoiceRequestId": { "type": "string", "minLength": 1 }, "state": { "type": "string", "minLength": 1 }, "documentRef": { "type": [ "string", "null" ] } } }, "EventEnvelope": { "type": "object", "required": [ "eventId", "eventType", "occurredAt", "tenantId", "projectId", "objectRef", "version", "correlationId" ], "properties": { "eventId": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "occurredAt": { "type": "string", "minLength": 1 }, "tenantId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "objectRef": { "type": "string", "minLength": 1 }, "version": { "type": "integer" }, "correlationId": { "type": "string", "minLength": 1 }, "causationId": { "type": [ "string", "null" ] }, "payload": { "type": "object", "description": "Event-specific data to agree in production contract; no sensitive record content." } } } }, "securitySchemes": { "oauth2": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://identity.example.invalid/oauth2/token", "scopes": { "ingest:write": "Ingest packages", "records:declare": "Registration and declaration", "records:metadata": "Controlled metadata updates", "jobs:read": "Processing jobs and status", "records:read": "Record search", "access:request": "Access requests", "preservation:write": "Preservation packages", "delivery:accept": "Delivery and acceptance", "evidence:verify": "Evidence verification", "devices:command": "Flow R routing decision", "billing:write": "Invoice request", "billing:read": "Invoice status" } } } } } }, "x-release-status": "PROPOSED_NOT_RELEASED", "x-source": "V3 reference contract retained; V4 local mock and profile semantics are design proposals, not provider APIs", "tags": [ { "name": "Intake", "description": "Proposed Intake integration contract; use only synthetic fixtures." }, { "name": "Records", "description": "Proposed Records integration contract; use only synthetic fixtures." }, { "name": "Jobs", "description": "Proposed Jobs integration contract; use only synthetic fixtures." }, { "name": "Access", "description": "Proposed Access integration contract; use only synthetic fixtures." }, { "name": "Preservation", "description": "Proposed Preservation integration contract; use only synthetic fixtures." }, { "name": "Acceptance", "description": "Proposed Acceptance integration contract; use only synthetic fixtures." }, { "name": "Evidence", "description": "Proposed Evidence integration contract; use only synthetic fixtures." }, { "name": "Device/Edge", "description": "Proposed Device/Edge integration contract; use only synthetic fixtures." }, { "name": "Billing", "description": "Proposed Billing integration contract; use only synthetic fixtures." } ], "x-local-mock": { "path": "/v1", "authentication": "NONE_SYNTHETIC_ONLY", "context": "fixed synthetic tenant/project", "state": "in-memory; no persistent records", "idempotency": "process/session only; no retention guarantee" } }