{
  "notice": "Synthetic data for local examples only",
  "operations": [
    {
      "id": "ingest",
      "slug": "ingest",
      "title": [
        "Tiếp nhận gói hồ sơ",
        "Ingest packages"
      ],
      "method": "POST",
      "path": "/v1/ingest-packages",
      "scope": "ingest:write",
      "status": 202,
      "required": [
        "sourceRef",
        "schemaVersion",
        "manifest"
      ],
      "sample": {
        "sourceRef": "synthetic-source-001",
        "schemaVersion": "1.0",
        "manifest": [
          {
            "fileRef": "synthetic-file-001",
            "sha256": "0000000000000000000000000000000000000000000000000000000000000000"
          }
        ]
      },
      "response": {
        "jobId": "synthetic-job-001",
        "status": "VALIDATING",
        "packageId": "synthetic-package-001"
      },
      "purpose": [
        "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.",
        "Submit manifests for validation and asynchronous jobs; examples use synthetic fileRefs, not actual uploads."
      ],
      "state": [
        "RECEIVED → VALIDATING → ACCEPTED / QUARANTINED. Được tiếp nhận chưa đồng nghĩa declared.",
        "RECEIVED → VALIDATING → ACCEPTED / QUARANTINED. Accepted ingest does not imply declaration."
      ],
      "error": [
        "Manifest thiếu, checksum/schema không hợp lệ trả 422; key trùng body khác trả 409.",
        "Missing manifests or invalid checksums/schemas return 422; key reuse with changed bodies returns 409."
      ]
    },
    {
      "id": "declare",
      "slug": "registration",
      "title": [
        "Đăng ký và declaration",
        "Registration and declaration"
      ],
      "method": "POST",
      "path": "/v1/records/declarations",
      "scope": "records:declare",
      "status": 202,
      "required": [
        "packageId",
        "recordClass",
        "qcRef"
      ],
      "sample": {
        "packageId": "synthetic-package-001",
        "recordClass": "synthetic-class-001",
        "qcRef": "synthetic-qc-001"
      },
      "response": {
        "jobId": "synthetic-job-002",
        "status": "REVIEW_PENDING",
        "declarationRef": "synthetic-declaration-001"
      },
      "purpose": [
        "Đề nghị declaration cho package đã kiểm/QC, theo file plan và quyền phê duyệt.",
        "Request declaration for validated/QC packages under file plans and approval authority."
      ],
      "state": [
        "REQUESTED → REVIEW_PENDING → APPROVED / REJECTED → DECLARED. Job không tự bỏ qua approval.",
        "REQUESTED → REVIEW_PENDING → APPROVED / REJECTED → DECLARED. Jobs cannot bypass approval."
      ],
      "error": [
        "Thiếu QC hoặc phân loại không hợp lệ trả 422; không đủ quyền trả 403.",
        "Missing QC or invalid classifications return 422; insufficient permission returns 403."
      ]
    },
    {
      "id": "metadata",
      "slug": "metadata-api",
      "title": [
        "Cập nhật metadata có kiểm soát",
        "Controlled metadata updates"
      ],
      "method": "PATCH",
      "path": "/v1/records/{recordId}/metadata",
      "scope": "records:metadata",
      "status": 202,
      "required": [
        "expectedVersion",
        "reason",
        "metadata"
      ],
      "sample": {
        "expectedVersion": 1,
        "reason": "synthetic correction",
        "metadata": {
          "title": "Synthetic record"
        }
      },
      "response": {
        "jobId": "synthetic-job-003",
        "status": "REVIEW_PENDING",
        "correctionRef": "synthetic-correction-001"
      },
      "purpose": [
        "Tạo yêu cầu correction; giữ expectedVersion và lý do, không sửa âm thầm hồ sơ đã declaration.",
        "Create correction requests with expectedVersion/reason; do not silently edit declared records."
      ],
      "state": [
        "REQUESTED → REVIEW → APPROVED → VERSIONED. Giữ bản trước và audit.",
        "REQUESTED → REVIEW → APPROVED → VERSIONED. Retain previous versions and audit."
      ],
      "error": [
        "Version conflict 409; field/schema sai 422; quyền metadata không đủ 403.",
        "Version conflicts return 409, field/schema defects 422, insufficient metadata permissions 403."
      ]
    },
    {
      "id": "job",
      "slug": "jobs",
      "title": [
        "Job xử lý và trạng thái",
        "Processing jobs and status"
      ],
      "method": "GET",
      "path": "/v1/jobs/{jobId}",
      "scope": "jobs:read",
      "status": 200,
      "required": [],
      "sample": {},
      "response": {
        "jobId": "synthetic-job-001",
        "status": "VALIDATING",
        "progress": {
          "processed": 1,
          "total": 2
        },
        "errors": [],
        "correlationId": "synthetic-correlation-001"
      },
      "purpose": [
        "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ụ.",
        "Track asynchronous jobs and object-level errors. Tool progress is synthetic."
      ],
      "state": [
        "QUEUED → RUNNING / VALIDATING → SUCCEEDED / FAILED / REVIEW_PENDING. SUCCEEDED chỉ mô tả job.",
        "QUEUED → RUNNING / VALIDATING → SUCCEEDED / FAILED / REVIEW_PENDING. SUCCEEDED describes the job only."
      ],
      "error": [
        "404 cho job không tồn tại trong scope; 403 thiếu quyền; 503 minh họa timeout/service unavailable.",
        "404 for missing jobs within scope; 403 for authorization failures; illustrative 503 for service unavailability."
      ]
    },
    {
      "id": "search",
      "slug": "search-api",
      "title": [
        "Tra cứu hồ sơ",
        "Record search"
      ],
      "method": "POST",
      "path": "/v1/records/search",
      "scope": "records:read",
      "status": 200,
      "required": [
        "query",
        "pageSize"
      ],
      "sample": {
        "query": "synthetic",
        "pageSize": 10,
        "cursor": null
      },
      "response": {
        "items": [
          {
            "recordId": "synthetic-record-001",
            "title": "Synthetic record"
          }
        ],
        "nextCursor": null
      },
      "purpose": [
        "Truy vấn metadata/full-text theo quyền. Cursor opaque; pageSize hợp lệ 1–100 trong contract đề xuất.",
        "Query authorized metadata/full text. Cursors are opaque; proposed pageSize range is 1–100."
      ],
      "state": [
        "REQUEST → AUTHORIZED QUERY → FILTERED RESULT. Mỗi viewer/download kiểm lại quyền.",
        "REQUEST → AUTHORIZED QUERY → FILTERED RESULT. Every viewer/download rechecks permission."
      ],
      "error": [
        "Query/pageSize sai 422; context/permission không khớp 403; không để lỗi lộ hồ sơ ngoài scope.",
        "Invalid query/pageSize returns 422; mismatched context/permissions return 403; errors must not disclose out-of-scope records."
      ]
    },
    {
      "id": "access",
      "slug": "access-api",
      "title": [
        "Yêu cầu truy cập",
        "Access requests"
      ],
      "method": "POST",
      "path": "/v1/access-requests",
      "scope": "access:request",
      "status": 202,
      "required": [
        "recordId",
        "purpose",
        "expiresAt"
      ],
      "sample": {
        "recordId": "synthetic-record-001",
        "purpose": "synthetic audit",
        "expiresAt": "2026-10-08T00:00:00Z"
      },
      "response": {
        "requestId": "synthetic-access-001",
        "status": "APPROVAL_PENDING"
      },
      "purpose": [
        "Đề nghị quyền có thời hạn và mục đích; grant chỉ sau người có thẩm quyền duyệt.",
        "Request expiring, purpose-bound access; grants follow authorized approval."
      ],
      "state": [
        "REQUESTED → APPROVED / DENIED → ACTIVE → EXPIRED / REVOKED.",
        "REQUESTED → APPROVED / DENIED → ACTIVE → EXPIRED / REVOKED."
      ],
      "error": [
        "Thời hạn/mục đích sai 422; quyền đề nghị không phù hợp 403; hold/access policy có thể chặn.",
        "Invalid purpose/expiry returns 422; inappropriate request authority returns 403; hold/access policy may block."
      ]
    },
    {
      "id": "preserve",
      "slug": "preservation-api",
      "title": [
        "Gói bảo quản",
        "Preservation packages"
      ],
      "method": "POST",
      "path": "/v1/preservation-packages",
      "scope": "preservation:write",
      "status": 202,
      "required": [
        "recordIds",
        "profileRef"
      ],
      "sample": {
        "recordIds": [
          "synthetic-record-001"
        ],
        "profileRef": "synthetic-preservation-001"
      },
      "response": {
        "jobId": "synthetic-job-004",
        "status": "SIP_VALIDATING",
        "packageRef": "synthetic-aip-001"
      },
      "purpose": [
        "Đề nghị validate SIP và tạo/quản lý AIP theo profile được duyệt.",
        "Request SIP validation and AIP creation/management under approved profiles."
      ],
      "state": [
        "SIP_VALIDATING → AIP_PENDING → PRESERVED / EXCEPTION. Kiểm fixity/format là quá trình tiếp diễn.",
        "SIP_VALIDATING → AIP_PENDING → PRESERVED / EXCEPTION. Fixity/format checks continue over time."
      ],
      "error": [
        "Thiếu representation/profile 422; policy/version conflict 409; fixity mismatch mở exception.",
        "Missing representations/profiles return 422; policy/version conflicts return 409; fixity mismatches create exceptions."
      ]
    },
    {
      "id": "deliver",
      "slug": "delivery-api",
      "title": [
        "Bàn giao và nghiệm thu",
        "Delivery and acceptance"
      ],
      "method": "POST",
      "path": "/v1/deliveries/{deliveryId}/acceptance",
      "scope": "delivery:accept",
      "status": 202,
      "required": [
        "manifestVersion",
        "acceptedRefs",
        "decision"
      ],
      "sample": {
        "manifestVersion": 1,
        "acceptedRefs": [
          "synthetic-record-001"
        ],
        "decision": "PARTIAL_ACCEPTANCE"
      },
      "response": {
        "acceptanceRef": "synthetic-acceptance-001",
        "status": "RECONCILING",
        "billableEvaluated": false
      },
      "purpose": [
        "Ghi tập chấp nhận và quyết định theo manifest; billing là bước đối soát riêng.",
        "Record accepted sets/decisions against manifests; billing is separately reconciled."
      ],
      "state": [
        "DELIVERED → REVIEW → PARTIAL_ACCEPTANCE / ACCEPTED / CORRECTION. Không tự tạo invoice.",
        "DELIVERED → REVIEW → PARTIAL_ACCEPTANCE / ACCEPTED / CORRECTION. No automatic invoice."
      ],
      "error": [
        "ManifestVersion không khớp 409; tập ngoài manifest hoặc thiếu quyền 422/403.",
        "Manifest version mismatches return 409; out-of-manifest sets or permissions return 422/403."
      ]
    },
    {
      "id": "verify",
      "slug": "evidence-api",
      "title": [
        "Xác minh bằng chứng",
        "Evidence verification"
      ],
      "method": "POST",
      "path": "/v1/evidence/verification",
      "scope": "evidence:verify",
      "status": 200,
      "required": [
        "manifestRef",
        "expectedHash"
      ],
      "sample": {
        "manifestRef": "synthetic-manifest-001",
        "expectedHash": "0000000000000000000000000000000000000000000000000000000000000000"
      },
      "response": {
        "verificationRef": "synthetic-verification-001",
        "integrity": "MATCH",
        "provenance": "NOT_EVALUATED",
        "legalStatus": "NOT_EVALUATED"
      },
      "purpose": [
        "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ý.",
        "Verify integrity against manifest/reference hashes; do not infer provenance or legal status."
      ],
      "state": [
        "CHECKED → MATCH / MISMATCH / INDETERMINATE. Kết quả simulator không là kiểm file thực.",
        "CHECKED → MATCH / MISMATCH / INDETERMINATE. Simulator results do not verify actual files."
      ],
      "error": [
        "Hash sai định dạng 422; quyền thiếu 403; thiếu nguồn tham chiếu cần INDETERMINATE.",
        "Invalid hash formats return 422; insufficient permissions 403; missing reference evidence is INDETERMINATE."
      ]
    },
    {
      "id": "device-command",
      "slug": "device-command",
      "title": [
        "Quyết định phân luồng Flow R",
        "Flow R routing decision"
      ],
      "path": "/v1/device-commands",
      "scope": "devices:command",
      "method": "POST",
      "status": 202,
      "required": [
        "commandId",
        "stationId",
        "sheetId",
        "dossierId",
        "trayId",
        "targetSheetIndex",
        "decisionVersion",
        "deadline"
      ],
      "sample": {
        "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"
      },
      "response": {
        "commandId": "synthetic-command-001",
        "state": "RECEIVED",
        "executionConfirmed": false
      },
      "purpose": [
        "Thiết kế adapter để thảo luận; RECEIVED không xác nhận giấy đã đến khay.",
        "Adapter design for discussion; RECEIVED does not confirm paper arrival."
      ],
      "state": [
        "Trạng thái minh họa; chốt mapping theo contract.",
        "Illustrative states; agree contract mappings."
      ],
      "error": [
        "422 dữ liệu sai; 403 thiếu quyền; 409 khóa/phiên bản; 503 chưa sẵn sàng.",
        "422 invalid data; 403 denied; 409 key/version conflict; 503 unavailable."
      ]
    },
    {
      "id": "payment-request",
      "slug": "payment-request",
      "title": [
        "Yêu cầu thanh toán",
        "Payment request"
      ],
      "path": "/v1/payment-requests",
      "scope": "billing:write",
      "method": "POST",
      "status": 202,
      "required": [
        "acceptanceRef",
        "billingVersion",
        "amountMinor",
        "currency",
        "channel"
      ],
      "sample": {
        "acceptanceRef": "synthetic-acceptance-001",
        "billingVersion": 1,
        "amountMinor": 125000,
        "currency": "VND",
        "channel": "NAPAS_QR_PROPOSED"
      },
      "response": {
        "paymentRequestId": "synthetic-payment-001",
        "state": "PENDING",
        "payableQr": null
      },
      "purpose": [
        "Thiết kế yêu cầu thanh toán từ nghiệm thu; không sinh QR thanh toán thật.",
        "Design payment requests from acceptance; no payable QR is generated."
      ],
      "state": [
        "Trạng thái minh họa; chốt mapping theo contract.",
        "Illustrative states; agree contract mappings."
      ],
      "error": [
        "422 dữ liệu sai; 403 thiếu quyền; 409 khóa/phiên bản; 503 chưa sẵn sàng.",
        "422 invalid data; 403 denied; 409 key/version conflict; 503 unavailable."
      ]
    },
    {
      "id": "payment-status",
      "slug": "payment-status",
      "title": [
        "Trạng thái thanh toán",
        "Payment status"
      ],
      "path": "/v1/payment-requests/{paymentRequestId}",
      "scope": "billing:read",
      "method": "GET",
      "status": 200,
      "required": [],
      "sample": {},
      "response": {
        "paymentRequestId": "synthetic-payment-001",
        "state": "CONFIRMED",
        "providerRef": "synthetic-provider-001",
        "reconciled": false
      },
      "purpose": [
        "Ví dụ confirmation chưa là reconciliation hoặc hóa đơn issued.",
        "Illustrative confirmation is not reconciliation or invoice issuance."
      ],
      "state": [
        "Trạng thái minh họa; chốt mapping theo contract.",
        "Illustrative states; agree contract mappings."
      ],
      "error": [
        "422 dữ liệu sai; 403 thiếu quyền; 409 khóa/phiên bản; 503 chưa sẵn sàng.",
        "422 invalid data; 403 denied; 409 key/version conflict; 503 unavailable."
      ]
    },
    {
      "id": "invoice-request",
      "slug": "invoice-request",
      "title": [
        "Yêu cầu hóa đơn",
        "Invoice request"
      ],
      "path": "/v1/invoice-requests",
      "scope": "billing:write",
      "method": "POST",
      "status": 202,
      "required": [
        "paymentRequestId",
        "acceptanceRef",
        "recipientRef"
      ],
      "sample": {
        "paymentRequestId": "synthetic-payment-001",
        "acceptanceRef": "synthetic-acceptance-001",
        "recipientRef": "synthetic-recipient-001"
      },
      "response": {
        "invoiceRequestId": "synthetic-invoice-001",
        "state": "REQUESTED"
      },
      "purpose": [
        "Đề xuất gửi Trusted Billing; schema/provider mapping cần xác nhận.",
        "Proposed Trusted Billing submission; confirm schemas/provider mapping."
      ],
      "state": [
        "Trạng thái minh họa; chốt mapping theo contract.",
        "Illustrative states; agree contract mappings."
      ],
      "error": [
        "422 dữ liệu sai; 403 thiếu quyền; 409 khóa/phiên bản; 503 chưa sẵn sàng.",
        "422 invalid data; 403 denied; 409 key/version conflict; 503 unavailable."
      ]
    },
    {
      "id": "invoice-status",
      "slug": "invoice-status",
      "title": [
        "Trạng thái hóa đơn",
        "Invoice status"
      ],
      "path": "/v1/invoice-requests/{invoiceRequestId}",
      "scope": "billing:read",
      "method": "GET",
      "status": 200,
      "required": [],
      "sample": {},
      "response": {
        "invoiceRequestId": "synthetic-invoice-001",
        "state": "PROCESSING",
        "documentRef": null
      },
      "purpose": [
        "Theo dõi bất đồng bộ; chưa có chứng từ để tải khi PROCESSING.",
        "Track asynchronous processing; no document is available while PROCESSING."
      ],
      "state": [
        "Trạng thái minh họa; chốt mapping theo contract.",
        "Illustrative states; agree contract mappings."
      ],
      "error": [
        "422 dữ liệu sai; 403 thiếu quyền; 409 khóa/phiên bản; 503 chưa sẵn sàng.",
        "422 invalid data; 403 denied; 409 key/version conflict; 503 unavailable."
      ]
    }
  ],
  "event": {
    "eventId": "synthetic-event-001",
    "eventType": "records.declared",
    "occurredAt": "2026-10-07T00:00:00Z",
    "tenantId": "synthetic-tenant-001",
    "projectId": "synthetic-project-001",
    "objectRef": "synthetic-record-001",
    "version": 1,
    "correlationId": "synthetic-correlation-001"
  }
}