{"openapi":"3.1.0","info":{"title":"Dòng Tiền Pro API","version":"2026-10-19","description":"API công khai của Dòng Tiền Pro: đọc tài khoản, số dư, giao dịch ngân hàng theo thời gian thực.\n\n**Xác thực**: `Authorization: Bearer dt_live_…` (hoặc `dt_test_…` cho dữ liệu thử). Mỗi route ghi quyền cần có ở `x-dt-permission` và scope của khoá ở `x-dt-scope`.\n\n**Phiên bản**: header `DongTien-Version: YYYY-MM-DD`; bỏ trống thì dùng phiên bản ghim khi tạo khoá.\n\n**Lỗi**: `application/problem+json` (RFC 9457) với `code` ổn định. **Phân trang**: con trỏ `cursor`/`next_cursor`. **Ghi an toàn**: header `Idempotency-Key`.","contact":{"name":"Dòng Tiền Pro","url":"https://docs.dongtien.pro"}},"servers":[{"url":"https://api.dongtien.pro","description":"Production"},{"url":"https://api.staging.dongtien.pro","description":"Staging (dữ liệu thử)"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"dt_live_… | dt_test_…","description":"Khoá API `dt_live_…` (dữ liệu thật) hoặc `dt_test_…` (dữ liệu thử), hoặc token OAuth của CLI/MCP."}},"schemas":{"AcceptInvitation":{"type":"object","properties":{"token":{"type":"string","minLength":16,"maxLength":256}},"required":["token"],"example":{"token":"ivt_tok_3f9c2a7e5b1d4c68a0e2f7b9d1c35a46"}},"AcceptedInvitation":{"type":"object","properties":{"membership_id":{"$ref":"#/components/schemas/MemberId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"root_id":{"$ref":"#/components/schemas/OrgId"},"role":{"type":"string"}},"required":["membership_id","org_id","root_id","role"],"description":"Tư cách thành viên vừa được tạo."},"AccessGrant":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AccessGrantId"},"object":{"type":"string","enum":["access_grant"]},"grantor_org_id":{"type":"string","pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Bên cấp: một công ty, hoặc nút gốc của khách (cấp cho mọi công ty của nút gốc đó).","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"grantee_root_id":{"type":"string","pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Bên nhận: nút gốc của văn phòng kế toán.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"role_key":{"type":"string","description":"Vai trò bên nhận có tại công ty được cấp."},"status":{"$ref":"#/components/schemas/AccessGrantStatus"},"requested_by":{"type":"string","enum":["grantor","grantee"],"description":"Bên đề xuất; bên còn lại là bên kích hoạt."},"direction":{"$ref":"#/components/schemas/AccessGrantDirection"},"expires_at":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Hết hiệu lực vào lúc này; `null` = không hết hạn.","example":"2026-10-19T01:30:15Z"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"decided_at":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Lần kích hoạt hoặc thu hồi gần nhất.","example":"2026-10-19T01:30:15Z"},"revoked_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["id","object","grantor_org_id","grantee_root_id","role_key","status","requested_by","direction","expires_at","created_at","decided_at","revoked_at"],"description":"Quyền truy cập chéo giữa văn phòng kế toán và khách hàng."},"AccessGrantDirection":{"type":"string","enum":["given","received"],"description":"`given`: người gọi là bên cấp (dữ liệu của họ được chia sẻ); `received`: người gọi là bên nhận (văn phòng kế toán)."},"AccessGrantId":{"type":"string","pattern":"^grt_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã quyền truy cập chéo (`grt_…`).","example":"grt_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"AccessGrantList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/AccessGrant"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"AccessGrantRole":{"type":"string","enum":["admin","accountant_chief","accountant","developer","viewer","auditor"],"description":"Vai trò bên nhận có tại công ty được cấp; không có `owner`."},"AccessGrantStatus":{"type":"string","enum":["pending","active","revoked"],"description":"`pending`: chờ bên kia kích hoạt; `active`: đang hiệu lực (trừ khi `expires_at` đã qua); `revoked`: đã thu hồi, không khôi phục."},"AccountId":{"type":"string","pattern":"^acc_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã tài khoản ngân hàng (`acc_…`).","example":"acc_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"AccountingPeriod":{"type":"object","properties":{"org_id":{"$ref":"#/components/schemas/OrgId"},"ym":{"type":"string","pattern":"^[0-9]{6}$","description":"Kỳ kế toán dạng YYYYMM."},"state":{"$ref":"#/components/schemas/PeriodState"},"locked_by":{"anyOf":[{"$ref":"#/components/schemas/UserId"},{"type":"null"}]},"locked_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"lock_reason":{"type":["string","null"]},"unlock_requested_by":{"anyOf":[{"$ref":"#/components/schemas/UserId"},{"type":"null"}]},"unlock_requested_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"unlock_reason":{"type":["string","null"]},"last_export_id":{"anyOf":[{"$ref":"#/components/schemas/ExportBatchId"},{"type":"null"}]},"lock_requested_by":{"anyOf":[{"$ref":"#/components/schemas/UserId"},{"type":"null"}]},"lock_request_id":{"type":["string","null"],"pattern":"^apr_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã yêu cầu duyệt khoá đang chờ (dùng cho :approve / :reject).","example":"apr_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"unlock_request_id":{"type":["string","null"],"pattern":"^apr_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã yêu cầu duyệt mở khoá đang chờ (dùng cho :approve / :reject).","example":"apr_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["org_id","ym","state","created_at","updated_at"]},"AiConnectMode":{"type":"string","enum":["public","cf_tunnel","static_ip"],"description":"Đường kết nối tới origin: `public` HTTPS công khai, `cf_tunnel` Cloudflare Tunnel của khách, `static_ip` qua IP tĩnh dt-egress."},"AiConnectionId":{"type":"string","pattern":"^aip_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã kết nối AI (`aip_…`).","example":"aip_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"AiConnectionState":{"type":"string","enum":["new","ok","degraded","error","blocked"],"description":"Trạng thái kết nối: `new` (mới tạo/chờ kiểm tra), `ok` (hoạt động), `degraded` (chập chờn), `error` (lỗi), `blocked` (bị net-guard chặn SSRF)."},"AiDataMode":{"type":"string","enum":["platform_ok","byok_only"],"description":"`byok_only`: dữ liệu org chỉ gửi tới origin của khách, không bao giờ qua model nền tảng."},"AiMode":{"type":"string","enum":["off","platform","byok"],"description":"Chế độ AI: `off` (chưa bật), `platform` (Dòng Tiền Pro AI), `byok` (kết nối riêng)."},"Allocation":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AllocationId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"root_id":{"type":"string"},"tx_id":{"$ref":"#/components/schemas/TxId"},"tx_occurred_at":{"$ref":"#/components/schemas/Timestamp"},"tx_amount":{"$ref":"#/components/schemas/Vnd"},"state":{"type":"string","enum":["draft","pending_approval","approved","rejected","withdrawn","reversed"]},"maker_user_id":{"anyOf":[{"$ref":"#/components/schemas/UserId"},{"type":"null"}]},"checker_user_id":{"anyOf":[{"$ref":"#/components/schemas/UserId"},{"type":"null"}]},"created_by_kind":{"type":"string","enum":["system","user","api_key"],"default":"user"},"self_approved":{"type":"boolean","default":false},"group_id":{"type":["string","null"]},"overpay_amount":{"$ref":"#/components/schemas/Vnd"},"rounding_diff":{"$ref":"#/components/schemas/Vnd"},"overpay_handling":{"type":["string","null"],"enum":["customer_advance","refund_reminder","allocate_other",null]},"reject_reason":{"type":["string","null"],"enum":["wrong_invoice","wrong_amount","need_documents","other",null]},"reject_note":{"type":["string","null"]},"approval_request_id":{"anyOf":[{"$ref":"#/components/schemas/ApprovalRequestId"},{"type":"null"}]},"reversed_by_allocation_id":{"anyOf":[{"$ref":"#/components/schemas/AllocationId"},{"type":"null"}]},"reverses_allocation_id":{"anyOf":[{"$ref":"#/components/schemas/AllocationId"},{"type":"null"}]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/AllocationLine"}},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","org_id","tx_id","tx_amount","state","lines","created_at","updated_at","created_by_kind","self_approved","overpay_amount","rounding_diff"],"description":"Bản ghi phân bổ đối soát (maker-checker)."},"AllocationId":{"type":"string","pattern":"^alc_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã phân bổ đối soát (`alc_…`).","example":"alc_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"AllocationLine":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AllocationLineId"},"allocation_id":{"$ref":"#/components/schemas/AllocationId"},"target_type":{"type":"string","enum":["invoice","order","expected_payment"]},"target_id":{"type":"string"},"invoice_ref_id":{"anyOf":[{"$ref":"#/components/schemas/InvoiceRefId"},{"type":"null"}]},"expected_payment_id":{"anyOf":[{"$ref":"#/components/schemas/ExpectedPaymentId"},{"type":"null"}]},"amount":{"$ref":"#/components/schemas/Vnd"},"note":{"type":["string","null"]},"writeback_state":{"type":"string","enum":["pending","retry_wait","posted","failed","reversed"]},"writeback_attempts":{"type":"integer"},"created_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","allocation_id","target_type","target_id","amount","created_at"],"description":"Một dòng phân bổ tới hoá đơn hoặc đơn hàng."},"AllocationLineId":{"type":"string","pattern":"^all_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã dòng phân bổ (`all_…`).","example":"all_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"AllocationList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Allocation"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"AndroidReleaseManifest":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AppReleaseId"},"object":{"type":"string","enum":["android_release"]},"channel":{"type":"string","enum":["stable","beta"]},"version":{"type":"string","example":"1.4.3"},"version_code":{"type":"integer","exclusiveMinimum":0},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 (hex) của APK."},"size":{"type":"integer","exclusiveMinimum":0,"description":"Byte."},"url":{"type":"string","format":"uri","description":"Địa chỉ tải APK (R2 `dl.dongtien.pro`)."},"signature":{"type":"string","pattern":"^[0-9a-f]{128}$","description":"Ed25519 (hex, 64 byte) trên chuỗi `DTM1…` mô tả ở đầu tài liệu."},"mandatory_by":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Sau mốc này app hiện màn cập nhật bắt buộc (vẫn nhận và xếp hàng tin).","example":"2026-10-19T01:30:15Z"},"min_supported_version_code":{"type":"integer","minimum":0,"description":"Sau `mandatory_by` + 7 ngày ân hạn, phiên bản thấp hơn nhận `426 upgrade_required`."},"rollout_pct":{"type":"integer","minimum":0,"maximum":100},"rollout_salt":{"type":"string"},"state":{"$ref":"#/components/schemas/AppReleaseState"},"release_notes":{"type":"array","items":{"type":"string"}},"published_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["id","object","channel","version","version_code","sha256","size","url","signature","mandatory_by","min_supported_version_code","rollout_pct","rollout_salt","state","release_notes","published_at"],"description":"Manifest bản APK mới nhất đủ điều kiện công bố (`state` ≠ `draft`)."},"ApiKey":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ApiKeyId"},"name":{"type":"string"},"env":{"type":"string","enum":["live","test"],"description":"`live`: dữ liệu thật; `test`: sandbox."},"display":{"type":"string","description":"`dt_live_` + vài ký tự đầu + `••••` + 4 ký tự cuối: phần duy nhất được hiện lại."},"start":{"type":"string"},"last4":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"},"description":"Các scope khoá mang (xem danh mục scope)."},"all_companies":{"type":"boolean","description":"Mọi công ty của tổ chức (kể cả công ty thêm sau), trừ công ty cô lập cứng."},"company_ids":{"type":"array","items":{"$ref":"#/components/schemas/OrgId"},"description":"Công ty khoá được dùng; rỗng khi `all_companies`."},"bank_account_ids":{"type":["array","null"],"items":{"$ref":"#/components/schemas/AccountId"},"description":"Chỉ các tài khoản này; `null` = mọi tài khoản của công ty khoá chạm tới."},"ip_allowlist":{"type":"array","items":{"type":"string"},"description":"Địa chỉ IPv4/IPv6 hoặc CIDR được phép; rỗng = không giới hạn."},"pinned_version":{"type":["string","null"],"description":"Phiên bản API (`YYYY-MM-DD`) khoá được ghim."},"expires_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"extended_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"last_used_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"last_used_ip":{"type":["string","null"]},"state":{"type":"string","enum":["active","revoked","expired"]},"rotated_from_id":{"type":["string","null"],"pattern":"^apk_[0-9a-hjkmnp-tv-z]{26}$","description":"Khoá tiền nhiệm khi đây là khoá thay thế sau `:rotate`.","example":"apk_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"grace_until":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Khoá cũ vẫn dùng được đến thời điểm này sau khi xoay.","example":"2026-10-19T01:30:15Z"},"created_by":{"$ref":"#/components/schemas/UserId"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"revoked_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"revoked_reason":{"type":["string","null"]}},"required":["id","name","env","display","start","last4","scopes","all_companies","company_ids","bank_account_ids","ip_allowlist","pinned_version","expires_at","extended_at","last_used_at","last_used_ip","state","rotated_from_id","grace_until","created_by","created_at","revoked_at","revoked_reason"],"description":"Khoá API (không bao giờ chứa bí mật)."},"ApiKeyCall":{"type":"object","properties":{"at":{"$ref":"#/components/schemas/Timestamp"},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"integer"},"ms":{"type":"integer","description":"Thời gian xử lý (mili giây)."},"ip":{"type":["string","null"]}},"required":["at","method","path","status","ms","ip"],"description":"Một lệnh gọi mẫu của khoá: phương thức, đường dẫn, mã trạng thái; không bao giờ có nội dung."},"ApiKeyCallList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyCall"}},"next_cursor":{"type":"null"},"has_more":{"type":"boolean","enum":[false]}},"required":["object","data","next_cursor","has_more"]},"ApiKeyId":{"type":"string","pattern":"^apk_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã khoá API (`apk_…`).","example":"apk_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"ApiKeyIssued":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ApiKeyId"},"name":{"type":"string"},"env":{"type":"string","enum":["live","test"],"description":"`live`: dữ liệu thật; `test`: sandbox."},"display":{"type":"string","description":"`dt_live_` + vài ký tự đầu + `••••` + 4 ký tự cuối: phần duy nhất được hiện lại."},"start":{"type":"string"},"last4":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"},"description":"Các scope khoá mang (xem danh mục scope)."},"all_companies":{"type":"boolean","description":"Mọi công ty của tổ chức (kể cả công ty thêm sau), trừ công ty cô lập cứng."},"company_ids":{"type":"array","items":{"$ref":"#/components/schemas/OrgId"},"description":"Công ty khoá được dùng; rỗng khi `all_companies`."},"bank_account_ids":{"type":["array","null"],"items":{"$ref":"#/components/schemas/AccountId"},"description":"Chỉ các tài khoản này; `null` = mọi tài khoản của công ty khoá chạm tới."},"ip_allowlist":{"type":"array","items":{"type":"string"},"description":"Địa chỉ IPv4/IPv6 hoặc CIDR được phép; rỗng = không giới hạn."},"pinned_version":{"type":["string","null"],"description":"Phiên bản API (`YYYY-MM-DD`) khoá được ghim."},"expires_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"extended_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"last_used_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"last_used_ip":{"type":["string","null"]},"state":{"type":"string","enum":["active","revoked","expired"]},"rotated_from_id":{"type":["string","null"],"pattern":"^apk_[0-9a-hjkmnp-tv-z]{26}$","description":"Khoá tiền nhiệm khi đây là khoá thay thế sau `:rotate`.","example":"apk_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"grace_until":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Khoá cũ vẫn dùng được đến thời điểm này sau khi xoay.","example":"2026-10-19T01:30:15Z"},"created_by":{"$ref":"#/components/schemas/UserId"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"revoked_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"revoked_reason":{"type":["string","null"]},"key":{"type":"string","description":"Khoá đầy đủ, chỉ hiện một lần. Hãy lưu ngay: không thể lấy lại."}},"required":["id","name","env","display","start","last4","scopes","all_companies","company_ids","bank_account_ids","ip_allowlist","pinned_version","expires_at","extended_at","last_used_at","last_used_ip","state","rotated_from_id","grace_until","created_by","created_at","revoked_at","revoked_reason","key"],"description":"Khoá vừa cấp, kèm bí mật hiện một lần. Phản hồi có `Cache-Control: no-store`."},"ApiKeyList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"AppReleaseId":{"type":"string","pattern":"^rel_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã bản phát hành ứng dụng (`rel_…`).","example":"rel_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"AppReleaseState":{"type":"string","enum":["draft","staged","stable","mandatory","halted"]},"ApplyMappingTemplateBody":{"type":"object","properties":{"template_id":{"type":"string","minLength":1},"profile_id":{"type":"string","format":"uuid"}},"required":["template_id"],"example":{"template_id":"tt133-standard"}},"ApplyMappingTemplateResult":{"type":"object","properties":{"approval_id":{"$ref":"#/components/schemas/ApprovalRequestId"},"rule_ids":{"type":"array","items":{"$ref":"#/components/schemas/MappingRuleId"}},"applied_count":{"type":"integer"}},"required":["approval_id","rule_ids","applied_count"]},"Approval":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ApprovalRequestId"},"company_id":{"$ref":"#/components/schemas/OrgId"},"kind":{"type":"string","enum":["allocation","obligation_allocation","partner_create","split_rule_version","payout_variance_recognition","export_batch","period_lock","period_unlock","mapping_change","category_retro_apply","tx_verify_manual","quarantine_release","merge_locked_period","shift_close","company_delete","flag_change","plan_change"]},"subject_type":{"type":"string"},"subject_id":{"type":"string"},"state":{"type":"string","enum":["pending","approved","rejected","withdrawn","expired"]},"maker_user_id":{"type":"string","pattern":"^usr_[0-9a-hjkmnp-tv-z]{26}$","description":"Người đề nghị.","example":"usr_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"checker_user_id":{"type":["string","null"],"pattern":"^usr_[0-9a-hjkmnp-tv-z]{26}$","description":"Người quyết định; `null` khi chưa quyết định.","example":"usr_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"self_approved":{"type":"boolean","description":"Người đề nghị tự duyệt theo chính sách một người duyệt."},"reason":{"type":["string","null"]},"decision_reason":{"type":["string","null"]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"decided_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"expires_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","company_id","kind","subject_type","subject_id","state","maker_user_id","checker_user_id","self_approved","reason","decision_reason","created_at","decided_at","expires_at"],"description":"Yêu cầu phê duyệt hai người (người đề nghị ≠ người duyệt)."},"ApprovalList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Approval"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"ApprovalReadiness":{"type":"object","properties":{"company_id":{"$ref":"#/components/schemas/OrgId"},"eligible_approvers":{"type":"integer","description":"Số người có thể duyệt tại công ty."},"has_chief":{"type":"boolean"},"self_approval_enabled":{"type":"boolean"},"self_approval_allowed":{"type":"boolean"},"solo_self_approve_limit":{"type":["string","null"],"description":"Hạn mức tự duyệt (VND, dạng chuỗi số); `null` khi không đặt."},"auto_disabled":{"type":"boolean"},"needs_more_approvers":{"type":"boolean","description":"Công ty chưa có ai ngoài người đề nghị có thể duyệt (hiện biểu ngữ cảnh báo)."}},"required":["company_id","eligible_approvers","has_chief","self_approval_enabled","self_approval_allowed","solo_self_approve_limit","auto_disabled","needs_more_approvers"],"description":"Công ty đã đủ người duyệt chưa, và điều kiện tự duyệt của một người."},"ApprovalRequestId":{"type":"string","pattern":"^apr_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã yêu cầu duyệt (`apr_…`).","example":"apr_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"AuditEvent":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AuditEventId"},"ts":{"$ref":"#/components/schemas/Timestamp"},"company_id":{"type":["string","null"],"pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Công ty của dòng; `null` với dòng ở cấp tổ chức gốc.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"actor":{"type":"object","properties":{"type":{"type":"string","enum":["human","ai","mcp_client","api_key","system","staff","staff_impersonation","integration","device","oauth"]},"id":{"type":["string","null"],"description":"Mã định danh của chủ thể: người dùng, khoá API hoặc tên tác vụ hệ thống."},"role":{"type":["string","null"],"description":"Vai trò của chủ thể tại công ty lúc thực hiện."}},"required":["type","id","role"]},"action":{"type":"string","description":"Hành động, vd. `member.role_change`."},"object":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":["string","null"]}},"required":["type","id"]},"result":{"type":"string","enum":["success","proposed","pending","sensitive","alert","denied"]},"reason":{"type":["string","null"]},"note":{"type":["string","null"]},"diff":{"type":"object","properties":{"before":{},"after":{}}},"sens":{"type":"boolean","description":"Hành động nhạy cảm (đã báo cho chủ sở hữu)."},"seq":{"type":"integer","description":"Số thứ tự trong chuỗi băm của tổ chức."},"integrity":{"type":"object","properties":{"prev_hash":{"type":"string"},"hash":{"type":"string"},"chain_ok":{"type":["boolean","null"],"description":"`null` khi trang trải quá nhiều mắt xích để kiểm tra ngay (dùng tác vụ kiểm tra toàn vẹn)."},"verified_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["prev_hash","hash","chain_ok","verified_at"]}},"required":["id","ts","company_id","actor","action","object","result","reason","note","diff","sens","seq","integrity"],"description":"Một dòng nhật ký kiểm toán, kèm bằng chứng toàn vẹn."},"AuditEventId":{"type":"string","pattern":"^aud_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã dòng nhật ký kiểm toán (`aud_…`).","example":"aud_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"AuditEventList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditEvent"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"Balance":{"type":"object","properties":{"account_id":{"$ref":"#/components/schemas/AccountId"},"object":{"type":"string","enum":["balance"]},"reported":{"type":["object","null"],"properties":{"amount":{"$ref":"#/components/schemas/Vnd"},"as_of":{"$ref":"#/components/schemas/Timestamp"},"source":{"type":"string","enum":["openapi","statement","sms_verified","sms_provisional","computed"],"description":"Nguồn của số dư báo cáo."}},"required":["amount","as_of","source"],"description":"Số dư do ngân hàng/sao kê báo cáo; `null` nếu chưa nhận được."},"computed":{"type":["object","null"],"properties":{"amount":{"$ref":"#/components/schemas/Vnd"},"as_of":{"$ref":"#/components/schemas/Timestamp"}},"required":["amount","as_of"],"description":"Số dư tính từ mốc neo + giao dịch đã xác thực; `null` nếu chưa có mốc neo."},"difference":{"type":["integer","null"],"minimum":-9007199254740991,"maximum":9007199254740991,"description":"`reported − computed` khi có cả hai.","example":4500000},"trust":{"$ref":"#/components/schemas/BalanceChainTrust"},"evidence":{"type":"object","properties":{"anchor_state":{"type":["string","null"],"enum":["ok","mismatch","gap_suspected",null]},"anchor_as_of":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"transactions_since_anchor":{"type":"integer","minimum":0}},"required":["anchor_state","anchor_as_of","transactions_since_anchor"]},"as_of":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Thời điểm tính của phản hồi này.","example":"2026-10-19T01:30:15Z"}},"required":["account_id","object","reported","computed","difference","trust","evidence","as_of"],"description":"Số dư một tài khoản: báo cáo và tính toán tách riêng."},"BalanceChainTrust":{"type":"string","enum":["consistent","mismatch","gap_suspected","unchecked"],"description":"Chuỗi giao dịch có nhất quán với số dư báo cáo hay không: `consistent` khớp, `mismatch` lệch, `gap_suspected` nghi thiếu giao dịch, `unchecked` chưa có mốc đối chiếu. Chỉ là kiểm tra nhất quán, không phải xác minh của ngân hàng."},"BalanceList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Balance"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"BankAccount":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AccountId"},"object":{"type":"string","enum":["bank_account"]},"company":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/OrgId"},"mst":{"type":["string","null"],"description":"Mã số thuế của công ty."}},"required":["id","mst"]},"bank":{"type":"object","properties":{"code":{"type":"string","description":"Mã ngân hàng trong danh mục (vd. `ACB`).","example":"ACB"},"name":{"type":"string","example":"Ngân hàng TMCP Á Châu"}},"required":["code","name"]},"label":{"type":"string","description":"Nhãn hiển thị, vd. `ACB •••4521`.","example":"ACB •••4521"},"account_number_masked":{"type":"string","pattern":"^•+\\d{4}$","description":"Số tài khoản đã che, chỉ lộ 4 số cuối.","example":"•••4521"},"last4":{"type":"string","pattern":"^\\d{4}$","example":"4521"},"holder_name":{"type":["string","null"]},"type":{"type":"string","enum":["business","virtual_sub","savings"]},"state":{"type":"string","enum":["active","stopped_receiving","archived"]},"currency":{"type":"string","enum":["VND"]},"va_number":{"type":["string","null"],"description":"Số tài khoản định danh (VA) nếu ngân hàng cấp."},"balance":{"type":"object","properties":{"account_id":{"$ref":"#/components/schemas/AccountId"},"object":{"type":"string","enum":["balance"]},"reported":{"type":["object","null"],"properties":{"amount":{"$ref":"#/components/schemas/Vnd"},"as_of":{"$ref":"#/components/schemas/Timestamp"},"source":{"type":"string","enum":["openapi","statement","sms_verified","sms_provisional","computed"],"description":"Nguồn của số dư báo cáo."}},"required":["amount","as_of","source"],"description":"Số dư do ngân hàng/sao kê báo cáo; `null` nếu chưa nhận được."},"computed":{"type":["object","null"],"properties":{"amount":{"$ref":"#/components/schemas/Vnd"},"as_of":{"$ref":"#/components/schemas/Timestamp"}},"required":["amount","as_of"],"description":"Số dư tính từ mốc neo + giao dịch đã xác thực; `null` nếu chưa có mốc neo."},"difference":{"type":["integer","null"],"minimum":-9007199254740991,"maximum":9007199254740991,"description":"`reported − computed` khi có cả hai.","example":4500000},"trust":{"$ref":"#/components/schemas/BalanceChainTrust"},"evidence":{"type":"object","properties":{"anchor_state":{"type":["string","null"],"enum":["ok","mismatch","gap_suspected",null]},"anchor_as_of":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"transactions_since_anchor":{"type":"integer","minimum":0}},"required":["anchor_state","anchor_as_of","transactions_since_anchor"]},"as_of":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Thời điểm tính của phản hồi này.","example":"2026-10-19T01:30:15Z"}},"required":["account_id","object","reported","computed","difference","trust","evidence","as_of"],"description":"Chỉ có khi `expand=balance`."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"archived_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["id","object","company","bank","label","account_number_masked","last4","holder_name","type","state","currency","va_number","created_at","archived_at"],"description":"Tài khoản ngân hàng. Số tài khoản luôn được che."},"BankAccountGlMap":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"$ref":"#/components/schemas/OrgId"},"bank_account_id":{"$ref":"#/components/schemas/AccountId"},"profile_id":{"type":"string","format":"uuid"},"gl_code":{"type":"string","description":"Mã tài khoản kế toán (ví dụ: 1121)."},"code_misa":{"type":["string","null"],"description":"Mã tương ứng trong MISA."},"code_fast":{"type":["string","null"],"description":"Mã tương ứng trong Fast."},"state":{"type":"string","enum":["pending_approval","active","disabled"],"default":"active"},"effective_from":{"$ref":"#/components/schemas/Date"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","org_id","bank_account_id","profile_id","gl_code","effective_from","created_at","updated_at","state"]},"BankAccountList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/BankAccount"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"BankAccountRecipient":{"type":"object","properties":{"bin":{"type":"string","description":"Mã BIN ngân hàng thụ hưởng (VietQR)."},"bank_name":{"type":"string","description":"Tên ngân hàng ngắn gọn."},"account_no":{"type":"string","description":"Số tài khoản nhận tiền."},"account_name":{"type":"string","description":"Tên chủ tài khoản."}},"required":["bin","bank_name","account_no","account_name"],"description":"Tài khoản nhận tiền chính thức của nền tảng."},"Bill":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/BillId"},"object":{"type":"string","enum":["bill"]},"bill_ref":{"type":"string"},"state":{"$ref":"#/components/schemas/BillState"},"amount":{"$ref":"#/components/schemas/PositiveVnd"},"payment_method":{"type":"string","enum":["transfer","cash"]},"source":{"type":"string","enum":["pos_api","manual"]},"counter":{"$ref":"#/components/schemas/CounterRef"},"store":{"$ref":"#/components/schemas/StoreRef"},"shift_id":{"anyOf":[{"$ref":"#/components/schemas/ShiftId"},{"type":"null"}]},"payment_request":{"type":["object","null"],"properties":{"id":{"$ref":"#/components/schemas/PaymentRequestId"},"object":{"type":"string","enum":["payment_request"]},"company_id":{"$ref":"#/components/schemas/OrgId"},"memo_code":{"type":"string","pattern":"^DTP[0-9A-HJKMNP-TV-Z]{6}$"},"state":{"$ref":"#/components/schemas/PaymentRequestState"},"amount":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":9007199254740991,"description":"`null`: khách tự nhập số tiền.","example":4500000},"locked_amount":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":9007199254740991,"description":"Số tiền khoá trong QR hiện hành (khác `amount` sau `:resend-remainder`).","example":4500000},"received_verified":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Tổng tiền đã xác thực đã gắn vào yêu cầu."},"received_provisional":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Tổng tiền tạm tính (chưa tính là đã nhận)."},"short_by":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Còn thiếu (chỉ khi `short`/`provisional`)."},"over_by":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Thừa so với `amount` (chỉ khi `over`)."},"allow_partial":{"type":"boolean"},"expires_at":{"$ref":"#/components/schemas/Timestamp"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"opened_at":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Lần đầu khách mở trang thanh toán.","example":"2026-10-19T01:30:15Z"},"paid_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"late_verified":{"type":"boolean","description":"`true`: được xác thực muộn sau khi hết hạn (A2) nhưng vẫn gắn vào yêu cầu."},"overpay_resolved_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"cancelled_reason":{"type":["string","null"]},"account":{"$ref":"#/components/schemas/PaymentAccountRef"},"store":{"anyOf":[{"$ref":"#/components/schemas/StoreRef"},{"type":"null"}]},"counter":{"anyOf":[{"$ref":"#/components/schemas/CounterRef"},{"type":"null"}]},"ref":{"type":["string","null"]},"customer_name":{"type":["string","null"]},"note_internal":{"type":["string","null"]},"source":{"type":"string","pattern":"^(link|pos|api|qr_dynamic|integration:[a-z0-9_]{3,40})$"},"created_by":{"anyOf":[{"$ref":"#/components/schemas/UserId"},{"type":"null"}]},"pay_url":{"type":"string","format":"uri","description":"Trang thanh toán công khai `pay.dongtien.pro/r/{mã}`."},"qr":{"type":"object","properties":{"emv":{"type":"string","description":"Chuỗi VietQR (EMVCo) để vẽ mã QR; số tiền khoá khi `locked_amount` có giá trị."}},"required":["emv"]},"warnings":{"type":"array","items":{"type":"string","enum":["ACCOUNT_PROVISIONAL_ONLY"]}},"version":{"type":"integer","description":"Tăng mỗi lần đổi trạng thái; dùng để phát hiện cập nhật cũ."}},"required":["id","object","company_id","memo_code","state","amount","locked_amount","received_verified","received_provisional","short_by","over_by","allow_partial","expires_at","created_at","opened_at","paid_at","late_verified","overpay_resolved_at","cancelled_reason","account","store","counter","ref","customer_name","note_internal","source","created_by","pay_url","qr","warnings","version"],"description":"Yêu cầu thanh toán của bill (QR). `null` với bill tiền mặt."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"paid_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["id","object","bill_ref","state","amount","payment_method","source","counter","store","shift_id","payment_request","created_at","paid_at"],"description":"Bill của POS/quầy gắn với một yêu cầu thanh toán."},"BillId":{"type":"string","pattern":"^bil_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã bill của quầy (`bil_…`).","example":"bil_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"BillList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Bill"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"BillState":{"type":"string","enum":["waiting","paid","expired","cash_paid","cancelled"]},"BillingInfo":{"type":"object","properties":{"tax_id":{"type":["string","null"],"default":null,"description":"Mã số thuế doanh nghiệp."},"company_name":{"type":["string","null"],"default":null,"description":"Tên doanh nghiệp trên hoá đơn GTGT."},"invoice_address":{"type":["string","null"],"default":null,"description":"Địa chỉ nhận hoá đơn GTGT."},"invoice_email":{"type":["string","null"],"format":"email","default":null,"description":"Email nhận hoá đơn GTGT điện tử."},"contact_name":{"type":["string","null"],"default":null},"contact_email":{"type":["string","null"],"format":"email","default":null}},"description":"Thông tin xuất hoá đơn tài chính của tổ chức.","required":["tax_id","company_name","invoice_address","invoice_email","contact_name","contact_email"]},"BillingInvoice":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/BillingInvoiceId"},"code":{"type":"string","description":"Mã hoá đơn hiển thị, ví dụ DTP-INV-2610."},"period":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"tx_count":{"type":"integer","minimum":0,"description":"Tổng giao dịch trong kỳ."},"billed_count":{"type":"integer","minimum":0,"description":"Số giao dịch tính phí ngoài quota."},"subtotal_vnd":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Tiền trước thuế: giá theo bậc (đã gồm VAT) trừ phần VAT tách ra.","example":4500000},"vat_percent":{"type":"integer","minimum":0,"description":"Tỷ lệ VAT (%)."},"vat_vnd":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Tiền thuế VAT nằm trong giá theo bậc (subtotal_vnd + vat_vnd = giá theo bậc, VAT không cộng thêm).","example":4500000},"credit_deducted_vnd":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Credit dịch vụ đã tự động trừ.","example":4500000},"total_vnd":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Tổng tiền còn phải thanh toán sau khi trừ credit: subtotal_vnd + vat_vnd - credit_deducted_vnd.","example":4500000},"received_vnd":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Số tiền đã nhận qua VietQR.","example":4500000},"state":{"type":"string","enum":["accruing","open","paid","overdue","void","free_tier"]},"due_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"paid_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"memo_code":{"type":["string","null"],"description":"Mã nội dung DTP… gắn với hoá đơn này."},"vat_invoice_ref":{"type":["string","null"],"description":"Số hoá đơn GTGT điện tử (hoadon.pro)."},"vat_issued_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","code","period","tx_count","billed_count","subtotal_vnd","vat_percent","vat_vnd","credit_deducted_vnd","total_vnd","received_vnd","state","due_at","paid_at","memo_code","vat_invoice_ref","vat_issued_at","created_at","updated_at"],"description":"Hoá đơn dịch vụ Dòng Tiền Pro theo tháng."},"BillingInvoiceId":{"type":"string","pattern":"^bin_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã hoá đơn thanh toán (`bin_…`).","example":"bin_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"BillingInvoiceList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/BillingInvoice"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"BillingMeter":{"type":"object","properties":{"period":{"type":"string","pattern":"^\\d{4}-\\d{2}$","description":"Kỳ đo lường YYYY-MM (giờ VN)."},"used":{"type":"integer","minimum":0,"description":"Số giao dịch đã xác thực trong kỳ."},"quota":{"type":"integer","minimum":0,"description":"Số giao dịch miễn phí trong gói."},"today":{"type":"integer","minimum":0,"description":"Số giao dịch tính đến hiện tại trong ngày."},"projected":{"type":"integer","minimum":0,"description":"Dự kiến số giao dịch cuối tháng."},"estimated_fee_vnd":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Ước tính phí phát sinh kỳ hiện tại (giá theo bậc, đã gồm VAT).","example":4500000},"spend_cap_vnd":{"type":["integer","null"],"minimum":-9007199254740991,"maximum":9007199254740991,"description":"Trần chi tiêu do khách đặt (null = không đặt).","example":4500000},"capped":{"type":"boolean","description":"true khi đã vượt trần chi tiêu."},"is_illustrative":{"type":"boolean","description":"true khi giá và phí còn gắn nhãn minh hoạ."}},"required":["period","used","quota","today","projected","estimated_fee_vnd","spend_cap_vnd","capped","is_illustrative"],"description":"Thanh đo hạn mức sử dụng và dự báo chi phí."},"BulkNote":{"type":"object","properties":{"tx_ids":{"type":"array","items":{"$ref":"#/components/schemas/TxId"},"minItems":1,"maxItems":100},"note":{"type":["string","null"],"maxLength":2000,"description":"Đặt ghi chú; `null` xoá ghi chú."},"add_tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"maxItems":20},"remove_tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"maxItems":20}},"required":["tx_ids"]},"BulkNoteResult":{"type":"object","properties":{"object":{"type":"string","enum":["bulk_result"]},"updated":{"type":"integer","minimum":0},"results":{"type":"array","items":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/TxId"},"ok":{"type":"boolean"},"error":{"type":"string","enum":["not_found","rejected_transaction"]}},"required":["id","ok"]}}},"required":["object","updated","results"],"description":"Kết quả từng giao dịch (giao dịch không thấy được → `not_found`)."},"CancelOrgDeletion":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"description":"Lý do huỷ yêu cầu."}},"example":{"reason":"Gửi nhầm công ty."}},"CancelPaymentRequest":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"example":{"reason":"Khách đổi ý, không mua nữa"}},"Category":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"anyOf":[{"$ref":"#/components/schemas/OrgId"},{"type":"null"}]},"key":{"type":"string","minLength":1,"maxLength":64},"name_vn":{"type":"string","minLength":1,"maxLength":120},"direction":{"$ref":"#/components/schemas/CategoryDirection"},"system":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","org_id","key","name_vn","direction","system","created_at","updated_at"],"description":"Danh mục thu chi dòng tiền."},"CategoryDirection":{"type":"string","enum":["in","out"],"description":"Chiều dòng tiền: `in` (thu) hoặc `out` (chi)."},"CategoryRule":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/CategoryRuleId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"seq_no":{"type":"integer"},"name":{"type":"string","minLength":1,"maxLength":120},"conds":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["content","counterparty_mst","counterparty_name","recipient_account_in_list","amount","account","direction"]},"op":{"type":"string","enum":["contains","starts_with","regex","eq","in","gte"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"array","items":{"type":"string"}}]},"join":{"type":"string","enum":["and","or"],"default":"and"}},"required":["field","op","value"]}},"direction":{"anyOf":[{"$ref":"#/components/schemas/CategoryDirection"},{"type":"null"}]},"category_id":{"type":["string","null"],"format":"uuid"},"action":{"type":"string","enum":["assign","tag_review"],"default":"assign"},"scope":{"type":"object","additionalProperties":{},"default":{}},"source":{"type":"string","enum":["user","ai_suggested","system_default"],"default":"user"},"ai_confidence":{"type":["number","null"],"minimum":0,"maximum":1},"approved_by":{"type":["string","null"],"format":"uuid"},"locked":{"type":"boolean","default":false},"enabled":{"type":"boolean","default":true},"applied_count":{"type":"integer","default":0},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","org_id","seq_no","name","conds","direction","category_id","ai_confidence","approved_by","created_at","updated_at","action","scope","source","locked","enabled","applied_count"],"description":"Quy tắc tự động phân loại giao dịch."},"CategoryRuleId":{"type":"string","pattern":"^crl_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã quy tắc phân loại danh mục (`crl_…`).","example":"crl_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"ChannelTestId":{"type":"string","pattern":"^cht_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã lần gửi thử kênh (`cht_…`).","example":"cht_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"CommerceOrder":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"integration_id":{"$ref":"#/components/schemas/IntegrationId"},"external_order_id":{"type":"string"},"event":{"type":"string"},"amount":{"$ref":"#/components/schemas/Vnd"},"currency":{"type":"string","enum":["VND"],"default":"VND"},"customer_ref":{"type":"string","description":"Thông tin khách hàng đã băm SHA-256 (tuân thủ PDPL/GDPR)"},"expected_payment_id":{"type":["string","null"],"format":"uuid"},"payment_request_id":{"anyOf":[{"$ref":"#/components/schemas/PaymentRequestId"},{"type":"null"}]},"writeback_state":{"$ref":"#/components/schemas/CommerceOrderWritebackState"},"writeback_attempts":{"type":"integer","minimum":0,"default":0},"writeback_error":{"type":["string","null"]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","integration_id","external_order_id","event","amount","customer_ref","writeback_state","created_at","updated_at","currency","writeback_attempts"],"description":"Đơn hàng từ nền tảng thương mại điện tử (Woo, Haravan, Shopify)."},"CommerceOrderList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/CommerceOrder"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"CommerceOrderWritebackState":{"type":"string","enum":["pending","done","failed"],"description":"Trạng thái ghi nhận ngược lại đơn hàng ở cửa hàng (Woo/Shopify/Haravan)."},"CounterId":{"type":"string","pattern":"^ctr_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã quầy thu ngân (`ctr_…`).","example":"ctr_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"CounterRef":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/CounterId"},"name":{"type":"string"},"slug":{"type":"string"}},"required":["id","name","slug"]},"CounterpartyCodeEntry":{"type":"object","properties":{"counterparty_id":{"$ref":"#/components/schemas/CounterpartyId"},"name":{"type":"string"},"mst":{"type":["string","null"]},"target":{"$ref":"#/components/schemas/CounterpartyCodeTarget"},"code":{"type":"string","description":"Mã sẽ xuất: mã đã lưu, hoặc mã suy ra từ MST/tên khi chưa lưu."},"source":{"type":"string","enum":["saved","derived"]},"max_len":{"type":"integer","description":"Độ dài tối đa của mã trên đích."}},"required":["counterparty_id","name","mst","target","code","source","max_len"]},"CounterpartyCodeList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/CounterpartyCodeEntry"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"CounterpartyCodeTarget":{"type":"string","enum":["misa_amis","misa_sme","fast","excel"],"description":"Phần mềm kế toán đích của mã đối tượng."},"CounterpartyId":{"type":"string","pattern":"^cpt_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã đối tác (`cpt_…`).","example":"cpt_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"CounterpartyList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/CounterpartyId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"name":{"type":"string"},"name_norm":{"type":"string"},"kind":{"type":"string","enum":["customer","vendor","both","retail_customer","marketplace","other"]},"tax_code":{"type":["string","null"]},"tax_status":{"type":["string","null"]},"tax_status_checked_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"tax_status_stale":{"type":"boolean"},"address":{"type":["string","null"]},"phone":{"type":["string","null"]},"email":{"type":["string","null"]},"notes":{"type":["string","null"]},"bank_accounts":{"type":"array","items":{"type":"object","properties":{"bank_code":{"type":"string"},"account_number":{"type":"string"},"account_holder":{"type":"string"}},"required":["bank_code","account_number"]},"default":[]},"total_90d":{"$ref":"#/components/schemas/Vnd"},"tx_count_90d":{"type":"integer","default":0},"last_tx_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["id","org_id","name","name_norm","kind"]}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"CoverageRecommendation":{"type":"object","properties":{"object":{"type":"string","enum":["coverage_recommendation"]},"kind":{"type":"string","enum":["email_forward","daily_statement","bank_connection","android_device","fix_ios_keywords"]},"priority":{"type":"string","enum":["high","normal"]},"title":{"type":"string"},"reason":{"type":"string"},"action":{"type":["object","null"],"properties":{"tab":{"type":"string","description":"Tab đích, vd. `device:new`, `channels`."},"hint":{"type":["string","null"]}},"required":["tab","hint"]}},"required":["object","kind","priority","title","reason","action"]},"CoverageRecommendationList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"account_id":{"$ref":"#/components/schemas/AccountId"},"channels":{"type":"object","properties":{"ios":{"type":"integer","minimum":0},"android":{"type":"integer","minimum":0},"email":{"type":"integer","minimum":0},"bank_connection":{"type":"integer","minimum":0}},"required":["ios","android","email","bank_connection"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/CoverageRecommendation"}}},"required":["object","account_id","channels","data"]},"CreateApiKey":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"env":{"type":"string","enum":["live","test"],"description":"`live`: dữ liệu thật; `test`: sandbox."},"scopes":{"type":"array","items":{"type":"string","enum":["transactions:read","accounts:read","balances:read","invoices:read","counterparties:read","cashflow:read","settlement:read","export:read","audit:read","mcp:read","collect:write","reconcile:propose","import:write","webhooks:write","integrations:write","collect:read","integrations:read","billing:read"]},"minItems":1,"maxItems":18},"all_companies":{"type":"boolean","default":false,"description":"Mọi công ty của tổ chức (kể cả công ty thêm sau), trừ công ty cô lập cứng."},"company_ids":{"type":"array","items":{"$ref":"#/components/schemas/OrgId"},"maxItems":500,"description":"Cần khi `all_companies=false`."},"bank_account_ids":{"type":"array","items":{"$ref":"#/components/schemas/AccountId"},"maxItems":500,"description":"Giới hạn theo tài khoản; bỏ trống = mọi tài khoản của các công ty được chọn."},"ip_allowlist":{"type":"array","items":{"type":"string","minLength":2,"maxLength":64},"maxItems":50,"default":[],"description":"Địa chỉ IPv4/IPv6 hoặc CIDR; giá trị sai → `422`."},"pinned_version":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Phiên bản API `YYYY-MM-DD` để ghim."},"expires_at":{"type":"string","format":"date-time","description":"Bắt buộc với khoá `live`; tối đa 12 tháng kể từ bây giờ."}},"required":["name","env","scopes"],"example":{"name":"Đồng bộ kế toán","env":"live","scopes":["transactions:read","accounts:read"],"all_companies":true,"ip_allowlist":["203.0.113.0/24"],"expires_at":"2030-06-30T00:00:00+07:00"}},"CreateBankAccount":{"type":"object","properties":{"company_id":{"$ref":"#/components/schemas/OrgId"},"bank_code":{"type":"string","minLength":2,"maxLength":16,"example":"ACB"},"account_number":{"type":"string","pattern":"^\\d{6,20}$","description":"Số tài khoản đầy đủ. Chỉ ghi: được mã hoá ngay khi nhận và không bao giờ trả lại ở các route đọc.","example":"123456784521"},"holder_name":{"type":"string","minLength":1,"maxLength":200},"type":{"type":"string","enum":["business","virtual_sub","savings"],"default":"business"},"label":{"type":"string","minLength":1,"maxLength":80},"va_number":{"type":"string","pattern":"^\\d{6,24}$"}},"required":["company_id","bank_code","account_number"]},"CreateBill":{"type":"object","properties":{"store":{"type":"string","pattern":"^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$","description":"`slug` của cửa hàng."},"counter":{"type":"string","pattern":"^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$","description":"`slug` của quầy."},"bill_ref":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9._\\-/#]+$","description":"Mã bill của POS; duy nhất trong quầy. Dùng làm `Idempotency-Key`."},"amount":{"type":"integer","exclusiveMinimum":0,"maximum":9999999999999},"account":{"type":"string","pattern":"^(acc_[0-9a-hjkmnp-tv-z]{26}|[a-zA-Z0-9]{2,12}_[0-9a-zA-Z]{1,4})$","description":"Bỏ trống: dùng tài khoản của quầy."},"expires_in_minutes":{"type":"integer","minimum":1,"maximum":1440,"description":"Mặc định theo `qr_ttl_min` của quầy."},"customer_name":{"type":"string","minLength":1,"maxLength":120},"note":{"type":"string","minLength":1,"maxLength":500}},"required":["store","counter","bill_ref","amount"],"example":{"store":"q1-nguyen-hue","counter":"quay-1","bill_ref":"HD-000123","amount":185000}},"CreateDevicePairingCode":{"type":"object","properties":{"company_id":{"$ref":"#/components/schemas/OrgId"},"kind":{"type":"string","enum":["android"],"default":"android"},"device_name_hint":{"type":"string","minLength":1,"maxLength":60},"account_ids":{"type":"array","items":{"$ref":"#/components/schemas/AccountId"},"maxItems":50,"description":"Tài khoản máy sẽ phụ trách; bỏ trống = mọi tài khoản của công ty."}},"required":["company_id"]},"CreateExportBatchBody":{"type":"object","properties":{"target":{"$ref":"#/components/schemas/ExportTarget"},"coa_profile":{"type":"string","description":"Mã hoặc id của hệ thống tài khoản (TT133 hoặc TT99).","example":"TT133"},"from":{"$ref":"#/components/schemas/Date"},"to":{"$ref":"#/components/schemas/Date"},"account_ids":{"type":"array","items":{"$ref":"#/components/schemas/AccountId"},"minItems":1},"voucher_types":{"type":"array","items":{"$ref":"#/components/schemas/VoucherType"},"minItems":1},"flags":{"$ref":"#/components/schemas/ExportFlags"},"note_to_checker":{"type":"string","maxLength":500},"ack_warnings":{"type":"boolean","default":false,"description":"Người tạo xác nhận đã xem và đồng ý với các cảnh báo (warning)."}},"required":["target","coa_profile","from","to","account_ids","voucher_types"]},"CreateInvitation":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email"},"role":{"type":"string","enum":["owner","admin","accountant_chief","accountant","developer","viewer","auditor"]},"org_id":{"type":"string","pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Công ty sẽ giữ vai trò; bỏ trống = nút gốc.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"scope":{"type":"string","enum":["all","list"],"default":"all","description":"`all`: mọi công ty của nút; `list`: chỉ các công ty trong `company_ids` (chỉ ở nút gốc)."},"company_ids":{"type":"array","items":{"$ref":"#/components/schemas/OrgId"},"maxItems":500,"description":"Các công ty của phạm vi `list` (chỉ lời mời ở nút gốc)."},"require_2fa":{"type":"boolean","default":false},"expires_in_days":{"anyOf":[{"type":"number","enum":[3]},{"type":"number","enum":[7]},{"type":"number","enum":[14]}],"default":7,"description":"Hiệu lực của liên kết: 3, 7 hoặc 14 ngày."}},"required":["email","role"],"example":{"email":"ketoan@congty.example","role":"accountant","scope":"all","require_2fa":false,"expires_in_days":7}},"CreateIosDevice":{"type":"object","properties":{"company_id":{"$ref":"#/components/schemas/OrgId"},"kind":{"type":"string","enum":["ios_shortcut"],"default":"ios_shortcut"},"name":{"type":"string","minLength":1,"maxLength":100,"example":"iPhone quầy 1"},"account_ids":{"type":"array","items":{"$ref":"#/components/schemas/AccountId"},"maxItems":50,"description":"Tài khoản máy phụ trách; bỏ trống = mọi tài khoản của công ty."},"responsible_user_id":{"type":"string","description":"Người phụ trách (tuỳ chọn)."}},"required":["company_id","name"],"example":{"company_id":"org_0f5k2m9q4h7t3n8r6v1w0x5yzd","kind":"ios_shortcut","name":"iPhone quầy 1"}},"CreateMappingRuleBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Thu tiền khách hàng qua ngân hàng"},"profile_id":{"type":"string","format":"uuid","example":"0192f2f0-7c3e-7d3a-9b1a-3c5d6e7f8a90"},"conditions":{"type":"object","additionalProperties":{},"default":{}},"voucher_type":{"$ref":"#/components/schemas/VoucherType"},"debit_account":{"type":"string","minLength":3,"example":"1121"},"credit_account":{"type":"string","minLength":3,"example":"131"},"detail_account":{"type":"string"},"counterparty_rule":{"type":"object","additionalProperties":{}},"case_code_required":{"type":"boolean","default":false},"vat_rate":{"type":"number"},"revenue_account":{"type":"string"},"vat_account":{"type":"string"},"priority":{"type":"integer","default":100},"effective_from":{"$ref":"#/components/schemas/Date"}},"required":["name","profile_id","voucher_type","debit_account","credit_account","effective_from"]},"CreateObligationAllocationBody":{"type":"object","properties":{"tx_id":{"type":"string","pattern":"^tx_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã giao dịch ngân hàng ĐÃ XÁC THỰC (verified)","example":"tx_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"amount":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Số tiền gạch nợ (phải <= số tiền giao dịch và <= số dư còn lại của nghĩa vụ)","example":4500000},"overpay_handling":{"type":"string","enum":["credit_next","refund_reminder"]}},"required":["tx_id","amount"]},"CreateOrg":{"type":"object","properties":{"parent_id":{"type":"string","pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Nút gốc để thêm công ty vào; mặc định là nút gốc của người gọi. Người dùng mới chưa có tổ chức: bỏ trống, hệ thống tạo nút gốc.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"mst":{"type":"string","minLength":1,"maxLength":32,"description":"Mã số thuế, 10 số hoặc 10 số + `-NNN`.","example":"0100109106"},"name":{"type":"string","minLength":1,"maxLength":200,"description":"Chỉ bắt buộc khi nguồn MST không trả được tên pháp lý."},"display_name":{"type":"string","pattern":"^[A-Z0-9 ]{1,25}$","description":"Tên hiển thị trên VietQR; mặc định suy ra từ tên pháp lý."},"alert_email":{"type":"string","maxLength":254,"format":"email","description":"Email nhận cảnh báo kênh / tiền vào của công ty. Để trống: gửi tới các chủ sở hữu.","example":"ketoan@congty.vn"},"is_accounting_firm":{"type":"boolean","description":"Áp dụng khi lời gọi này tạo nút gốc (lần đầu sử dụng)."},"template_id":{"type":"string","format":"uuid","description":"Mã mẫu từ `GET /v1/org-templates`; mặc định là mẫu mặc định của nút gốc."}},"required":["mst"]},"CreateOrgResult":{"type":"object","properties":{"company":{"$ref":"#/components/schemas/Org"},"root":{"type":["object","null"],"properties":{"id":{"$ref":"#/components/schemas/OrgId"},"kind":{"type":"string","description":"`root` (văn phòng kế toán / doanh nghiệp) hoặc `company` (một mã số thuế).","example":"company"},"parent_id":{"type":["string","null"],"pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Tổ chức gốc chứa công ty; `null` với `root`.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"root_id":{"$ref":"#/components/schemas/OrgId"},"name":{"type":"string","description":"Tên gọi trong hệ thống."},"mst":{"type":["string","null"],"description":"Mã số thuế (10 hoặc 13 số, không có dấu gạch)."},"mst_synced_at":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Lần cuối đồng bộ hồ sơ pháp lý từ nguồn MST; `null` nếu chưa từng.","example":"2026-10-19T01:30:15Z"},"legal_name":{"type":["string","null"],"description":"Tên pháp lý theo nguồn MST."},"address":{"type":["string","null"]},"legal_rep":{"type":["string","null"],"description":"Người đại diện pháp luật."},"alert_email":{"type":["string","null"],"maxLength":254,"format":"email","description":"Email nhận cảnh báo kênh / tiền vào của công ty. Để trống: gửi tới các chủ sở hữu.","example":"ketoan@congty.vn"},"entity_type":{"type":["string","null"]},"display_name":{"type":["string","null"],"description":"Tên hiển thị trên mã VietQR: chữ in hoa không dấu, tối đa 25 ký tự."},"is_accounting_firm":{"type":"boolean"},"coa_profile":{"type":"string","enum":["TT133","TT99"],"description":"Hệ thống tài khoản kế toán: Thông tư 133 hoặc 99."},"fiscal_year_start":{"type":"string","pattern":"^(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$","example":"01-01","description":"Ngày bắt đầu năm tài chính `MM-DD`."},"timezone":{"type":"string","example":"Asia/Ho_Chi_Minh"},"billing_payer":{"type":"string","enum":["firm","customer"],"description":"Bên trả phí: văn phòng kế toán hoặc khách hàng."},"isolation":{"type":"string","enum":["hard","consolidate"],"description":"`hard`: dữ liệu tách hẳn, văn phòng chỉ vào được khi được chỉ định rõ."},"tax_status":{"type":"string","description":"Tình trạng thuế theo nguồn MST: `active`, `suspended`, `closed` hoặc `unknown`."},"status":{"type":"string","description":"`active`, `suspended`, `frozen` (đang chờ xoá) hoặc `deleted`."},"delete_after":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Thời điểm công ty bị đóng băng sẽ được xoá hẳn.","example":"2026-10-19T01:30:15Z"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"role":{"type":["string","null"],"description":"Vai trò của người gọi tại nút này (người dùng và OAuth); `null` với khoá API."}},"required":["id","kind","parent_id","root_id","name","mst","mst_synced_at","legal_name","address","legal_rep","alert_email","entity_type","display_name","is_accounting_firm","coa_profile","fiscal_year_start","timezone","billing_payer","isolation","tax_status","status","delete_after","created_at","role"],"description":"Nút gốc vừa được tạo (lần đầu sử dụng); `null` nếu đã có."},"mst_source":{"$ref":"#/components/schemas/MstSource"},"warnings":{"type":"array","items":{"type":"string"},"description":"Cảnh báo không chặn: `mst_checksum_failed`, `mst_lookup_unavailable`, `mst_not_found_at_source`, `tax_status_not_active`."}},"required":["company","root","mst_source","warnings"]},"CreateOrgTemplate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"coa_profile":{"type":"string","enum":["TT133","TT99"],"default":"TT133"},"default_role":{"type":"string","enum":["owner","admin","accountant_chief","accountant","developer","viewer","auditor"],"default":"accountant"},"require_2fa_days":{"type":"integer","minimum":0,"maximum":90,"default":7},"is_default":{"type":"boolean","default":false}},"required":["name"],"example":{"name":"Công ty dịch vụ","coa_profile":"TT133","default_role":"accountant","require_2fa_days":7,"is_default":false}},"CreatePartnerBody":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/PartnerKind"},"name":{"type":"string","minLength":1,"maxLength":200},"legal_name":{"type":"string","maxLength":200},"mst":{"type":"string","maxLength":20},"cycle":{"type":"object","properties":{"kind":{"type":"string","enum":["daily","weekly","monthly","biweekly"]},"params":{"type":"object","additionalProperties":{}}},"required":["kind"]},"payment_terms_days":{"type":"integer","minimum":0,"maximum":365,"default":0},"data_source":{"type":"string","enum":["excel","api_seller","manual"],"default":"excel"},"bank_account_ref":{"type":"string","maxLength":64},"internal_note":{"type":"string","maxLength":500}},"required":["kind","name","cycle"],"example":{"kind":"ctv_group","name":"Nhóm CTV Hà Nội","legal_name":"Công ty TNHH Thương mại Minh Anh","mst":"0312345678","cycle":{"kind":"monthly"},"payment_terms_days":7,"data_source":"excel"}},"CreatePaymentRequest":{"type":"object","properties":{"account":{"type":"string","pattern":"^(acc_[0-9a-hjkmnp-tv-z]{26}|[a-zA-Z0-9]{2,12}_[0-9a-zA-Z]{1,4})$","description":"Tài khoản nhận: `acc_…` hoặc bí danh `<ngân hàng>_<4 số cuối>`. Bí danh trùng nhiều tài khoản trả `409 account_alias_ambiguous`."},"amount":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":9999999999999,"description":"Số tiền; `null`/bỏ trống để khách tự nhập."},"expires_in_minutes":{"type":"integer","minimum":5,"maximum":43200,"default":1440,"description":"Hạn thanh toán, mặc định 24 giờ, tối đa 30 ngày."},"allow_partial":{"type":"boolean","default":false},"counter_id":{"$ref":"#/components/schemas/CounterId"},"customer_name":{"type":"string","minLength":1,"maxLength":120},"ref":{"type":"string","minLength":1,"maxLength":64,"description":"Mã tham chiếu của bạn (đơn hàng…)."},"note":{"type":"string","minLength":1,"maxLength":500,"description":"Ghi chú nội bộ, không hiện cho khách."}},"required":["account"],"example":{"account":"acb_4521","amount":250000,"ref":"DH-10492"}},"CreateSavedView":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"visibility":{"$ref":"#/components/schemas/SavedViewVisibility"},"company_id":{"type":"string","pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Bắt buộc khi `visibility=company`.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"filters":{"$ref":"#/components/schemas/SavedViewFilters"},"show_count_on_card":{"type":"boolean","default":false},"show_in_dashboard_todo":{"type":"boolean","default":false}},"required":["name"],"example":{"name":"Tiền vào hôm nay","visibility":"me","filters":{}}},"CreateSplitRuleBody":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/SplitRuleKind"},"partner_id":{"$ref":"#/components/schemas/PartnerId"},"name":{"type":"string","minLength":1,"maxLength":120},"initial_version":{"type":"object","properties":{"conds":{"type":"object","properties":{"brands":{"type":"array","items":{"type":"string"}},"platforms":{"type":"array","items":{"$ref":"#/components/schemas/SettlementPlatform"}},"ctv_codes":{"type":"array","items":{"type":"string"}},"sku_prefixes":{"type":"array","items":{"type":"string"}}}},"pct_bp":{"type":"integer","minimum":0,"maximum":10000},"basis":{"$ref":"#/components/schemas/SplitRuleBasis"},"trigger":{"$ref":"#/components/schemas/SplitRuleTrigger"},"effective_from":{"$ref":"#/components/schemas/Date"}},"required":["conds","pct_bp","basis","trigger","effective_from"]}},"required":["kind","partner_id","name","initial_version"],"example":{"kind":"payable_brand","partner_id":"ptn_0f5k2m9q4h7t3n8r6v1w0x5yz0","name":"Chia doanh thu hãng An Phát","initial_version":{"conds":{"brands":["Thương hiệu An Phát"],"platforms":["shopee"]},"pct_bp":1500,"basis":"net_after_platform_fee","trigger":"on_delivered","effective_from":"2026-11-01"}}},"CreateSplitRuleVersionBody":{"type":"object","properties":{"conds":{"type":"object","properties":{"brands":{"type":"array","items":{"type":"string"}},"platforms":{"type":"array","items":{"$ref":"#/components/schemas/SettlementPlatform"}},"ctv_codes":{"type":"array","items":{"type":"string"}},"sku_prefixes":{"type":"array","items":{"type":"string"}}}},"pct_bp":{"type":"integer","minimum":0,"maximum":10000},"basis":{"$ref":"#/components/schemas/SplitRuleBasis"},"trigger":{"$ref":"#/components/schemas/SplitRuleTrigger"},"effective_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Ngày hiệu lực bắt buộc >= ngày hiện tại","example":"2026-10-19"}},"required":["conds","pct_bp","basis","trigger","effective_from"],"example":{"conds":{"brands":["Thương hiệu An Phát"],"platforms":["shopee"]},"pct_bp":1200,"basis":"net_after_platform_fee","trigger":"on_delivered","effective_from":"2026-11-01"}},"CreateStatementSchedule":{"type":"object","properties":{"bank_account_id":{"$ref":"#/components/schemas/AccountId"},"source":{"type":"string","enum":["email_attachment","manual_upload","sftp"]},"format":{"type":"string","enum":["auto","xlsx","csv","mt940","camt053"],"default":"auto"},"cron":{"type":"string","minLength":9,"maxLength":64,"pattern":"^\\S+( \\S+){4}$","description":"Bắt buộc với `manual_upload` và `sftp`; không dùng với `email_attachment`."},"alias_id":{"type":"string","pattern":"^eal_[0-9a-hjkmnp-tv-z]{26}$","description":"Chỉ với `email_attachment`: alias thư nhận sao kê.","example":"eal_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"sftp":{"type":"object","properties":{"host":{"type":"string","minLength":1,"maxLength":253},"port":{"type":"integer","minimum":1,"maximum":65535,"default":22},"path":{"type":"string","minLength":1,"maxLength":255,"description":"Thư mục hoặc mẫu tên tệp trên máy chủ SFTP, ví dụ `/out/camt053/*.xml`."},"username":{"type":"string","minLength":1,"maxLength":128},"host_key_sha256":{"type":"string","pattern":"^SHA256:[A-Za-z0-9+/]{43}$","description":"Dấu vân tay khoá máy chủ SFTP (`SHA256:…`, như `ssh-keygen -lf`). Cổng ngân hàng chỉ kết nối khi máy chủ trình đúng khoá này; không khớp thì từ chối, không tự tin cậy lần đầu."},"secret":{"type":"string","minLength":1,"maxLength":4096,"description":"Mật khẩu hoặc khoá riêng; được niêm phong cho cổng ngân hàng, không bao giờ trả về."}},"required":["host","path","username","host_key_sha256","secret"],"description":"Bắt buộc với `sftp`, cấm với nguồn khác. SFTP chỉ nhận CAMT.053."},"auto_commit":{"type":"boolean","default":true},"overdue_after_days":{"type":"integer","minimum":1,"maximum":90,"default":7}},"required":["bank_account_id","source"]},"CreateWebhookEndpointBody":{"type":"object","properties":{"company_id":{"type":"string","pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Công ty cụ thể hoặc bỏ trống nếu chọn tất cả công ty.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"company_scope":{"$ref":"#/components/schemas/WebhookCompanyScope"},"url":{"type":"string","example":"https://api.congtyabc.vn/webhooks/dongtien"},"description":{"type":"string","maxLength":255},"events":{"type":"array","items":{"type":"string"},"minItems":1,"example":["transaction.confirmed","payment.received"]},"api_version":{"type":"string","default":"2026-10-19"},"egress":{"$ref":"#/components/schemas/WebhookEgress"},"send_full_account":{"type":"boolean","default":false},"memo_pattern_id":{"$ref":"#/components/schemas/MemoPatternId"},"memo_regex":{"type":"string","maxLength":128}},"required":["url","events"]},"CreateWebhookEndpointResponse":{"type":"object","properties":{"endpoint":{"$ref":"#/components/schemas/WebhookEndpoint"},"secret":{"type":"string","description":"Khoá bí mật đầy đủ (whsec_...), chỉ hiển thị một lần duy nhất."}},"required":["endpoint","secret"]},"Currency":{"type":"string","enum":["VND"],"description":"Mã tiền tệ ISO 4217. GA chỉ có `VND`."},"CurrentPlanResponse":{"type":"object","properties":{"plan_key":{"type":"string","enum":["free","per_tx","enterprise","trial","internal"]},"name":{"type":"string"},"description":{"type":["string","null"]},"is_illustrative":{"type":"boolean"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/PlanTier"}},"limits":{"$ref":"#/components/schemas/PlanLimits"},"state":{"type":"string","enum":["trial","active","overdue","suspended","closing"]},"trial_ends_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"dunning_stage":{"type":"string","enum":["current","reminder_3d","reminder_7d","reminder_14d","suspended_30d"]}},"required":["plan_key","name","description","is_illustrative","tiers","limits","state","trial_ends_at","dunning_stage"],"description":"Chi tiết gói cước hiện tại của tổ chức."},"Cursor":{"type":"string","maxLength":4096,"pattern":"^cur_[A-Za-z0-9_-]+(\\.[A-Za-z0-9_-]+)?$","description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","example":"cur_eyJ2IjoxfQ.AAAAAAAAAAAAAAAAAAAAAA"},"DashboardSummary":{"type":"object","properties":{"object":{"type":"string","enum":["dashboard_summary"]},"period":{"type":"object","properties":{"preset":{"type":"string","enum":["today","7d","30d","month"]},"from":{"$ref":"#/components/schemas/Timestamp"},"to":{"$ref":"#/components/schemas/Timestamp"}},"required":["preset","from","to"]},"balances":{"type":"object","properties":{"reported_total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Tổng số dư báo cáo của các tài khoản đã có số dư (không cộng số tính toán).","example":4500000},"accounts_reported":{"type":"integer","minimum":0},"accounts_total":{"type":"integer","minimum":0},"accounts":{"type":"array","items":{"type":"object","properties":{"account_id":{"$ref":"#/components/schemas/AccountId"},"label":{"type":["string","null"]},"bank":{"type":"string"},"last4":{"type":"string","pattern":"^\\d{4}$"},"reported":{"type":["object","null"],"properties":{"amount":{"$ref":"#/components/schemas/Vnd"},"as_of":{"$ref":"#/components/schemas/Timestamp"}},"required":["amount","as_of"],"description":"Số dư do ngân hàng/sao kê báo cáo gần nhất; `null` nếu chưa có."},"trust":{"$ref":"#/components/schemas/BalanceChainTrust"}},"required":["account_id","label","bank","last4","reported","trust"]},"maxItems":50}},"required":["reported_total","accounts_reported","accounts_total","accounts"],"description":"Số dư hợp nhất: chỉ cộng số dư báo cáo; tài khoản chưa có số dư đếm ở `accounts_total`."},"flow":{"type":"object","properties":{"in":{"$ref":"#/components/schemas/Vnd"},"out":{"$ref":"#/components/schemas/Vnd"},"count":{"type":"integer","minimum":0},"provisional_in":{"$ref":"#/components/schemas/Vnd"},"provisional_out":{"$ref":"#/components/schemas/Vnd"},"provisional_share_pct":{"type":"number","minimum":0,"maximum":100,"description":"Phần trăm (làm tròn 1 chữ số) tiền vào + ra còn tạm tính trên tổng."}},"required":["in","out","count","provisional_in","provisional_out","provisional_share_pct"]},"today":{"type":"object","properties":{"in":{"$ref":"#/components/schemas/Vnd"},"out":{"$ref":"#/components/schemas/Vnd"},"in_count":{"type":"integer","minimum":0},"out_count":{"type":"integer","minimum":0},"from":{"$ref":"#/components/schemas/Timestamp"}},"required":["in","out","in_count","out_count","from"]},"todos":{"type":"object","properties":{"provisional_over_24h":{"type":"integer","minimum":0},"unreconciled":{"type":"integer","minimum":0},"quarantined":{"type":"integer","minimum":0},"needs_attention":{"type":"integer","minimum":0},"unrouted_messages":{"type":"integer","minimum":0},"chain_gaps":{"type":"integer","minimum":0},"reversal_review":{"type":"integer","minimum":0},"statement_unmatched":{"type":"integer","minimum":0,"description":"Giao dịch tạm tính nằm trong kỳ của sao kê nhập gần nhất của tài khoản nhưng sao kê không có (\"Không có trong sao kê\"). Xác thực hoặc lưu trữ giao dịch thì giảm."}},"required":["provisional_over_24h","unreconciled","quarantined","needs_attention","unrouted_messages","chain_gaps","reversal_review"],"description":"Việc cần xử lý. `unrouted_messages` đếm tin chưa gán được tài khoản (cần quyền xử lý tin chưa gán, ngược lại `0`). `reversal_review` đếm giao dịch hoàn/huỷ chưa được xem xét (đã liên kết giao dịch gốc, hoặc mồ côi vì không tìm được một giao dịch gốc duy nhất); đóng bằng thẻ `reversal_reviewed`."},"pinned_views":{"type":"array","items":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/SavedViewId"},"name":{"type":"string"},"count":{"type":["integer","null"],"minimum":0}},"required":["id","name","count"]},"description":"Chế độ xem ghim lên bảng điều khiển (`show_in_dashboard_todo`); `count` chỉ có khi bật `show_count_on_card`."},"as_of":{"$ref":"#/components/schemas/Timestamp"}},"required":["object","period","balances","flow","today","todos","pinned_views","as_of"],"description":"Tổng quan từ sổ giao dịch cho bảng điều khiển."},"Date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Ngày lịch `YYYY-MM-DD` (giờ Việt Nam).","example":"2026-10-19"},"DecideCategoryRetroApply":{"type":"object","properties":{"decision":{"type":"string","enum":["approve","reject"]},"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["decision"]},"DecideManualVerify":{"type":"object","properties":{"decision":{"type":"string","enum":["approve","reject"]},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["decision"]},"DeleteOrgRequest":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"description":"Lý do, hiển thị cho người xác nhận."}},"example":{"reason":"Công ty đã giải thể."}},"Device":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/DeviceId"},"object":{"type":"string","enum":["device"]},"kind":{"$ref":"#/components/schemas/DeviceKind"},"name":{"type":"string"},"state":{"$ref":"#/components/schemas/DeviceState"},"company":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/OrgId"},"mst":{"type":["string","null"],"description":"Mã số thuế của công ty."}},"required":["id","mst"]},"os":{"type":["string","null"],"example":"Android 15"},"rom":{"type":["string","null"],"example":"HyperOS 2.0"},"manufacturer":{"type":["string","null"],"example":"Xiaomi"},"model":{"type":["string","null"],"example":"Redmi Note 13"},"app_version":{"type":["string","null"],"example":"1.4.2"},"version_code":{"type":["integer","null"]},"update_available":{"anyOf":[{"$ref":"#/components/schemas/DeviceUpdateInfo"},{"type":"null"}]},"attestation_level":{"anyOf":[{"$ref":"#/components/schemas/DeviceAttestationLevel"},{"type":"null"}]},"config_version":{"type":"integer"},"responsible_user_id":{"type":["string","null"],"pattern":"^usr_[0-9a-hjkmnp-tv-z]{26}$","description":"Người phụ trách nhận nhắc khi máy mất kết nối.","example":"usr_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"account_ids":{"type":"array","items":{"$ref":"#/components/schemas/AccountId"},"description":"Tài khoản mà thiết bị này phụ trách chuyển tiếp."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/DeviceSource"}},"last_seen_at":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Heartbeat gần nhất (rollup tối đa 60 s).","example":"2026-10-19T01:30:15Z"},"last_sms_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"silent_since":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"iOS: bắt đầu im lặng quá 36 giờ.","example":"2026-10-19T01:30:15Z"},"battery_pct":{"type":["integer","null"],"minimum":0,"maximum":100},"queue_depth":{"type":["integer","null"],"minimum":0},"perms":{"anyOf":[{"$ref":"#/components/schemas/DevicePerms"},{"type":"null"}]},"oem_checks":{"anyOf":[{"$ref":"#/components/schemas/DeviceOemChecks"},{"type":"null"}]},"send_stats":{"anyOf":[{"$ref":"#/components/schemas/DeviceSendStats"},{"type":"null"}]},"token_last4":{"type":["string","null"],"description":"iOS: 4 ký tự cuối token `dtd_…` (đã che)."},"trust_downgraded_at":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"iOS (D42): thời điểm hệ thống hạ tin cậy thiết bị; giao dịch mới về `provisional`.","example":"2026-10-19T01:30:15Z"},"revoked_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"created_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","object","kind","name","state","company","os","rom","manufacturer","model","app_version","version_code","update_available","attestation_level","config_version","responsible_user_id","account_ids","sources","last_seen_at","last_sms_at","silent_since","battery_pct","queue_depth","perms","oem_checks","send_stats","token_last4","trust_downgraded_at","revoked_at","created_at"],"description":"Thiết bị chuyển tiếp tin (Android hoặc iOS Shortcuts). Không bao giờ chứa khoá công khai, băm token hay nội dung tin."},"DeviceAlertRules":{"type":"object","properties":{"object":{"type":"string","enum":["device_alert_rules"]},"company_id":{"$ref":"#/components/schemas/OrgId"},"no_heartbeat_min":{"type":"integer","minimum":5,"maximum":240,"description":"Không heartbeat quá N phút ⇒ `stale`; gấp đôi ⇒ `offline` (mặc định 15 / 30)."},"battery_lt":{"type":"integer","minimum":1,"maximum":99,"description":"Pin dưới N % (mặc định 20)."},"queue_gt":{"type":"integer","minimum":1,"maximum":5000,"description":"Hàng đợi quá N tin (mặc định 10)."},"queue_age_min":{"type":"integer","minimum":1,"maximum":1440,"description":"…kéo dài quá N phút mới cảnh báo (mặc định 30)."},"ios_silent_hours":{"type":"integer","minimum":1,"maximum":168,"description":"iOS: không có SMS hợp lệ quá N giờ ⇒ `silent` (mặc định 36)."},"channels":{"type":"array","items":{"type":"string","enum":["zalo","push","email"]},"minItems":1,"maxItems":3},"enabled":{"type":"object","properties":{"no_heartbeat":{"type":"boolean"},"battery":{"type":"boolean"},"queue":{"type":"boolean"},"ios_silent":{"type":"boolean"}},"required":["no_heartbeat","battery","queue","ios_silent"]},"remind_every_hours":{"type":"number","enum":[6],"description":"Nhắc lại tối đa 1 lần / 6 giờ (cố định)."},"updated_at":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"`null` khi đang dùng mặc định chưa lưu.","example":"2026-10-19T01:30:15Z"}},"required":["object","company_id","no_heartbeat_min","battery_lt","queue_gt","queue_age_min","ios_silent_hours","channels","enabled","remind_every_hours","updated_at"],"description":"Quy tắc cảnh báo thiết bị của một công ty."},"DeviceAttestationLevel":{"type":"string","enum":["strongbox","tee","software","none"],"description":"Mức bảo vệ khoá thiết bị do Android Key Attestation báo: `strongbox` > `tee` > `software` > `none`. Chỉ hiển thị, không chặn ở GA."},"DeviceBankList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/DeviceBankStatus"}},"accounts":{"type":"array","items":{"$ref":"#/components/schemas/DeviceIosAccount"}},"sender_verified_enabled":{"type":"boolean","description":"Cờ nền tảng `ios.sender_verified` đang bật: giao dịch iOS đủ điều kiện có thể `verified`."}},"required":["object","data","accounts","sender_verified_enabled"]},"DeviceBankStatus":{"type":"object","properties":{"object":{"type":"string","enum":["device_bank_status"]},"bank_code":{"type":"string"},"brand":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"status":{"$ref":"#/components/schemas/IosBankStatus"},"automation_created":{"type":"boolean","description":"Người dùng đã bấm \"Đã tạo automation\"."},"last_message_at":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Tin gần nhất automation này chuyển lên.","example":"2026-10-19T01:30:15Z"},"today_ok":{"type":"integer","minimum":0,"description":"Tin đọc được hôm nay (giờ Việt Nam)."},"today_fail":{"type":"integer","minimum":0,"description":"Tin không đọc được hôm nay."},"last_parse_error_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["object","bank_code","brand","keywords","status","automation_created","last_message_at","today_ok","today_fail","last_parse_error_at"],"description":"Trạng thái automation của một ngân hàng trên một iPhone. Không chứa nội dung tin."},"DeviceCommand":{"type":"object","properties":{"object":{"type":"string","enum":["device_command"]},"id":{"type":"string"},"device_id":{"$ref":"#/components/schemas/DeviceId"},"kind":{"$ref":"#/components/schemas/DeviceCommandKind"},"state":{"type":"string","enum":["queued","delivered","completed","failed","expired"]},"queued_at":{"$ref":"#/components/schemas/Timestamp"},"expires_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["object","id","device_id","kind","state","queued_at","expires_at"],"description":"Lệnh đã xếp hàng; máy nhận ở heartbeat kế tiếp (≤ 45 giây khi dịch vụ nền còn sống)."},"DeviceCommandKind":{"type":"string","enum":["ping","upload_queue_preview","diagnose","test_send","catch_up"],"description":"Lệnh server → máy, đi kèm phản hồi heartbeat 45 s (không dùng FCM): `ping` (báo sống), `upload_queue_preview` (gửi 20 mục hàng đợi đã che), `diagnose` (gửi bảng kiểm), `test_send` (gửi tin thử), `catch_up` (quét lại hộp thư trong khoảng thời gian)."},"DeviceEvent":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["device_event"]},"device_id":{"$ref":"#/components/schemas/DeviceId"},"at":{"$ref":"#/components/schemas/Timestamp"},"kind":{"type":"string","example":"seq_gap","description":"Loại nhật ký: `paired`, `first_heartbeat`, `stale`, `offline`, `online`, `revoked`, `unpaired`, `seq_gap`, `burst`, `command`, `pin_mismatch`, `perm_lost`, `first_sms`, `trust_downgraded`…"},"detail":{"type":"object","additionalProperties":{},"description":"Chi tiết đã che; không có nội dung tin."}},"required":["id","object","device_id","at","kind","detail"],"description":"Một dòng nhật ký thiết bị (chỉ thêm, không sửa)."},"DeviceEventList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/DeviceEvent"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"DeviceId":{"type":"string","pattern":"^dev_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã thiết bị chuyển tiếp tin (`dev_…`).","example":"dev_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"DeviceIosAccount":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AccountId"},"bank_code":{"type":"string"},"last4":{"type":["string","null"]},"label":{"type":["string","null"]},"ios_trust_enabled":{"type":"boolean","description":"\"Tính giao dịch iOS là đã xác thực\": tắt thì giao dịch iOS của tài khoản này luôn `provisional`."}},"required":["id","bank_code","last4","label","ios_trust_enabled"]},"DeviceKind":{"type":"string","enum":["android","ios_shortcut"]},"DeviceList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Device"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"DeviceNudge":{"type":"object","properties":{"object":{"type":"string","enum":["device_nudge"]},"device_id":{"$ref":"#/components/schemas/DeviceId"},"sent_to_user_id":{"anyOf":[{"$ref":"#/components/schemas/UserId"},{"type":"null"}]},"sent_at":{"$ref":"#/components/schemas/Timestamp"},"next_allowed_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Nhắc lại được sau mốc này (tối đa 1 lần / 6 giờ).","example":"2026-10-19T01:30:15Z"}},"required":["object","device_id","sent_to_user_id","sent_at","next_allowed_at"]},"DeviceOemChecks":{"type":"object","properties":{"autostart_confirmed":{"type":"boolean"}},"required":["autostart_confirmed"],"description":"Mục chỉ người dùng tự xác nhận được trên máy (tự khởi động của ROM Xiaomi/Oppo/Vivo…)."},"DevicePairingCode":{"type":"object","properties":{"object":{"type":"string","enum":["device_pairing_code"]},"code":{"type":"string","pattern":"^PAIR-[0-9A-HJKMNP-TV-Z]{4}-[0-9A-HJKMNP-TV-Z]{4}$","example":"PAIR-7K2M-9QXH","description":"Mã ghép một lần, chỉ hiện ở lần trả lời này."},"qr_payload":{"type":"string","description":"Nội dung mã QR: `https://dongtien.pro/p/<code>` (mở app hoặc trang tải)."},"kind":{"type":"string","enum":["android"]},"company":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/OrgId"},"mst":{"type":["string","null"]}},"required":["id","mst"]},"device_name_hint":{"type":["string","null"]},"account_ids":{"type":"array","items":{"$ref":"#/components/schemas/AccountId"}},"expires_at":{"$ref":"#/components/schemas/Timestamp"},"expires_in":{"type":"integer","description":"Số giây còn lại (300)."}},"required":["object","code","qr_payload","kind","company","device_name_hint","account_ids","expires_at","expires_in"]},"DevicePerms":{"type":"object","properties":{"receive_sms":{"type":"boolean"},"read_sms":{"type":"boolean"},"notification_listener":{"type":"boolean"},"post_notifications":{"type":"boolean"},"battery_unrestricted":{"type":"boolean"}},"required":["receive_sms","read_sms","notification_listener","post_notifications","battery_unrestricted"],"description":"Quyền hệ điều hành đang có trên máy (heartbeat gần nhất)."},"DeviceQueue":{"type":"object","properties":{"object":{"type":"string","enum":["device_queue"]},"device_id":{"$ref":"#/components/schemas/DeviceId"},"state":{"type":"string","enum":["requested","ready","expired","unsupported"],"description":"`requested`: đã xếp lệnh `upload_queue_preview`, chờ máy trả lời; `ready`: có ảnh chụp mới (≤ 15 phút); `expired`: ảnh chụp cũ đã bị xoá; `unsupported`: thiết bị iOS không có hàng đợi."},"queue_depth":{"type":["integer","null"],"minimum":0},"captured_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"expires_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"items":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["sms","notification"]},"sender":{"type":["string","null"],"description":"Brandname/package đã chuẩn hoá."},"preview":{"type":"string","maxLength":80,"description":"Nội dung rút gọn ≤ 80 ký tự, số tài khoản đã che."},"queued_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"attempt":{"type":"integer","minimum":0},"last_error":{"type":["string","null"]}},"required":["source","sender","preview","queued_at","attempt","last_error"]},"maxItems":20}},"required":["object","device_id","state","queue_depth","captured_at","expires_at","items"],"description":"Ảnh chụp hàng đợi trên máy (rút gọn, có kiểm toán)."},"DeviceSendStats":{"type":"object","properties":{"oldest_queued_age_s":{"type":["integer","null"],"minimum":0},"send_latency_ms":{"type":["integer","null"],"minimum":0},"sent_today":{"type":"integer","minimum":0},"otp_dropped_today":{"type":"integer","minimum":0},"foreign_sender_dropped_today":{"type":"integer","minimum":0},"queue_overflow":{"type":"integer","minimum":0},"charging":{"type":["boolean","null"]},"pin_mismatch":{"type":"boolean"}},"required":["oldest_queued_age_s","send_latency_ms","sent_today","otp_dropped_today","foreign_sender_dropped_today","queue_overflow","charging","pin_mismatch"],"description":"Bộ đếm sức khoẻ gửi tin từ heartbeat; không chứa nội dung tin."},"DeviceSource":{"type":"object","properties":{"kind":{"type":"string","enum":["app_package","sms_brand"]},"value":{"type":"string","minLength":1,"maxLength":64,"description":"Package app ngân hàng hoặc brandname SMS (chữ thường)."},"enabled":{"type":"boolean"}},"required":["kind","value","enabled"],"description":"Nguồn mà máy được phép đọc (server-driven)."},"DeviceState":{"type":"string","enum":["pending_pair","active","stale","offline","silent","revoked"]},"DeviceUpdateInfo":{"type":"object","properties":{"version":{"type":"string"},"version_code":{"type":"integer"},"mandatory_by":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["version","version_code","mandatory_by"],"description":"Bản mới hơn máy đang chạy (nếu có)."},"DuplicateCoaProfileBody":{"type":"object","properties":{"name":{"type":"string"}},"example":{"name":"TT133 - bản nháp chuyển sang TT99"}},"DuplicateCoaProfileResult":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"system":{"type":"string"}},"required":["id","name","system"]},"EmailAliasId":{"type":"string","pattern":"^eal_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã email alias (`eal_…`).","example":"eal_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"ErrorCode":{"type":"string","enum":["unauthenticated","invalid_api_key","api_key_expired","api_key_revoked","ip_not_allowed","permission_denied","scope_not_allowed","step_up_required","two_factor_required","hoadon_key_insufficient_scope","approver_same_as_maker","resource_not_found","account_scope_denied","impersonation_forbidden","staff_mfa_required","flag_approval_required","tenant_suspended","bad_request","invalid_json","validation_failed","invalid_cursor","unsupported_version","method_not_allowed","payload_too_large","unsupported_media_type","conflict","raw_expired","too_many_accounts","idempotency_key_required","idempotency_key_reused","idempotency_in_flight","rate_limited","quota_exceeded","spend_cap_reached","tx_not_verified","period_locked","balance_mismatch","memo_pattern_invalid","memo_pattern_in_use","account_alias_ambiguous","allocation_exceeds_tx","invoice_over_allocated","no_eligible_checker","retryable","upgrade_required","service_unavailable","hoadon_unavailable","internal_error","ai_not_enabled","ai_paused","ai_task_unassigned","key_required","forecast_unavailable"],"description":"Mã lỗi ổn định (snake_case). Danh sách đầy đủ ở docs.dongtien.pro/errors."},"EventId":{"type":"string","pattern":"^evt_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã sự kiện (`evt_…`), ổn định qua retry.","example":"evt_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"EventListItem":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/EventId"},"type":{"type":"string"},"api_version":{"type":"string"},"payload":{},"created_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","type","api_version","created_at"]},"EventListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/EventListItem"}}},"required":["object","data"]},"EventTypeItem":{"type":"object","properties":{"type":{"type":"string"},"visibility":{"type":"string","enum":["public","internal"]},"when":{"type":"string"},"domain":{"type":"string"}},"required":["type","visibility","when","domain"]},"EventTypeListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/EventTypeItem"}}},"required":["object","data"]},"ExpectedPaymentId":{"type":"string","pattern":"^exp_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã khoản dự thu/chi (`exp_…`).","example":"exp_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"ExpectedPaymentList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ExpectedPaymentId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"kind":{"type":"string","enum":["order","cod","pr","obligation","other"]},"ref":{"type":"string"},"counterparty_id":{"anyOf":[{"$ref":"#/components/schemas/CounterpartyId"},{"type":"null"}]},"counterparty_name":{"type":["string","null"]},"counterparty_tax_code":{"type":["string","null"]},"amount":{"$ref":"#/components/schemas/PositiveVnd"},"paid_amount":{"$ref":"#/components/schemas/Vnd"},"state":{"type":"string","enum":["open","partial","paid","cancelled","expired"]},"due_date":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"expires_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"description":{"type":["string","null"]},"memo_code":{"type":["string","null"]}},"required":["id","org_id","kind","ref","amount","state"]}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"ExportAuditEvents":{"type":"object","properties":{"company_id":{"$ref":"#/components/schemas/OrgId"},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"ExportBatch":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ExportBatchId"},"code":{"type":"string","description":"Mã định danh hiển thị của lô (EXP-YYMM-NNN)."},"org_id":{"$ref":"#/components/schemas/OrgId"},"target":{"$ref":"#/components/schemas/ExportTarget"},"golden_version":{"type":"string","description":"Phiên bản mẫu golden file áp dụng."},"coa_profile_id":{"type":"string","format":"uuid","description":"Mã hồ sơ hệ thống tài khoản áp dụng."},"period":{"type":"string","pattern":"^[0-9]{6}$","description":"Kỳ kế toán (YYYYMM)."},"from_date":{"$ref":"#/components/schemas/Date"},"to_date":{"$ref":"#/components/schemas/Date"},"account_ids":{"type":"array","items":{"$ref":"#/components/schemas/AccountId"}},"voucher_types":{"type":"array","items":{"$ref":"#/components/schemas/VoucherType"}},"flags":{"$ref":"#/components/schemas/ExportFlags"},"state":{"$ref":"#/components/schemas/ExportBatchState"},"file_state":{"$ref":"#/components/schemas/ExportFileState"},"maker_user_id":{"$ref":"#/components/schemas/UserId"},"checker_user_id":{"anyOf":[{"$ref":"#/components/schemas/UserId"},{"type":"null"}]},"scope_hash":{"type":"string"},"mapping_version":{"type":"string"},"supersedes_id":{"anyOf":[{"$ref":"#/components/schemas/ExportBatchId"},{"type":"null"}]},"note_to_checker":{"type":["string","null"]},"ack_warnings":{"type":"boolean","default":false},"approved_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"rejected_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"reject_reason":{"type":["string","null"]},"file_error":{"type":["string","null"],"description":"Lý do sinh tệp thất bại (khi file_state = failed)."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","code","org_id","target","golden_version","coa_profile_id","period","from_date","to_date","account_ids","voucher_types","flags","state","file_state","maker_user_id","scope_hash","mapping_version","created_at","updated_at","ack_warnings"]},"ExportBatchDetail":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ExportBatchId"},"code":{"type":"string","description":"Mã định danh hiển thị của lô (EXP-YYMM-NNN)."},"org_id":{"$ref":"#/components/schemas/OrgId"},"target":{"$ref":"#/components/schemas/ExportTarget"},"golden_version":{"type":"string","description":"Phiên bản mẫu golden file áp dụng."},"coa_profile_id":{"type":"string","format":"uuid","description":"Mã hồ sơ hệ thống tài khoản áp dụng."},"period":{"type":"string","pattern":"^[0-9]{6}$","description":"Kỳ kế toán (YYYYMM)."},"from_date":{"$ref":"#/components/schemas/Date"},"to_date":{"$ref":"#/components/schemas/Date"},"account_ids":{"type":"array","items":{"$ref":"#/components/schemas/AccountId"}},"voucher_types":{"type":"array","items":{"$ref":"#/components/schemas/VoucherType"}},"flags":{"$ref":"#/components/schemas/ExportFlags"},"state":{"$ref":"#/components/schemas/ExportBatchState"},"file_state":{"$ref":"#/components/schemas/ExportFileState"},"maker_user_id":{"$ref":"#/components/schemas/UserId"},"checker_user_id":{"anyOf":[{"$ref":"#/components/schemas/UserId"},{"type":"null"}]},"scope_hash":{"type":"string"},"mapping_version":{"type":"string"},"supersedes_id":{"anyOf":[{"$ref":"#/components/schemas/ExportBatchId"},{"type":"null"}]},"note_to_checker":{"type":["string","null"]},"ack_warnings":{"type":"boolean","default":false},"approved_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"rejected_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"reject_reason":{"type":["string","null"]},"file_error":{"type":["string","null"],"description":"Lý do sinh tệp thất bại (khi file_state = failed)."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"files":{"type":"array","items":{"$ref":"#/components/schemas/ExportFile"},"default":[]},"checks":{"type":"array","items":{"$ref":"#/components/schemas/ExportCheckItem"},"default":[]}},"required":["id","code","org_id","target","golden_version","coa_profile_id","period","from_date","to_date","account_ids","voucher_types","flags","state","file_state","maker_user_id","scope_hash","mapping_version","created_at","updated_at","ack_warnings","files","checks"]},"ExportBatchId":{"type":"string","pattern":"^exb_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã lô xuất kế toán (`exb_…`).","example":"exb_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"ExportBatchList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/ExportBatch"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"ExportBatchState":{"type":"string","enum":["dry_run","pending_approval","approved","failed_validation","rejected","superseded"],"description":"Trạng thái lô xuất: dry_run, pending_approval, approved, failed_validation, rejected, superseded."},"ExportCheckItem":{"type":"object","properties":{"check_key":{"type":"string","description":"Mã kiểm tra (ví dụ: balanced, date_in_open_period)."},"severity":{"$ref":"#/components/schemas/ExportCheckSeverity"},"detail":{"type":"string","description":"Nội dung chi tiết kết quả kiểm tra."},"action":{"type":["string","null"],"description":"Hành động đề xuất khắc phục nếu có."}},"required":["check_key","severity","detail"]},"ExportCheckSeverity":{"type":"string","enum":["pass","warning","blocking"],"description":"Mức độ nghiêm trọng của kiểm tra: pass, warning (cảnh báo có thể tiếp tục), blocking (chặn xuất)."},"ExportDryRunBody":{"type":"object","properties":{"target":{"$ref":"#/components/schemas/ExportTarget"},"coa_profile":{"type":"string","description":"Mã hoặc id của hệ thống tài khoản (TT133 hoặc TT99).","example":"TT133"},"from":{"$ref":"#/components/schemas/Date"},"to":{"$ref":"#/components/schemas/Date"},"account_ids":{"type":"array","items":{"$ref":"#/components/schemas/AccountId"},"minItems":1},"voucher_types":{"type":"array","items":{"$ref":"#/components/schemas/VoucherType"},"minItems":1},"flags":{"$ref":"#/components/schemas/ExportFlags"}},"required":["target","coa_profile","from","to","account_ids","voucher_types"]},"ExportDryRunResponse":{"type":"object","properties":{"checks":{"type":"array","items":{"$ref":"#/components/schemas/ExportCheckItem"}},"can_submit":{"type":"boolean","description":"true nếu không có lỗi blocking nào."},"summary":{"type":"object","properties":{"total_entries":{"type":"integer"},"total_vouchers":{"type":"integer"},"total_debit":{"$ref":"#/components/schemas/Vnd"},"total_credit":{"$ref":"#/components/schemas/Vnd"},"voucher_counts":{"type":"object","properties":{"BC":{"type":"integer"},"BN":{"type":"integer"},"PT":{"type":"integer"},"PC":{"type":"integer"}}},"estimated_ranges":{"type":"object","properties":{"BC":{"type":"string"},"BN":{"type":"string"},"PT":{"type":"string"},"PC":{"type":"string"}}}},"required":["total_entries","total_vouchers","total_debit","total_credit","voucher_counts","estimated_ranges"]}},"required":["checks","can_submit","summary"]},"ExportFile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"batch_id":{"$ref":"#/components/schemas/ExportBatchId"},"r2_key":{"type":"string"},"name":{"type":"string"},"size":{"type":"integer"},"rows":{"type":"integer"},"sha256":{"type":"string"},"generated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","batch_id","r2_key","name","size","rows","sha256","generated_at"]},"ExportFileState":{"type":"string","enum":["pending","generating","ready","failed"],"description":"Trạng thái sinh tệp: pending, generating, ready, failed."},"ExportFlags":{"type":"object","properties":{"verified_only":{"type":"boolean","default":true,"description":"Chỉ xuất giao dịch đã xác thực (loại bỏ provisional)."},"invoice_no_in_memo":{"type":"boolean","default":false,"description":"Thêm số hoá đơn vào diễn giải chứng từ."},"cash_voucher_pairs":{"type":"boolean","default":false,"description":"Tạo cặp phiếu thu/chi tiền mặt tương ứng khi nộp/rút tiền."},"merge_bank_fee_daily":{"type":"boolean","default":false,"description":"Gộp các giao dịch phí ngân hàng cùng ngày thành một dòng."}}},"ExportPreviewLineList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"voucher_no":{"type":"string"},"voucher_type":{"$ref":"#/components/schemas/VoucherType"},"date":{"$ref":"#/components/schemas/Date"},"debit":{"type":"string"},"credit":{"type":"string"},"amount":{"$ref":"#/components/schemas/Vnd"},"description":{"type":"string"},"counterparty_code":{"type":["string","null"]}},"required":["voucher_no","voucher_type","date","debit","credit","amount","description"]}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"ExportReadiness":{"type":"object","properties":{"ready":{"type":"boolean","description":"true nếu sẵn sàng tạo lô xuất."},"period":{"type":"string","pattern":"^[0-9]{6}$"},"target":{"$ref":"#/components/schemas/ExportTarget"},"period_locked":{"type":"boolean"},"provisional_count":{"type":"integer"},"balance_anchor_mismatch":{"type":"boolean"},"unmapped_accounts_count":{"type":"integer"},"missing_counterparty_codes_count":{"type":"integer"},"blockers":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}}},"required":["ready","period","target","period_locked","provisional_count","balance_anchor_mismatch","unmapped_accounts_count","missing_counterparty_codes_count","blockers","warnings"]},"ExportTarget":{"type":"string","enum":["misa_amis","misa_sme","fast","excel_tt133","excel_tt99","misa_amis_api"],"description":"Đích xuất kế toán: MISA AMIS, MISA SME, Fast, Excel TT133, Excel TT99 hoặc OpenAPI MISA AMIS."},"ExportTransactions":{"type":"object","properties":{"format":{"type":"string","enum":["csv","json","xlsx"],"default":"csv"},"since":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"$ref":"#/components/schemas/Date"}]},"until":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"$ref":"#/components/schemas/Date"}]},"company_id":{"$ref":"#/components/schemas/OrgId"},"account_id":{"$ref":"#/components/schemas/AccountId"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"direction":{"type":"string","enum":["in","out"]},"include_quarantined":{"type":"boolean","default":false}}},"ExtendApiKey":{"type":"object","properties":{"expires_at":{"type":"string","format":"date-time"}},"required":["expires_at"],"example":{"expires_at":"2030-06-30T00:00:00+07:00"}},"FieldError":{"type":"object","properties":{"pointer":{"type":"string","description":"RFC 6901 JSON Pointer vào body, hoặc `#/query/<tên>`, `#/path/<tên>`, `#/header/<tên>`."},"detail":{"type":"string","description":"Mô tả lỗi của trường."},"code":{"type":"string","description":"Mã lỗi ngắn của trường (vd. `too_small`, `invalid_format`)."}},"required":["pointer","detail","code"]},"ForecastRunId":{"type":"string","pattern":"^fcr_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã lượt chạy dự báo dòng tiền (`fcr_…`).","example":"fcr_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"ForecastScenario":{"type":"string","enum":["base","conservative","optimistic"],"description":"Kịch bản dự báo dòng tiền: Cơ sở, Thận trọng, Lạc quan."},"HoadonConnectionId":{"type":"string","pattern":"^hdc_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã kết nối hoadon.pro (`hdc_…`).","example":"hdc_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"ImportCounterpartyCodesBody":{"type":"object","properties":{"target":{"$ref":"#/components/schemas/CounterpartyCodeTarget"},"rows":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":50},"mst":{"type":"string","maxLength":32},"name":{"type":"string","maxLength":255}},"required":["code"]},"minItems":1,"maxItems":5000}},"required":["target","rows"],"example":{"target":"misa_amis","rows":[{"code":"KH_VINHPHAT","mst":"0301234567","name":"CTY CP VAT LIEU XD VINH PHAT"}]}},"ImportCounterpartyCodesResult":{"type":"object","properties":{"matched":{"type":"integer","description":"Số dòng khớp một đối tác (theo MST, rồi theo tên) và đã lưu mã."},"unmatched":{"type":"integer","description":"Số dòng không khớp đối tác nào."},"conflicts":{"type":"integer","description":"Số dòng bị bỏ qua vì mã đã thuộc đối tác khác hoặc không hợp lệ cho đích."}},"required":["matched","unmatched","conflicts"]},"ImportCounts":{"type":"object","properties":{"processed":{"type":"integer","minimum":0,"description":"`new + merged + skipped` đã ghi."},"new":{"type":"integer","minimum":0,"description":"Giao dịch mới tạo (đã xác thực)."},"merged":{"type":"integer","minimum":0,"description":"Khớp giao dịch realtime sẵn có (nâng xác thực tại chỗ)."},"skipped":{"type":"integer","minimum":0,"description":"Trùng, bỏ qua."},"error":{"type":"integer","minimum":0,"description":"Dòng lỗi, không nhập."}},"required":["processed","new","merged","skipped","error"],"description":"Đếm theo dòng. Luôn có `processed = new + merged + skipped`; dòng lỗi tính riêng."},"Integration":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/IntegrationId"},"root_id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"kind":{"$ref":"#/components/schemas/IntegrationKind"},"name":{"type":"string","minLength":1,"maxLength":100},"direction":{"$ref":"#/components/schemas/IntegrationDirection"},"state":{"$ref":"#/components/schemas/IntegrationState"},"credential_hint":{"type":"string","description":"Phần gợi nhớ đã che của credential, vd: •••a3f9 hoặc @DongTienProBot"},"external_ref":{"type":["string","null"]},"settings":{"type":"object","additionalProperties":{},"default":{}},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"last_delivery_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"last_error":{"type":["string","null"]}},"required":["id","root_id","org_id","kind","name","direction","state","credential_hint","created_at","updated_at","settings"],"description":"Cấu hình một kết nối tích hợp trong tổ chức."},"IntegrationCatalogItem":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/IntegrationKind"},"name":{"type":"string"},"title":{"type":"string"},"category":{"type":"string","enum":["chat","commerce","webhook","sheet"]},"description":{"type":"string"},"direction":{"$ref":"#/components/schemas/IntegrationDirection"},"steps":{"type":"array","items":{"type":"object","properties":{"step":{"type":"integer","minimum":1},"title":{"type":"string"},"description":{"type":"string"}},"required":["step","title","description"]}},"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","password","url","oauth_button","select"]},"placeholder":{"type":"string"},"required":{"type":"boolean","default":true},"description":{"type":"string"}},"required":["key","label","type"]}},"platformConfigured":{"type":"boolean"},"oauthSupported":{"type":"boolean","default":false},"instructionsUrl":{"type":"string","format":"uri"}},"required":["kind","name","title","category","description","direction","steps","fields","platformConfigured","oauthSupported"],"description":"Mô tả một loại tích hợp trong danh mục tích hợp."},"IntegrationDelivery":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/IntegrationDeliveryId"},"integration_id":{"$ref":"#/components/schemas/IntegrationId"},"rule_id":{"type":["string","null"],"format":"uuid"},"event_id":{"type":"string"},"event_created_at":{"$ref":"#/components/schemas/Timestamp"},"state":{"$ref":"#/components/schemas/IntegrationDeliveryState"},"attempt":{"type":"integer","minimum":0},"http_status":{"type":["integer","null"]},"error":{"type":["string","null"]},"latency_ms":{"type":["integer","null"],"minimum":0},"is_test":{"type":"boolean","default":false},"next_retry_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"payload_preview":{"type":"string","description":"Bản xem trước nội dung đã che số tài khoản và thông tin nhạy cảm"},"created_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","integration_id","event_id","event_created_at","state","attempt","payload_preview","created_at","is_test"],"description":"Nhật ký một lần gửi thông báo ra tích hợp ngoài (lưu 30 ngày)."},"IntegrationDeliveryId":{"type":"string","pattern":"^idl_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã lượt gửi tin tích hợp (`idl_…`).","example":"idl_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"IntegrationDeliveryList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationDelivery"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"IntegrationDeliveryState":{"type":"string","enum":["queued","sending","delivered","retry_wait","failed","dead","skipped_filter","skipped_quiet","throttled"],"description":"Trạng thái gửi thông báo tích hợp."},"IntegrationDirection":{"type":"string","enum":["out","in","both"],"description":"Hướng dữ liệu: gửi ra (out), nhận vào (in) hoặc cả hai (both)."},"IntegrationEventType":{"type":"string","enum":["transaction.created","transaction.confirmed","payment.received","payment.partial","payment.overpaid","payment.expired","reconcile.proposed","invoice.payment_posted","invoice.payment_writeback_failed","channel.degraded","device.offline","security.new_location","quota.threshold","cashflow.alert","export.completed"],"description":"Sự kiện mà một quy tắc tích hợp có thể đăng ký."},"IntegrationId":{"type":"string","pattern":"^int_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã tích hợp (`int_…`).","example":"int_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"IntegrationKind":{"type":"string","enum":["lark","telegram","slack","discord","custom_webhook","woocommerce","haravan","shopify","lark_base","google_sheets"],"description":"Loại kênh / nền tảng tích hợp."},"IntegrationList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Integration"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"IntegrationRule":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"integration_id":{"$ref":"#/components/schemas/IntegrationId"},"org_id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":100},"events":{"type":"array","items":{"type":"string"},"minItems":1},"filters":{"$ref":"#/components/schemas/IntegrationRuleFilters"},"template_id":{"type":["string","null"],"format":"uuid"},"target":{"type":"object","additionalProperties":{}},"quiet_hours":{"type":"object","properties":{"enabled":{"type":"boolean"},"start":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"end":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"timezone":{"type":"string","default":"Asia/Ho_Chi_Minh"}},"required":["enabled","start","end"]},"show_balance":{"type":"boolean","default":false,"description":"D49: Gửi kèm số dư sau giao dịch (mặc định tắt vì bảng tính và chat nằm ngoài hệ thống)"},"enabled":{"type":"boolean","default":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","integration_id","org_id","name","events","filters","created_at","updated_at","show_balance","enabled"],"description":"Quy tắc định tuyến và lọc sự kiện cho một kết nối tích hợp."},"IntegrationRuleFilters":{"type":"object","properties":{"account_ids":{"type":"array","items":{"type":"string"}},"direction":{"type":"string","enum":["in","out","both"]},"min_amount":{"$ref":"#/components/schemas/Vnd"},"max_amount":{"$ref":"#/components/schemas/Vnd"},"mst":{"type":"array","items":{"type":"string"}},"memo_code_only":{"type":"boolean"},"include_provisional":{"type":"boolean","default":false},"memo_pattern_id":{"$ref":"#/components/schemas/MemoPatternId"},"memo_regex":{"type":"string","maxLength":128}},"description":"Bộ lọc giao dịch/sự kiện trước khi gửi ra kênh ngoài."},"IntegrationState":{"type":"string","enum":["draft","connected","test_ok","active","degraded","error","paused","revoked"],"description":"Trạng thái tích hợp theo máy trạng thái state-machines.md §11."},"IntegrationTemplate":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":["string","null"],"format":"uuid","description":"null nếu là mẫu mặc định toàn hệ thống"},"kind":{"$ref":"#/components/schemas/IntegrationKind"},"event":{"type":"string"},"locale":{"type":"string","enum":["vi"],"default":"vi"},"body":{"type":"string","minLength":1},"version":{"type":"integer","exclusiveMinimum":0,"default":1},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","org_id","kind","event","body","created_at","updated_at","locale","version"],"description":"Mẫu tin nhắn tiếng Việt cho thông báo tích hợp."},"Invitation":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/InvitationId"},"email":{"type":"string"},"org_id":{"type":"string","pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Nút sẽ giữ vai trò: nút gốc hoặc một công ty.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"role":{"type":"string","description":"Khoá vai trò được mời (xem `GET /v1/roles`)."},"scope":{"type":"string","enum":["all","list"],"description":"`all`: mọi công ty của nút; `list`: chỉ các công ty trong `company_ids` (chỉ ở nút gốc)."},"company_ids":{"type":"array","items":{"$ref":"#/components/schemas/OrgId"}},"require_2fa":{"type":"boolean"},"state":{"type":"string","enum":["pending","accepted","revoked","expired"]},"invited_by":{"$ref":"#/components/schemas/UserId"},"sent_at":{"$ref":"#/components/schemas/Timestamp"},"expires_at":{"$ref":"#/components/schemas/Timestamp"},"resend_count":{"type":"integer"},"accepted_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"revoked_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"created_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","email","org_id","role","scope","company_ids","require_2fa","state","invited_by","sent_at","expires_at","resend_count","accepted_at","revoked_at","created_at"],"description":"Lời mời tham gia một nút tổ chức."},"InvitationCreated":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/InvitationId"},"email":{"type":"string"},"org_id":{"type":"string","pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Nút sẽ giữ vai trò: nút gốc hoặc một công ty.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"role":{"type":"string","description":"Khoá vai trò được mời (xem `GET /v1/roles`)."},"scope":{"type":"string","enum":["all","list"],"description":"`all`: mọi công ty của nút; `list`: chỉ các công ty trong `company_ids` (chỉ ở nút gốc)."},"company_ids":{"type":"array","items":{"$ref":"#/components/schemas/OrgId"}},"require_2fa":{"type":"boolean"},"state":{"type":"string","enum":["pending","accepted","revoked","expired"]},"invited_by":{"$ref":"#/components/schemas/UserId"},"sent_at":{"$ref":"#/components/schemas/Timestamp"},"expires_at":{"$ref":"#/components/schemas/Timestamp"},"resend_count":{"type":"integer"},"accepted_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"revoked_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"email_delivery":{"type":"string","enum":["queued","unavailable"],"description":"`queued`: email đang được gửi; `unavailable`: chưa cấu hình dịch vụ email nên chưa ai nhận được liên kết."}},"required":["id","email","org_id","role","scope","company_ids","require_2fa","state","invited_by","sent_at","expires_at","resend_count","accepted_at","revoked_at","created_at","email_delivery"],"description":"Lời mời vừa tạo hoặc gửi lại, kèm tình trạng gửi email."},"InvitationId":{"type":"string","pattern":"^ivt_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã lời mời (`ivt_…`).","example":"ivt_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"InvitationList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Invitation"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"InvitationPreview":{"type":"object","properties":{"org_display_name":{"type":"string","description":"Tên tổ chức (hoặc công ty) đã mời bạn."},"role_key":{"type":"string","description":"Khoá vai trò được mời."},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Thời điểm liên kết hết hiệu lực.","example":"2026-10-19T01:30:15Z"}},"required":["org_display_name","role_key","expires_at"],"description":"Thông tin tối thiểu để trang lời mời hiển thị trước khi người nhận đăng nhập."},"InvoiceRefId":{"type":"string","pattern":"^inv_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã tham chiếu hoá đơn (`inv_…`).","example":"inv_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"InvoiceRefList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/InvoiceRefId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"direction":{"type":"string","enum":["in","out"]},"seller_tax_code":{"type":"string"},"seller_name":{"type":"string"},"buyer_tax_code":{"type":["string","null"]},"buyer_name":{"type":["string","null"]},"template_code":{"type":"string"},"series":{"type":"string"},"number":{"type":"string"},"issue_date":{"$ref":"#/components/schemas/Timestamp"},"due_date":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"currency":{"$ref":"#/components/schemas/Currency"},"total_amount":{"$ref":"#/components/schemas/Vnd"},"external_paid":{"$ref":"#/components/schemas/Vnd"},"dtp_allocated":{"$ref":"#/components/schemas/Vnd"},"outstanding_amount":{"$ref":"#/components/schemas/Vnd"},"payment_status":{"type":"string","enum":["unpaid","partially_paid","paid","overpaid"]},"lookup_code":{"type":["string","null"]},"hoadon_id":{"type":["string","null"]}},"required":["id","org_id","direction","seller_tax_code","seller_name","template_code","series","number","issue_date","total_amount","outstanding_amount","payment_status"]}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"IosBankKeyword":{"type":"object","properties":{"bank_code":{"type":"string","example":"VCB"},"brand":{"type":"string","example":"Vietcombank"},"name":{"type":["string","null"]},"keywords":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"minItems":1,"description":"Từ khoá cho bộ lọc `Message Contains` của automation (hoặc của ô tìm trong Shortcuts)."}},"required":["bank_code","brand","name","keywords"]},"IosBankKeywordList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/IosBankKeyword"}}},"required":["object","data"]},"IosBankStatus":{"type":"string","enum":["not_created","untested","active","parse_error"],"description":"`not_created`: chưa tạo automation. `untested`: đã bấm \"Đã tạo\" nhưng chưa có tin. `active`: đã nhận tin. `parse_error`: hôm nay ≥ 3 tin không đọc được và chưa có tin đọc được (sửa từ khoá)."},"IosDeviceCredential":{"type":"object","properties":{"object":{"type":"string","enum":["ios_device_credential"]},"device":{"$ref":"#/components/schemas/Device"},"token":{"type":"string","pattern":"^dtd_[0-9A-HJKMNP-TV-Z]{26}$","example":"dtd_7K2M9QXH0P4T6V8W1Y3Z5BCDFG","description":"Token `dtd_…` của Shortcut. CHỈ hiện ở lần trả lời này; chỉ lưu băm SHA-256. Mất token phải xoay token (mã cũ còn dùng được 30 phút)."},"token_last4":{"type":"string","minLength":4,"maxLength":4,"description":"4 ký tự cuối, hiển thị sau này."}},"required":["object","device","token","token_last4"],"description":"Thiết bị iPhone kèm token hiện một lần. Phản hồi có `Cache-Control: no-store`."},"IosShortcutRelease":{"type":"object","properties":{"object":{"type":"string","enum":["ios_shortcut_release"]},"id":{"$ref":"#/components/schemas/AppReleaseId"},"version":{"type":"string","example":"1.3.0"},"version_code":{"type":"integer","exclusiveMinimum":0},"icloud_url":{"type":"string","format":"uri","description":"Liên kết iCloud của file Shortcut đã ký."},"import_questions":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"prompt":{"type":"string"}},"required":["key","prompt"]},"description":"Câu hỏi khi nhập Shortcut (vd. dán token `dtd_…`)."},"min_ios":{"type":["string","null"],"example":"17.0"},"release_notes":{"type":"array","items":{"type":"string"}},"published_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["object","id","version","version_code","icloud_url","import_questions","min_ios","release_notes","published_at"],"description":"Bản Shortcut mới nhất; phiên bản độc lập với Android."},"IosSmsTest":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ChannelTestId"},"object":{"type":"string","enum":["channel_test"]},"kind":{"type":"string","enum":["sms"]},"device_id":{"$ref":"#/components/schemas/DeviceId"},"state":{"type":"string","enum":["pending","received","expired","failed"]},"memo_code":{"type":"string","example":"DTPK7M2QX","description":"Mã ghi vào nội dung chuyển khoản thử (`TEST DTP…`); tin SMS của ngân hàng phải chứa mã này."},"amount_vnd":{"type":"integer","description":"Số tiền gợi ý chuyển thử (VND)."},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Hết hạn sau 90 giây.","example":"2026-10-19T01:30:15Z"},"result":{"anyOf":[{"$ref":"#/components/schemas/IosSmsTestResult"},{"type":"null"}]}},"required":["id","object","kind","device_id","state","memo_code","amount_vnd","expires_at","result"]},"IosSmsTestResult":{"type":"object","properties":{"parsed":{"type":"boolean"},"bank_code":{"type":["string","null"]},"amount_masked":{"type":["string","null"],"description":"Số tiền đã che, vd. `10.***₫`."},"latency_ms":{"type":["integer","null"],"minimum":0,"description":"Từ lúc máy chủ nhận tin tới lúc đọc xong."},"raw_id":{"type":["string","null"]}},"required":["parsed","bank_code","amount_masked","latency_ms","raw_id"]},"Job":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/JobId"},"object":{"type":"string","enum":["job"]},"kind":{"$ref":"#/components/schemas/JobKind"},"state":{"$ref":"#/components/schemas/JobState"},"progress":{"$ref":"#/components/schemas/JobProgress"},"result":{"type":"object","additionalProperties":{},"description":"Kết quả khi `succeeded` (cấu trúc tuỳ `kind`)."},"error":{"$ref":"#/components/schemas/JobError"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"finished_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["id","object","kind","state","progress","created_at","finished_at"],"description":"Tác vụ bất đồng bộ."},"JobAccepted":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"}},"required":["job"]},"JobError":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"detail":{"type":"string"}},"required":["code"],"description":"Lý do thất bại, cùng mã lỗi với API (không có chi tiết nội bộ)."},"JobId":{"type":"string","pattern":"^job_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã tác vụ bất đồng bộ (`job_…`).","example":"job_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"JobKind":{"type":"string","pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$","description":"Loại tác vụ, dạng `miền.hành_động` (vd. `import.statement`).","example":"import.statement"},"JobProgress":{"type":"object","properties":{"done":{"type":"integer","minimum":0},"total":{"type":["integer","null"],"minimum":0,"description":"`null` khi chưa biết tổng."},"unit":{"type":"string","description":"Đơn vị đếm, vd. `rows`, `transactions`."},"message":{"type":"string"}},"required":["done","total"]},"JobState":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"LockPeriodRequest":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"]},"ManualVerifyTransaction":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500},"evidence":{"type":"string","minLength":3,"maxLength":2000,"description":"Bằng chứng người duyệt đã đối chiếu (ví dụ: sao kê, cuộc gọi ngân hàng). Ghi nhật ký kiểm toán."}},"required":["reason","evidence"],"example":{"reason":"Đã đối chiếu sao kê","evidence":"Sao kê VCB ngày 19/10, dòng 12"}},"MappingChange":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ApprovalRequestId"},"subject_type":{"type":"string","enum":["bank_account_gl_map","mapping_rule"]},"subject_id":{"type":"string","description":"Id dòng ánh xạ, hoặc `<id quy tắc>:<phiên bản>` với quy tắc định khoản."},"state":{"type":"string","enum":["pending","approved","rejected","withdrawn","expired"]},"maker_user_id":{"$ref":"#/components/schemas/UserId"},"checker_user_id":{"anyOf":[{"$ref":"#/components/schemas/UserId"},{"type":"null"}]},"decision_reason":{"type":["string","null"]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"decided_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["id","subject_type","subject_id","state","maker_user_id","created_at"]},"MappingChangeList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/MappingChange"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"MappingProposalResult":{"type":"object","properties":{"approval_id":{"$ref":"#/components/schemas/ApprovalRequestId"},"rule_ids":{"type":"array","items":{"$ref":"#/components/schemas/MappingRuleId"}}},"required":["approval_id","rule_ids"]},"MappingRule":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/MappingRuleId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"profile_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"conditions":{"type":"object","additionalProperties":{}},"voucher_type":{"$ref":"#/components/schemas/VoucherType"},"debit_account":{"type":"string"},"credit_account":{"type":"string"},"detail_account":{"type":["string","null"]},"counterparty_rule":{"type":["object","null"],"additionalProperties":{}},"case_code_required":{"type":"boolean","default":false},"vat_rate":{"type":["number","null"]},"revenue_account":{"type":["string","null"]},"vat_account":{"type":["string","null"]},"source":{"type":"string","enum":["rule","ai_accepted"],"default":"rule"},"priority":{"type":"integer","default":100},"state":{"type":"string","enum":["draft","pending_approval","active","disabled"],"default":"active"},"effective_from":{"$ref":"#/components/schemas/Date"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","org_id","profile_id","name","conditions","voucher_type","debit_account","credit_account","effective_from","created_at","updated_at","case_code_required","source","priority","state"]},"MappingRuleDraft":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Thu tiền khách hàng qua ngân hàng"},"conditions":{"type":"object","additionalProperties":{},"default":{}},"voucher_type":{"$ref":"#/components/schemas/VoucherType"},"debit_account":{"type":"string","minLength":3,"example":"1121"},"credit_account":{"type":"string","minLength":3,"example":"131"},"detail_account":{"type":"string"},"counterparty_rule":{"type":"object","additionalProperties":{}},"case_code_required":{"type":"boolean","default":false},"vat_rate":{"type":"number"},"revenue_account":{"type":"string"},"vat_account":{"type":"string"},"priority":{"type":"integer","default":100},"effective_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Mặc định: hôm nay (giờ Việt Nam).","example":"2026-10-19"}},"required":["name","voucher_type","debit_account","credit_account"]},"MappingRuleId":{"type":"string","pattern":"^map_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã quy tắc định khoản (`map_…`).","example":"map_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"MappingRuleList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/MappingRule"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"MappingTemplate":{"type":"object","properties":{"id":{"type":"string","example":"tt133-standard"},"system":{"type":"string","enum":["TT133","TT99"]},"name":{"type":"string"},"description":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/MappingRuleDraft"}}},"required":["id","system","name","description","rules"]},"MappingTemplateList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MappingTemplate"}}},"required":["data"]},"MarketplaceOrderId":{"type":"string","pattern":"^mko_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã đơn hàng sàn nội bộ (`mko_…`).","example":"mko_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"MatchRuleId":{"type":"string","pattern":"^rul_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã quy tắc đối soát (`rul_…`).","example":"rul_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"MatchRuleList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/MatchRuleId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"name":{"type":"string"},"description":{"type":"string"},"kind_label":{"type":"string"},"direction":{"type":"string","enum":["in","out","both"]},"strategy":{"type":"string","enum":["one_to_one","one_to_many","many_to_one"]},"priority":{"type":"integer"},"base_confidence":{"type":["number","null"]},"conds":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string","enum":["=","exists","<",">","<=",">=","in","contains"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"required":["field","op","value"]}},"bonus":{"type":"array","items":{"type":"object","properties":{"tone":{"type":"string","enum":["y","w","n"]},"description":{"type":"string"},"delta":{"type":"number"}},"required":["tone","description"]}},"tolerance_vnd":{"type":"integer","default":1000},"window_days":{"type":"integer","default":45},"mode":{"type":"string","enum":["suggest_only","one_tap_ge_95"]},"is_enabled":{"type":"boolean"},"is_locked":{"type":"boolean"},"version":{"type":"integer"},"eval_count_30d":{"type":"integer"},"accepted_count_30d":{"type":"integer"},"acceptance_rate_30d":{"type":"number"},"flagged_review":{"type":"boolean"}},"required":["id","org_id","name","description","kind_label","direction","strategy","priority","base_confidence","conds","mode","is_enabled","is_locked","version"]}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"Me":{"type":"object","properties":{"principal":{"$ref":"#/components/schemas/MePrincipal"},"org":{"type":["object","null"],"properties":{"id":{"$ref":"#/components/schemas/OrgId"},"name":{"type":"string"},"mst":{"type":["string","null"]}},"required":["id","name","mst"]},"active_root_id":{"type":["string","null"],"pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Gốc tổ chức phiên đang làm việc (đổi bằng `POST /v1/me/root:switch`); `null` khi chưa có tổ chức.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"mst":{"type":["string","null"]},"mode":{"type":"string","enum":["live","sandbox"]},"scopes":{"type":"array","items":{"type":"string"}},"companies":{"type":"array","items":{"$ref":"#/components/schemas/MeCompany"}},"flags":{"type":"object","additionalProperties":{"type":"boolean"},"description":"Cờ tính năng đang bật cho người gọi (tên → `true`/`false`). Chỉ để giao diện ẩn/hiện; máy chủ vẫn kiểm quyền ở mỗi yêu cầu."},"impersonation":{"type":"object","properties":{"ticket":{"type":"string","description":"Phiếu hỗ trợ đã mở phiên (`SUP-nnnn`)."},"ends_at":{"type":"string","description":"Thời điểm phiên hỗ trợ kết thúc (RFC 3339, UTC)."},"scope":{"type":"string","enum":["read_only"],"description":"Phiên hỗ trợ luôn chỉ-đọc."}},"required":["ticket","ends_at","scope"],"description":"Chỉ có khi người gọi là nhân viên hỗ trợ đang xem hộ khách hàng."}},"required":["principal","org","active_root_id","mst","mode","scopes","companies","flags"],"description":"Người gọi, các công ty truy cập được và chế độ chạy."},"MeCompany":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/OrgId"},"name":{"type":"string"},"mst":{"type":["string","null"]},"kind":{"type":"string","enum":["root","company"]},"role":{"type":["string","null"],"description":"Vai trò của người gọi tại công ty này (người dùng, OAuth); `null` với khoá API (khoá dùng phạm vi, không dùng vai trò)."}},"required":["id","name","mst","kind","role"],"description":"Một nút tổ chức người gọi truy cập được."},"MePrincipal":{"type":"object","properties":{"type":{"type":"string","enum":["user","api_key","oauth","impersonation"]},"id":{"type":"string","description":"`usr_…` của người dùng hoặc `apk_…` của khoá API (mã cấp quyền với OAuth)."},"user_id":{"type":["string","null"],"pattern":"^usr_[0-9a-hjkmnp-tv-z]{26}$","description":"Người đứng sau thông tin xác thực (người tạo khoá, người cấp quyền OAuth).","example":"usr_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"session_id":{"type":["string","null"]},"key_env":{"type":["string","null"],"enum":["live","test",null]},"client_id":{"type":["string","null"]}},"required":["type","id","user_id","session_id","key_env","client_id"],"description":"Chủ thể đang gọi API."},"MeRoot":{"type":"object","properties":{"id":{"type":"string","pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã gốc tổ chức.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"name":{"type":"string"},"is_accounting_firm":{"type":"boolean","description":"Gốc là hãng kế toán (quản lý nhiều khách hàng)."},"role_key":{"type":"string","description":"Vai trò tốt nhất của người dùng tại gốc này."},"has_root_node":{"type":"boolean","description":"Có thành viên ở chính nút gốc (`false`: khách hàng chỉ sở hữu một công ty)."},"first_joined_at":{"$ref":"#/components/schemas/Timestamp"},"active":{"type":"boolean","description":"Đây là gốc phiên hiện tại đang làm việc."}},"required":["id","name","is_accounting_firm","role_key","has_root_node","first_joined_at","active"],"description":"Một gốc tổ chức mà người dùng thuộc về."},"MeRootList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/MeRoot"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"Member":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/MemberId"},"user_id":{"$ref":"#/components/schemas/UserId"},"email":{"type":"string"},"name":{"type":"string"},"org_id":{"type":"string","pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Nút giữ vai trò: nút gốc (toàn tổ chức) hoặc một công ty.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"role":{"type":"string","enum":["owner","admin","accountant_chief","accountant","developer","viewer","auditor"],"description":"Vai trò hệ thống: `owner`, `admin`, `accountant_chief`, …"},"scope":{"type":"string","enum":["all","list"],"description":"`all`: mọi công ty của nút; `list`: chỉ các công ty trong `company_ids` (chỉ ở nút gốc)."},"company_ids":{"type":"array","items":{"$ref":"#/components/schemas/OrgId"},"description":"Các công ty của phạm vi `list`; rỗng với phạm vi `all`."},"require_2fa":{"type":"boolean"},"two_factor_enabled":{"type":"boolean"},"status":{"type":"string","enum":["active","invited"]},"first_login_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"last_active_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"created_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","user_id","email","name","org_id","role","scope","company_ids","require_2fa","two_factor_enabled","status","first_login_at","last_active_at","created_at"],"description":"Thành viên: một người giữ một vai trò tại một nút tổ chức."},"MemberId":{"type":"string","pattern":"^mbr_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã thành viên (`mbr_…`): một vai trò tại một nút tổ chức.","example":"mbr_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"MemberList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Member"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"MemoPatternId":{"type":"string","pattern":"^omp_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã mẫu mã đơn của công ty (`omp_…`).","example":"omp_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"MisaConnection":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/MisaConnectionId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"org_company_code":{"type":"string","description":"Mã định danh công ty nguồn trong MISA (dtp-<org>)."},"access_code_last4":{"type":"string","minLength":4,"maxLength":4,"description":"4 ký tự cuối của mã kết nối (mã đầy đủ không bao giờ trả về qua API)."},"branch_id":{"type":["string","null"],"description":"Mã chi nhánh trong MISA AMIS (organization_unit_id)."},"state":{"$ref":"#/components/schemas/MisaConnectionState"},"dict_last_sync_time":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"last_tested_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"callback_verified_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"last_error_code":{"type":["string","null"]},"last_error_message":{"type":["string","null"]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","org_id","org_company_code","access_code_last4","state","created_at","updated_at"]},"MisaConnectionId":{"type":"string","pattern":"^msc_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã kết nối MISA AMIS (`msc_…`).","example":"msc_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"MisaConnectionState":{"type":"string","enum":["draft","ok","invalid_code","disconnected"],"description":"Trạng thái kết nối MISA: draft (mới tạo), ok (hoạt động), invalid_code (mã kết nối không hợp lệ), disconnected (đã ngắt kết nối)."},"MisaConnectionTestResult":{"type":"object","properties":{"success":{"type":"boolean"},"branch_id":{"type":["string","null"]},"branches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"default":[]},"bank_accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"account_number":{"type":"string"},"bank_name":{"type":"string"}},"required":["id","account_number","bank_name"]},"default":[]},"error_code":{"type":["string","null"]},"error_message":{"type":["string","null"]}},"required":["success","branch_id","branches","bank_accounts"]},"MisaDictionaryItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"$ref":"#/components/schemas/MisaConnectionId"},"kind":{"$ref":"#/components/schemas/MisaDictionaryKind"},"local_ref":{"type":"string","format":"uuid","description":"ID tài khoản ngân hàng hoặc đối tác nội bộ."},"code":{"type":"string","description":"Số TK ngân hàng hoặc mã đối tượng trong MISA."},"dict_id":{"type":"string","format":"uuid"},"misa_guid":{"type":["string","null"],"format":"uuid"},"state":{"type":"string","enum":["unmapped","pending_create","confirmed","missing","inactive"]},"last_polled_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"confirmed_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","connection_id","kind","local_ref","code","dict_id","state","created_at","updated_at"]},"MisaDictionaryKind":{"type":"string","enum":["bank_account","account_object"],"description":"Loại danh mục MISA: bank_account (tài khoản ngân hàng) hoặc account_object (khách hàng/nhà cung cấp)."},"MisaVoucherRequest":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/MisaVoucherRequestId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"connection_id":{"$ref":"#/components/schemas/MisaConnectionId"},"export_batch_id":{"$ref":"#/components/schemas/ExportBatchId"},"tx_id":{"$ref":"#/components/schemas/TxId"},"tx_occurred_at":{"$ref":"#/components/schemas/Timestamp"},"version":{"type":"integer","default":1},"voucher_type":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[3]}],"description":"1: Thu tiền gửi (ba_deposit), 3: Chi tiền gửi (ba_withdraw)."},"reftype":{"anyOf":[{"type":"number","enum":[1500]},{"type":"number","enum":[1510]}],"description":"1500: Thu tiền gửi, 1510: Ủy nhiệm chi."},"org_refid":{"type":"string","format":"uuid","description":"Khoá idempotent (UUIDv5) gửi sang MISA."},"org_refno":{"type":"string","description":"Mã giao dịch ngân hàng gốc."},"reason_type_id":{"type":"integer"},"amount":{"$ref":"#/components/schemas/Vnd"},"state":{"$ref":"#/components/schemas/MisaVoucherRequestState"},"dictionary_pending":{"type":"boolean"},"attempts":{"type":"integer"},"next_retry_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"sent_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"result_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"error_code":{"type":["string","null"]},"error_message":{"type":["string","null"]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","org_id","connection_id","export_batch_id","tx_id","tx_occurred_at","voucher_type","reftype","org_refid","org_refno","reason_type_id","amount","state","dictionary_pending","attempts","created_at","updated_at","version"]},"MisaVoucherRequestId":{"type":"string","pattern":"^mvr_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã đề nghị chứng từ MISA AMIS (`mvr_…`).","example":"mvr_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"MisaVoucherRequestList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/MisaVoucherRequest"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"MisaVoucherRequestState":{"type":"string","enum":["queued","blocked","sent","generated","failed_generation","posted_inferred","unconfirmed","superseded","dead"],"description":"Trạng thái đề nghị chứng từ MISA: queued, blocked, sent, generated, failed_generation, posted_inferred, unconfirmed, superseded, dead."},"MstLookup":{"type":"object","properties":{"mst":{"type":"string","description":"Mã số thuế dạng chuẩn."},"checksum_ok":{"type":"boolean","description":"Chữ số kiểm tra chỉ mang tính tham khảo: MST sai checksum vẫn được tra cứu."},"company":{"type":"object","properties":{"tax_code":{"type":"string"},"legal_name":{"type":"string"},"short_name":{"type":["string","null"]},"address":{"type":["string","null"]},"legal_rep":{"type":["string","null"]},"status_code":{"type":["string","null"]},"status_label":{"type":["string","null"]},"active":{"type":"boolean"}},"required":["tax_code","legal_name","short_name","address","legal_rep","status_code","status_label","active"]},"fetched_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Thời điểm lấy bản sao này.","example":"2026-10-19T01:30:15Z"},"source":{"type":"string","enum":["kv","api","store"],"description":"Nguồn: bộ nhớ đệm, nguồn MST hoặc bản đã lưu."},"stale":{"type":"boolean","description":"`true` khi nguồn đang lỗi và đây là bản đã lưu."},"stale_reason":{"type":"string"}},"required":["mst","checksum_ok","company","fetched_at","source","stale"],"description":"Thông tin doanh nghiệp theo mã số thuế."},"MstSource":{"type":"object","properties":{"status":{"type":"string","enum":["found","unavailable","not_found"],"description":"`found`: có dữ liệu; `unavailable`: nguồn MST không trả lời; `not_found`: nguồn không biết mã số thuế này."},"stale":{"type":"boolean","description":"`true`: dữ liệu là bản đã lưu lần trước vì nguồn đang lỗi."},"checksum_ok":{"type":"boolean","description":"Chữ số kiểm tra của mã số thuế hợp lệ (chỉ là cảnh báo)."}},"required":["status","stale","checksum_ok"],"description":"Kết quả tra cứu mã số thuế."},"Obligation":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ObligationId"},"code":{"type":"string","pattern":"^OB-\\d{4}-\\d{4}$"},"org_id":{"$ref":"#/components/schemas/OrgId"},"direction":{"$ref":"#/components/schemas/ObligationDirection"},"partner_id":{"$ref":"#/components/schemas/PartnerId"},"partner_name":{"type":"string"},"total":{"$ref":"#/components/schemas/PositiveVnd"},"paid":{"$ref":"#/components/schemas/Vnd"},"left":{"$ref":"#/components/schemas/Vnd"},"state":{"$ref":"#/components/schemas/ObligationState"},"is_overdue":{"type":"boolean","default":false},"due_date":{"$ref":"#/components/schemas/Date"},"source":{"$ref":"#/components/schemas/ObligationSource"},"split_rule_id":{"anyOf":[{"$ref":"#/components/schemas/SplitRuleId"},{"type":"null"}]},"split_rule_version":{"type":["integer","null"]},"composition":{"$ref":"#/components/schemas/ObligationComposition"},"suggested_memo":{"type":"string","pattern":"^DTP[0-9A-HJKMNP-TV-Z]{6}$"},"payout_id":{"anyOf":[{"$ref":"#/components/schemas/PayoutId"},{"type":"null"}]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","code","org_id","direction","partner_id","total","state","due_date","source","created_at","updated_at","paid","left","is_overdue"],"description":"Nghĩa vụ thanh toán phải thu / phải trả."},"ObligationAllocation":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ObligationAllocationId"},"obligation_id":{"$ref":"#/components/schemas/ObligationId"},"tx_id":{"$ref":"#/components/schemas/TxId"},"amount":{"$ref":"#/components/schemas/PositiveVnd"},"state":{"$ref":"#/components/schemas/ObligationAllocationState"},"maker_user_id":{"$ref":"#/components/schemas/UserId"},"checker_user_id":{"anyOf":[{"$ref":"#/components/schemas/UserId"},{"type":"null"}]},"self_approved":{"type":"boolean","default":false},"overpay_amount":{"$ref":"#/components/schemas/Vnd"},"overpay_handling":{"type":["string","null"],"enum":["credit_next","refund_reminder",null]},"reject_reason":{"type":["string","null"]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"approved_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["id","obligation_id","tx_id","amount","state","maker_user_id","created_at","self_approved","overpay_amount"],"description":"Bút toán gạch nợ nghĩa vụ gắn với giao dịch ngân hàng đã xác thực."},"ObligationAllocationId":{"type":"string","pattern":"^ola_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã gạch nợ nghĩa vụ (`ola_…`).","example":"ola_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"ObligationAllocationState":{"type":"string","enum":["pending","approved","rejected"],"description":"`pending` chờ duyệt · `approved` đã duyệt · `rejected` từ chối."},"ObligationComposition":{"type":"object","properties":{"items_count":{"type":"integer","minimum":0},"platforms":{"type":"object","additionalProperties":{"type":"string"}},"brands":{"type":"object","additionalProperties":{"type":"string"}},"carry_in_amount":{"$ref":"#/components/schemas/Vnd"},"summary_text":{"type":"string"}},"required":["items_count"],"description":"Cấu thành số liệu nghĩa vụ (sản phẩm, tỷ lệ sàn, khoản mang sang)."},"ObligationDirection":{"type":"string","enum":["in","out"],"description":"`in` phải thu · `out` phải trả."},"ObligationId":{"type":"string","pattern":"^obl_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã nghĩa vụ thanh toán (`obl_…`).","example":"obl_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"ObligationLine":{"type":"object","properties":{"id":{"type":"string"},"obligation_id":{"$ref":"#/components/schemas/ObligationId"},"kind":{"type":"string","enum":["accrual","allocation","refund_adjustment","reversal","credit"]},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Số tiền có dấu (dương hoặc âm)","example":4500000},"order_id":{"anyOf":[{"$ref":"#/components/schemas/MarketplaceOrderId"},{"type":"null"}]},"ref_id":{"type":["string","null"]},"created_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","obligation_id","kind","amount","created_at"],"description":"Dòng chi tiết cấu thành nghĩa vụ thanh toán."},"ObligationList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Obligation"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"ObligationSource":{"type":"string","enum":["split_rule","invoice","payout_statement"],"description":"`split_rule` sinh từ quy tắc chia · `invoice` sinh từ hoá đơn · `payout_statement` sinh từ sao kê sàn."},"ObligationState":{"type":"string","enum":["not_due","awaiting_payout","partially_settled","settled","variance"],"description":"`not_due` chưa đến hạn · `awaiting_payout` chờ payout · `partially_settled` đã gạch một phần · `settled` tất toán · `variance` chênh lệch."},"OnboardingDraft":{"type":"object","properties":{"step":{"type":"string","enum":["b1","b2","done"]},"data":{"type":"object","additionalProperties":{}},"updated_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["step","data","updated_at"],"description":"Bản nháp các bước làm quen (hồ sơ → công ty), lưu trên máy chủ để tiếp tục khi đổi trình duyệt. Chưa lưu lần nào: bước `b1`, `data` rỗng, `updated_at` null."},"OpenApiDocument":{"type":"object","additionalProperties":{},"description":"Tài liệu OpenAPI (JSON)."},"Org":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/OrgId"},"kind":{"type":"string","description":"`root` (văn phòng kế toán / doanh nghiệp) hoặc `company` (một mã số thuế).","example":"company"},"parent_id":{"type":["string","null"],"pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Tổ chức gốc chứa công ty; `null` với `root`.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"root_id":{"$ref":"#/components/schemas/OrgId"},"name":{"type":"string","description":"Tên gọi trong hệ thống."},"mst":{"type":["string","null"],"description":"Mã số thuế (10 hoặc 13 số, không có dấu gạch)."},"mst_synced_at":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Lần cuối đồng bộ hồ sơ pháp lý từ nguồn MST; `null` nếu chưa từng.","example":"2026-10-19T01:30:15Z"},"legal_name":{"type":["string","null"],"description":"Tên pháp lý theo nguồn MST."},"address":{"type":["string","null"]},"legal_rep":{"type":["string","null"],"description":"Người đại diện pháp luật."},"alert_email":{"type":["string","null"],"maxLength":254,"format":"email","description":"Email nhận cảnh báo kênh / tiền vào của công ty. Để trống: gửi tới các chủ sở hữu.","example":"ketoan@congty.vn"},"entity_type":{"type":["string","null"]},"display_name":{"type":["string","null"],"description":"Tên hiển thị trên mã VietQR: chữ in hoa không dấu, tối đa 25 ký tự."},"is_accounting_firm":{"type":"boolean"},"coa_profile":{"type":"string","enum":["TT133","TT99"],"description":"Hệ thống tài khoản kế toán: Thông tư 133 hoặc 99."},"fiscal_year_start":{"type":"string","pattern":"^(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$","example":"01-01","description":"Ngày bắt đầu năm tài chính `MM-DD`."},"timezone":{"type":"string","example":"Asia/Ho_Chi_Minh"},"billing_payer":{"type":"string","enum":["firm","customer"],"description":"Bên trả phí: văn phòng kế toán hoặc khách hàng."},"isolation":{"type":"string","enum":["hard","consolidate"],"description":"`hard`: dữ liệu tách hẳn, văn phòng chỉ vào được khi được chỉ định rõ."},"tax_status":{"type":"string","description":"Tình trạng thuế theo nguồn MST: `active`, `suspended`, `closed` hoặc `unknown`."},"status":{"type":"string","description":"`active`, `suspended`, `frozen` (đang chờ xoá) hoặc `deleted`."},"delete_after":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Thời điểm công ty bị đóng băng sẽ được xoá hẳn.","example":"2026-10-19T01:30:15Z"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"role":{"type":["string","null"],"description":"Vai trò của người gọi tại nút này (người dùng và OAuth); `null` với khoá API."}},"required":["id","kind","parent_id","root_id","name","mst","mst_synced_at","legal_name","address","legal_rep","alert_email","entity_type","display_name","is_accounting_firm","coa_profile","fiscal_year_start","timezone","billing_payer","isolation","tax_status","status","delete_after","created_at","role"],"description":"Một công ty hoặc nút gốc của tổ chức."},"OrgApproval":{"type":"object","properties":{"approval_id":{"$ref":"#/components/schemas/ApprovalRequestId"},"state":{"type":"string","enum":["pending","approved","rejected","withdrawn","expired"]},"company":{"$ref":"#/components/schemas/Org"}},"required":["approval_id","state","company"],"description":"Yêu cầu duyệt xoá công ty và công ty liên quan."},"OrgId":{"type":"string","pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã công ty / tổ chức (`org_…`).","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"OrgList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Org"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"OrgTemplate":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"UUID: mẫu công ty chưa có tiền tố mã công khai."},"name":{"type":"string"},"coa_profile":{"type":"string","description":"Hệ thống tài khoản mà công ty mới bắt đầu với: `TT133` hoặc `TT99`."},"default_role":{"type":"string","description":"Vai trò mặc định khi mời kế toán vào công ty tạo từ mẫu."},"require_2fa_days":{"type":"integer","description":"Số ngày ân hạn trước khi bắt buộc xác thực hai lớp."},"is_default":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","name","coa_profile","default_role","require_2fa_days","is_default","created_at"],"description":"Mẫu công ty của một nút gốc."},"OrgTemplateList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/OrgTemplate"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"Partner":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PartnerId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"kind":{"$ref":"#/components/schemas/PartnerKind"},"name":{"type":"string","minLength":1,"maxLength":200},"legal_name":{"type":["string","null"],"maxLength":200},"mst":{"type":["string","null"],"maxLength":20},"cycle":{"$ref":"#/components/schemas/PartnerCycle"},"payment_terms_days":{"type":"integer","minimum":0,"maximum":365,"default":0},"data_source":{"type":"string","enum":["excel","api_seller","manual"],"default":"excel"},"bank_account_ref":{"type":["string","null"],"maxLength":64},"state":{"$ref":"#/components/schemas/PartnerState"},"internal_note":{"type":["string","null"],"maxLength":500},"created_by":{"anyOf":[{"$ref":"#/components/schemas/UserId"},{"type":"null"}]},"approved_by":{"anyOf":[{"$ref":"#/components/schemas/UserId"},{"type":"null"}]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","org_id","kind","name","cycle","state","created_at","updated_at","payment_terms_days","data_source"],"description":"Đối tác sàn/hãng ký gửi/đại lý/nhóm CTV."},"PartnerCycle":{"type":"object","properties":{"kind":{"type":"string","enum":["daily","weekly","monthly","biweekly"]},"params":{"type":"object","additionalProperties":{}}},"required":["kind"],"description":"Chu kỳ đối soát của đối tác."},"PartnerId":{"type":"string","pattern":"^ptn_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã đối tác sàn/hãng/CTV (`ptn_…`).","example":"ptn_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"PartnerKind":{"type":"string","enum":["marketplace","agent","brand_consignor","ctv_group"],"description":"`marketplace` sàn TMĐT · `agent` đại lý bán lẻ · `brand_consignor` hãng/chủ hàng ký gửi · `ctv_group` nhóm cộng tác viên."},"PartnerList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Partner"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"PartnerMember":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PartnerMemberId"},"partner_id":{"$ref":"#/components/schemas/PartnerId"},"name":{"type":"string","minLength":1,"maxLength":120},"tax_id_masked":{"type":"string","description":"MST hoặc CCCD đã che (vd: •••1234)"},"bank_account_masked":{"type":"string","description":"STK ngân hàng đã che (vd: •••5678)"},"bank_bin":{"type":["string","null"],"maxLength":10},"ctv_code":{"type":["string","null"]},"monthly_income_threshold_flag":{"type":"boolean","default":false,"description":"Cờ cảnh báo thu nhập vượt 2.000.000 ₫/tháng khấu trừ TNCN"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","partner_id","name","tax_id_masked","bank_account_masked","created_at","updated_at","monthly_income_threshold_flag"],"description":"Cá nhân trong nhóm CTV (thông tin PII được mã hoá AES-256-GCM)."},"PartnerMemberId":{"type":"string","pattern":"^pmb_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã thành viên nhóm CTV (`pmb_…`).","example":"pmb_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"PartnerState":{"type":"string","enum":["draft","pending_approval","active","archived"],"description":"`draft` mới tạo · `pending_approval` chờ duyệt · `active` đang hoạt động · `archived` lưu trữ."},"PatchDeviceBank":{"type":"object","properties":{"automation_created":{"type":"boolean"}},"required":["automation_created"],"example":{"automation_created":true}},"PatchDeviceIosAccount":{"type":"object","properties":{"ios_trust_enabled":{"type":"boolean"}},"required":["ios_trust_enabled"],"example":{"ios_trust_enabled":false}},"PatchWebhookEndpointBody":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":["string","null"],"maxLength":255},"events":{"type":"array","items":{"type":"string"},"minItems":1},"egress":{"$ref":"#/components/schemas/WebhookEgress"},"send_full_account":{"type":"boolean"},"memo_pattern_id":{"anyOf":[{"$ref":"#/components/schemas/MemoPatternId"},{"type":"null"}]},"memo_regex":{"type":["string","null"],"maxLength":128}}},"PayQrResponse":{"type":"object","properties":{"invoice_id":{"$ref":"#/components/schemas/BillingInvoiceId"},"memo_code":{"type":"string","description":"Mã nội dung chuyển tiền DTP… chuẩn."},"amount_vnd":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Số tiền cần chuyển chính xác.","example":4500000},"qr_payload":{"type":"string","description":"Chuỗi chuẩn VietQR EMV Co."},"qr_data_url":{"type":"string","description":"Ảnh QR định dạng data:image/png (nếu có)."},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Thời điểm hết hiệu lực thanh toán (15 phút).","example":"2026-10-19T01:30:15Z"},"bank_account":{"$ref":"#/components/schemas/BankAccountRecipient"}},"required":["invoice_id","memo_code","amount_vnd","qr_payload","expires_at","bank_account"],"description":"Thông tin thanh toán VietQR cho hoá đơn."},"PaymentAccountRef":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AccountId"},"label":{"type":"string","example":"ACB •••4521"},"bank":{"type":"string","example":"ACB"},"last4":{"type":"string"},"trust":{"type":"string","enum":["verifiable","provisional_only"],"description":"`provisional_only`: tài khoản chưa có kênh xác thực được (Open API, sao kê, email có chữ ký, SMS có người gửi do hệ điều hành cấp) — tiền về sẽ ở trạng thái tạm tính (D36)."}},"required":["id","label","bank","last4","trust"]},"PaymentRequest":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PaymentRequestId"},"object":{"type":"string","enum":["payment_request"]},"company_id":{"$ref":"#/components/schemas/OrgId"},"memo_code":{"type":"string","pattern":"^DTP[0-9A-HJKMNP-TV-Z]{6}$"},"state":{"$ref":"#/components/schemas/PaymentRequestState"},"amount":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":9007199254740991,"description":"`null`: khách tự nhập số tiền.","example":4500000},"locked_amount":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":9007199254740991,"description":"Số tiền khoá trong QR hiện hành (khác `amount` sau `:resend-remainder`).","example":4500000},"received_verified":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Tổng tiền đã xác thực đã gắn vào yêu cầu."},"received_provisional":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Tổng tiền tạm tính (chưa tính là đã nhận)."},"short_by":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Còn thiếu (chỉ khi `short`/`provisional`)."},"over_by":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Thừa so với `amount` (chỉ khi `over`)."},"allow_partial":{"type":"boolean"},"expires_at":{"$ref":"#/components/schemas/Timestamp"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"opened_at":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Lần đầu khách mở trang thanh toán.","example":"2026-10-19T01:30:15Z"},"paid_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"late_verified":{"type":"boolean","description":"`true`: được xác thực muộn sau khi hết hạn (A2) nhưng vẫn gắn vào yêu cầu."},"overpay_resolved_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"cancelled_reason":{"type":["string","null"]},"account":{"$ref":"#/components/schemas/PaymentAccountRef"},"store":{"anyOf":[{"$ref":"#/components/schemas/StoreRef"},{"type":"null"}]},"counter":{"anyOf":[{"$ref":"#/components/schemas/CounterRef"},{"type":"null"}]},"ref":{"type":["string","null"]},"customer_name":{"type":["string","null"]},"note_internal":{"type":["string","null"]},"source":{"type":"string","pattern":"^(link|pos|api|qr_dynamic|integration:[a-z0-9_]{3,40})$"},"created_by":{"anyOf":[{"$ref":"#/components/schemas/UserId"},{"type":"null"}]},"pay_url":{"type":"string","format":"uri","description":"Trang thanh toán công khai `pay.dongtien.pro/r/{mã}`."},"qr":{"type":"object","properties":{"emv":{"type":"string","description":"Chuỗi VietQR (EMVCo) để vẽ mã QR; số tiền khoá khi `locked_amount` có giá trị."}},"required":["emv"]},"warnings":{"type":"array","items":{"type":"string","enum":["ACCOUNT_PROVISIONAL_ONLY"]}},"version":{"type":"integer","description":"Tăng mỗi lần đổi trạng thái; dùng để phát hiện cập nhật cũ."}},"required":["id","object","company_id","memo_code","state","amount","locked_amount","received_verified","received_provisional","short_by","over_by","allow_partial","expires_at","created_at","opened_at","paid_at","late_verified","overpay_resolved_at","cancelled_reason","account","store","counter","ref","customer_name","note_internal","source","created_by","pay_url","qr","warnings","version"],"description":"Yêu cầu thanh toán VietQR. Không giữ tiền: tiền đi thẳng tới tài khoản của công ty. `paid` chỉ khi tổng giao dịch **đã xác thực** đủ số tiền."},"PaymentRequestEvent":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["created","opened","provisional","verified","short","over","reminded","receipt","expired","cancelled","overpay_resolved","reconciled","remainder_sent","updated","tx_attached","tx_detached"]},"at":{"$ref":"#/components/schemas/Timestamp"},"actor":{"type":["string","null"],"description":"`user:usr_…`, `key:apk_…` hoặc `system:recon`."},"from_state":{"anyOf":[{"$ref":"#/components/schemas/PaymentRequestState"},{"type":"null"}]},"to_state":{"anyOf":[{"$ref":"#/components/schemas/PaymentRequestState"},{"type":"null"}]},"detail":{"type":"object","additionalProperties":{}}},"required":["id","kind","at","actor","from_state","to_state","detail"]},"PaymentRequestEventList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRequestEvent"}}},"required":["object","data"]},"PaymentRequestId":{"type":"string","pattern":"^pr_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã yêu cầu thanh toán (`pr_…`).","example":"pr_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"PaymentRequestList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRequest"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"PaymentRequestNotify":{"type":"object","properties":{"recipient":{"oneOf":[{"type":"object","properties":{"channel":{"type":"string","enum":["email"]},"address":{"type":"string","maxLength":320,"format":"email"}},"required":["channel","address"]},{"type":"object","properties":{"channel":{"type":"string","enum":["zalo"]},"address":{"type":"string","minLength":1,"maxLength":128}},"required":["channel","address"]}]}},"required":["recipient"],"example":{"recipient":{"channel":"email","address":"ketoan@cuahangminhanh.vn"}}},"PaymentRequestRef":{"type":"string","pattern":"^(pr_[0-9a-hjkmnp-tv-z]{26}|[Dd][Tt][Pp][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{6})$","description":"Mã yêu cầu `pr_…` hoặc mã nội dung `DTP…`.","example":"pr_0f5k2m9q4h7t3n8r6v1w0x5yzd"},"PaymentRequestState":{"type":"string","enum":["waiting","provisional","short","paid","over","expired","cancelled"],"description":"`waiting` chờ tiền · `provisional` đã thấy tiền nhưng chưa xác thực · `short` mới nhận một phần đã xác thực · `paid` đủ · `over` thừa · `expired` hết hạn · `cancelled` đã huỷ."},"PaymentRequestTransaction":{"type":"object","properties":{"transaction_id":{"$ref":"#/components/schemas/TxId"},"amount":{"$ref":"#/components/schemas/PositiveVnd"},"amount_applied":{"$ref":"#/components/schemas/PositiveVnd"},"occurred_at":{"$ref":"#/components/schemas/Timestamp"},"verification_level":{"type":"string","enum":["provisional","verified"]},"verified_by":{"type":["string","null"],"enum":["openapi","statement","trusted_sender","email_dkim","manual","import",null]},"trust_basis":{"type":"string","enum":["trusted_sender","sender_verified_ios","email_dkim_direct","email_dkim_forwarded","none"]},"channel":{"type":"string","enum":["android","ios","email","openapi","statement","import"]},"payer_masked":{"type":["string","null"],"description":"Tên người chuyển đã rút gọn (`NGUYEN T*** NHUNG`)."},"last4":{"type":"string","description":"4 số cuối tài khoản nhận."},"linked_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["transaction_id","amount","amount_applied","occurred_at","verification_level","verified_by","trust_basis","channel","payer_masked","last4","linked_at"]},"PaymentRequestTransactionList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRequestTransaction"}}},"required":["object","data"]},"Payout":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PayoutId"},"platform":{"$ref":"#/components/schemas/SettlementPlatform"},"shop_id":{"type":"string","minLength":1,"maxLength":64},"period":{"type":"string","description":"Kỳ quyết toán (vd: 2026-10-A, 2026-W42)"},"statement_ref":{"type":"string","minLength":1,"maxLength":120},"statement_amount":{"$ref":"#/components/schemas/Vnd"},"state":{"$ref":"#/components/schemas/PayoutState"},"source":{"$ref":"#/components/schemas/PayoutSource"},"bank_tx_id":{"anyOf":[{"$ref":"#/components/schemas/TxId"},{"type":"null"}]},"diff":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"default":0,"description":"Chênh lệch: số tiền thực nhận tại bank - số tiền trên sao kê","example":4500000},"confidence":{"type":"integer","minimum":0,"maximum":100},"ai_cause":{"type":["object","null"],"additionalProperties":{}},"obligation_id":{"anyOf":[{"$ref":"#/components/schemas/ObligationId"},{"type":"null"}]},"lines_count":{"type":"integer","minimum":0},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","platform","shop_id","period","statement_ref","statement_amount","state","source","created_at","updated_at","diff"],"description":"Đợt quyết toán / statement đối soát từ sàn."},"PayoutId":{"type":"string","pattern":"^pay_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã đợt quyết toán sàn (`pay_…`).","example":"pay_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"PayoutLine":{"type":"object","properties":{"id":{"type":"string"},"payout_id":{"$ref":"#/components/schemas/PayoutId"},"kind":{"$ref":"#/components/schemas/PayoutLineKind"},"amount":{"$ref":"#/components/schemas/Vnd"},"order_no":{"type":["string","null"]}},"required":["id","payout_id","kind","amount"],"description":"Dòng chi tiết bóc tách trong đợt sao kê sàn."},"PayoutLineKind":{"type":"string","enum":["revenue","fee","voucher","refund","net"],"description":"`revenue` doanh thu · `fee` phí sàn · `voucher` trợ giá voucher · `refund` hoàn hàng · `net` thực nhận."},"PayoutList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Payout"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"PayoutSource":{"type":"string","enum":["upload","api_seller","manual"],"description":"`upload` tải tệp Excel · `api_seller` đồng bộ API Seller · `manual` nhập tay."},"PayoutState":{"type":"string","enum":["matched","variance","awaiting_payout","provisional","orphan_credit"],"description":"`matched` khớp tuyệt đối · `variance` lệch N đ · `awaiting_payout` chờ tiền về · `provisional` tạm tính (chỉ SMS/email) · `orphan_credit` thừa/thiếu statement."},"PeriodState":{"type":"string","enum":["open","lock_requested","locked","unlock_requested"],"description":"Trạng thái kỳ kế toán: open (mở), lock_requested (chờ duyệt khoá), locked (đã khoá), unlock_requested (chờ duyệt mở khoá)."},"PingDevice":{"type":"object","properties":{"kind":{"type":"string","enum":["ping","diagnose","test_send"],"default":"ping"}}},"PlanLimits":{"type":"object","additionalProperties":{"anyOf":[{"type":"number"},{"type":"boolean"}]},"description":"Hạn mức và quyền năng của gói."},"PlanTier":{"type":"object","properties":{"up_to":{"type":["integer","null"],"exclusiveMinimum":0,"description":"Hạn mức tối đa của bậc (null = không giới hạn).","example":1000},"unit_vnd":{"type":"integer","minimum":0,"description":"Đơn giá mỗi giao dịch trong bậc (VND).","example":20}},"required":["up_to","unit_vnd"],"description":"Bậc giá luỹ tiến theo số giao dịch."},"PlatformConnection":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PlatformConnectionId"},"partner_id":{"$ref":"#/components/schemas/PartnerId"},"platform":{"$ref":"#/components/schemas/SettlementPlatform"},"shop_id":{"type":"string","minLength":1,"maxLength":64},"shop_name":{"type":["string","null"],"maxLength":120},"mode":{"$ref":"#/components/schemas/PlatformConnectionMode"},"token_expires_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"last_sync_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"sync_status":{"type":"string","enum":["ok","error","reauth_required"],"default":"ok"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","partner_id","platform","shop_id","mode","created_at","updated_at","sync_status"],"description":"Kết nối gian hàng Shopee/TikTok/Lazada."},"PlatformConnectionId":{"type":"string","pattern":"^plc_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã kết nối gian hàng (`plc_…`).","example":"plc_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"PlatformConnectionMode":{"type":"string","enum":["excel","api_seller","manual"],"description":"`excel` nhập tệp sao kê · `api_seller` đồng bộ API · `manual` nhập tay."},"PositiveVnd":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Số tiền VND dương, số nguyên đồng.","example":4500000},"PreviewStatementForm":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Tệp sao kê, tối đa 25 MB: `.xlsx`, `.xls`, `.csv`, `.sta`/`.mt940`, `.xml` (CAMT.053)."},"bank_account_id":{"type":"string","pattern":"^acc_[0-9a-hjkmnp-tv-z]{26}$","description":"Tài khoản ngân hàng nhận sao kê.","example":"acc_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"format":{"type":"string","enum":["xlsx","xls","csv","mt940","camt053"],"description":"Bỏ trống để tự nhận dạng; nếu gửi phải khớp nội dung tệp."},"mapping_id":{"type":"string","pattern":"^smp_[0-9a-hjkmnp-tv-z]{26}$","description":"Dùng mẫu ánh xạ đã lưu thay cho tự nhận dạng.","example":"smp_0f5k2m9q4h7t3n8r6v1w0x5yz0"}},"required":["file","bank_account_id"]},"Problem":{"type":"object","properties":{"type":{"type":"string","example":"https://docs.dongtien.pro/errors/validation_failed"},"title":{"type":"string","example":"Request validation failed"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string","description":"Giải thích riêng cho lần lỗi này (không lộ nội bộ)."},"code":{"$ref":"#/components/schemas/ErrorCode"},"request_id":{"type":"string","example":"req_0f5k2m9q4h7t3n8r6v1w0x5yzd"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/FieldError"}},"retryable":{"type":"boolean","description":"`true` nếu gửi lại cùng yêu cầu có thể thành công."},"retry_after":{"type":"integer","minimum":0,"description":"Số giây nên chờ (khớp header `Retry-After`)."}},"required":["type","title","status","code","request_id","retryable"],"description":"Lỗi theo RFC 9457 (`application/problem+json`). `code` ổn định; `type` trỏ tới trang tài liệu của mã."},"ProposeAccessGrant":{"type":"object","properties":{"grantor_org_id":{"type":"string","pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Công ty (hoặc nút gốc) của khách được cấp quyền. Bên cấp đề xuất: người gọi phải có phạm vi trùm nó; bên nhận đề xuất: người gọi thuộc `grantee_root_id`.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"grantee_root_id":{"type":"string","pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Nút gốc của văn phòng kế toán nhận quyền.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"role_key":{"$ref":"#/components/schemas/AccessGrantRole"},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Thời điểm hết hạn, phải ở tương lai; bỏ trống = không hết hạn.","example":"2026-10-19T01:30:15Z"}},"required":["grantor_org_id","grantee_root_id","role_key"]},"ProposeMappingRulesBody":{"type":"object","properties":{"profile_id":{"type":"string","format":"uuid","description":"Mặc định: hồ sơ hệ thống tài khoản đang dùng của công ty."},"rules":{"type":"array","items":{"$ref":"#/components/schemas/MappingRuleDraft"},"minItems":1,"maxItems":50},"note":{"type":"string","maxLength":500,"description":"Ghi chú cho người duyệt."}},"required":["rules"],"example":{"rules":[{"name":"Thu tiền khách hàng qua ngân hàng","conditions":{"direction":"in"},"voucher_type":"BC","debit_account":"1121","credit_account":"131","priority":90}],"note":"Quy tắc cho tài khoản VCB chính."}},"PublicPlanItem":{"type":"object","properties":{"key":{"type":"string","enum":["free","per_tx","enterprise","trial","internal"]},"name":{"type":"string"},"description":{"type":["string","null"]},"is_illustrative":{"type":"boolean"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/PlanTier"}},"limits":{"$ref":"#/components/schemas/PlanLimits"}},"required":["key","name","description","is_illustrative","tiers","limits"],"description":"Thông tin gói công khai."},"PublicPlansResponse":{"type":"object","properties":{"plans":{"type":"array","items":{"$ref":"#/components/schemas/PublicPlanItem"}},"illustrative":{"type":"boolean","description":"Cờ minh hoạ toàn hệ thống."},"vat_percent":{"type":"integer","minimum":0,"description":"Tỷ lệ VAT cấu hình."}},"required":["plans","illustrative","vat_percent"],"description":"Danh sách các gói cước công khai."},"PutBankAccountGlMapBody":{"type":"object","properties":{"gl_code":{"type":"string","minLength":3,"description":"Số hiệu tài khoản kế toán (TT200/TT133), ví dụ `1121`.","example":"1121"},"code_misa":{"type":"string","maxLength":50},"code_fast":{"type":"string","maxLength":50},"effective_from":{"$ref":"#/components/schemas/Date"}},"required":["gl_code","effective_from"]},"PutCounterpartyCodeBody":{"type":"object","properties":{"counterparty_id":{"$ref":"#/components/schemas/CounterpartyId"},"target":{"$ref":"#/components/schemas/CounterpartyCodeTarget"},"code":{"type":"string","minLength":1,"maxLength":50,"description":"ASCII hoa, số, `_` hoặc `-`; không dài hơn giới hạn của đích."}},"required":["counterparty_id","target","code"],"example":{"counterparty_id":"cpt_0f5k2m9q4h7t3n8r6v1w0x5yz0","target":"misa_amis","code":"KH_VINHPHAT"}},"PutDeviceAlertRules":{"type":"object","properties":{"company_id":{"$ref":"#/components/schemas/OrgId"},"no_heartbeat_min":{"type":"integer","minimum":5,"maximum":240,"description":"Không heartbeat quá N phút ⇒ `stale`; gấp đôi ⇒ `offline` (mặc định 15 / 30)."},"battery_lt":{"type":"integer","minimum":1,"maximum":99,"description":"Pin dưới N % (mặc định 20)."},"queue_gt":{"type":"integer","minimum":1,"maximum":5000,"description":"Hàng đợi quá N tin (mặc định 10)."},"queue_age_min":{"type":"integer","minimum":1,"maximum":1440,"description":"…kéo dài quá N phút mới cảnh báo (mặc định 30)."},"ios_silent_hours":{"type":"integer","minimum":1,"maximum":168,"description":"iOS: không có SMS hợp lệ quá N giờ ⇒ `silent` (mặc định 36)."},"channels":{"type":"array","items":{"type":"string","enum":["zalo","push","email"]},"minItems":1,"maxItems":3},"enabled":{"type":"object","properties":{"no_heartbeat":{"type":"boolean"},"battery":{"type":"boolean"},"queue":{"type":"boolean"},"ios_silent":{"type":"boolean"}},"required":["no_heartbeat","battery","queue","ios_silent"]}},"required":["company_id","no_heartbeat_min","battery_lt","queue_gt","queue_age_min","ios_silent_hours","channels","enabled"],"example":{"company_id":"org_01hz8x9k3m4n5p6q7r8s9t0v1w","no_heartbeat_min":15,"battery_lt":20,"queue_gt":10,"queue_age_min":30,"ios_silent_hours":36,"channels":["zalo","push"],"enabled":{"no_heartbeat":true,"battery":true,"queue":true,"ios_silent":true}}},"PutMisaConnectionBody":{"type":"object","properties":{"access_code":{"type":"string","minLength":8,"maxLength":128},"branch_id":{"type":"string"}},"required":["access_code"]},"PutStatementMapping":{"type":"object","properties":{"company_id":{"type":"string","pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Công ty sở hữu mẫu.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"bank_code":{"type":"string","minLength":1,"maxLength":16,"example":"ACB"},"header_fingerprint":{"type":"string","pattern":"^[0-9a-f]{64}$","example":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"},"mapping":{"$ref":"#/components/schemas/StatementColumnMapping"},"template_name":{"type":"string","minLength":1,"maxLength":80}},"required":["company_id","bank_code","header_fingerprint","mapping"]},"QuarantineDecision":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500},"evidence":{"type":"string","minLength":3,"maxLength":2000,"description":"Bằng chứng người duyệt đã đối chiếu (ví dụ: sao kê, cuộc gọi ngân hàng). Ghi nhật ký kiểm toán."}},"required":["reason","evidence"],"example":{"reason":"Đã gọi ngân hàng xác nhận","evidence":"Mã tham chiếu FT26292xxxxx khớp sao kê"}},"RealtimeTicket":{"type":"object","properties":{"object":{"type":"string","enum":["realtime_ticket"]},"ticket":{"type":"string","pattern":"^rtk_[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$"},"expires_at":{"$ref":"#/components/schemas/Timestamp"},"topics":{"type":"array","items":{"$ref":"#/components/schemas/RealtimeTopic"}},"ws_url":{"type":"string","description":"Đường dẫn WebSocket đã gắn vé."},"sse_url":{"type":"string","description":"Đường dẫn SSE đã gắn vé."}},"required":["object","ticket","expires_at","topics","ws_url","sse_url"],"description":"Vé dùng một lần, hiệu lực 60 giây, gắn với phạm vi công ty/tài khoản của người gọi."},"RealtimeTicketRequest":{"type":"object","properties":{"company_id":{"type":"string","pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Chỉ nghe một công ty; bỏ trống = mọi công ty người gọi xem được.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"topics":{"type":"array","items":{"$ref":"#/components/schemas/RealtimeTopic"},"maxItems":20,"description":"Kênh muốn nghe. Mặc định `org:<company>` cho từng công ty trong phạm vi; `user:<mình>` được phép."},"purpose":{"type":"string","enum":["app","cli_listen"],"default":"app","description":"`cli_listen`: vé của `dtp listen` (luồng sự kiện webhook của tổ chức gốc); chỉ khoá API hoặc OAuth, `topics` bị bỏ qua."},"live":{"type":"boolean","description":"Chỉ với `cli_listen`: nghe sự kiện thật (cần scope `webhooks:write`, ghi nhật ký `cli.listen_live`); mặc định chỉ sự kiện sandbox."}}},"RealtimeTopic":{"type":"string","pattern":"^(org|user|counter|listen):[a-z0-9_]+$","example":"org:org_0f5k2m9q4h7t3n8r6v1w0x5yzd"},"ReconFollowupId":{"type":"string","pattern":"^rfu_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã việc cần xử lý đối soát (`rfu_…`).","example":"rfu_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"ReconFollowupList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ReconFollowupId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"kind":{"type":"string","enum":["late_payment","overpay_refund","invoice_overdue","partial_collect","customer_advance","other"]},"target_type":{"type":"string","enum":["invoice","order","expected_payment","transaction"]},"target_id":{"type":["string","null"]},"tx_id":{"anyOf":[{"$ref":"#/components/schemas/TxId"},{"type":"null"}]},"allocation_id":{"anyOf":[{"$ref":"#/components/schemas/AllocationId"},{"type":"null"}]},"title":{"type":"string"},"amount":{"anyOf":[{"$ref":"#/components/schemas/Vnd"},{"type":"null"}]},"due_date":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"status":{"type":"string","enum":["open","resolved","dismissed"]},"notes":{"type":["string","null"]},"created_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","org_id","kind","target_type","title","status","created_at"]}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"ReconQueueList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"allocation":{"$ref":"#/components/schemas/Allocation"},"tx":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/TxId"},"amount":{"$ref":"#/components/schemas/Vnd"},"direction":{"type":"string","enum":["in","out"]},"description":{"type":"string"},"occurred_at":{"$ref":"#/components/schemas/Timestamp"},"bank_account_id":{"type":"string"},"bank_code":{"type":"string"},"account_number_mask":{"type":"string"},"status":{"type":"string"}},"required":["id","amount","direction","description","occurred_at","status"]},"policy_checks":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"status":{"type":"string","enum":["pass","warn","fail"]},"detail":{"type":"string"}},"required":["key","label","status"]}},"maker_name":{"type":"string"},"can_approve":{"type":"boolean"},"lock_reason":{"type":"string"}},"required":["allocation","tx","policy_checks","can_approve"]}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"RejectExportBatchBody":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500,"example":"Sai tài khoản đối ứng ở chứng từ BC-0012"}},"required":["reason"]},"RejectRequestBody":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500,"example":"Sai tài khoản kế toán, vui lòng kiểm tra lại."}},"required":["reason"]},"ReplayDeliveryResponse":{"type":"object","properties":{"delivery_id":{"$ref":"#/components/schemas/WebhookDeliveryId"},"replayed":{"type":"boolean"}},"required":["delivery_id","replayed"]},"ReplayFailedDeliveriesBody":{"type":"object","properties":{"group":{"type":"string","enum":["blocked","waiting","ready"]},"endpoint_id":{"$ref":"#/components/schemas/WebhookEndpointId"},"dry_run":{"type":"boolean","default":false}}},"ReplayFailedDeliveriesResponse":{"type":"object","properties":{"blocked_count":{"type":"integer"},"waiting_count":{"type":"integer"},"ready_count":{"type":"integer"},"replayed_count":{"type":"integer"}},"required":["blocked_count","waiting_count","ready_count","replayed_count"]},"RerunStatement":{"type":"object","properties":{"mapping_id":{"type":"string","pattern":"^smp_[0-9a-hjkmnp-tv-z]{26}$","description":"Dùng mẫu ánh xạ đã lưu.","example":"smp_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"mapping":{"type":"object","properties":{"layout_id":{"type":"string","maxLength":64,"description":"Mã bố cục đã nhận dạng (ví dụ `acb`)."},"header_row":{"type":"integer","minimum":0,"maximum":1000,"description":"Dòng tiêu đề (đếm từ 0)."},"header_rows":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}],"description":"Số dòng tiêu đề (mặc định 1)."},"columns":{"type":"object","properties":{"date":{"type":"integer","minimum":0,"maximum":1023},"time":{"type":"integer","minimum":0,"maximum":1023},"value_date":{"type":"integer","minimum":0,"maximum":1023},"debit":{"type":"integer","minimum":0,"maximum":1023},"credit":{"type":"integer","minimum":0,"maximum":1023},"amount":{"type":"integer","minimum":0,"maximum":1023},"dc_flag":{"type":"integer","minimum":0,"maximum":1023},"balance":{"type":"integer","minimum":0,"maximum":1023},"description":{"type":"integer","minimum":0,"maximum":1023},"ref":{"type":"integer","minimum":0,"maximum":1023},"counterparty_name":{"type":"integer","minimum":0,"maximum":1023},"counterparty_account":{"type":"integer","minimum":0,"maximum":1023},"currency":{"type":"integer","minimum":0,"maximum":1023}},"description":"Chỉ số cột (đếm từ 0) của từng trường; trường nào không có cột thì bỏ qua."}},"required":["header_row","columns"],"description":"Ánh xạ nhập tay cho lần chạy này.","example":{"layout_id":"acb","header_row":8,"columns":{"date":0,"debit":3,"credit":4,"balance":5,"description":2}}},"save_template":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"Tên mẫu (ví dụ `ACB doanh nghiệp`)."}},"required":["name"],"description":"Lưu ánh xạ làm mẫu cho tệp cùng bố cục lần sau (\"Lưu ánh xạ & chạy lại\")."}}},"ResendInvitation":{"type":"object","properties":{"expires_in_days":{"anyOf":[{"type":"number","enum":[3]},{"type":"number","enum":[7]},{"type":"number","enum":[14]}],"default":7}}},"ResolveOverpay":{"type":"object","properties":{"note":{"type":"string","minLength":1,"maxLength":500}},"example":{"note":"Đã báo khách, đối trừ vào đơn hàng sau"}},"ResyncOrgResult":{"type":"object","properties":{"company":{"$ref":"#/components/schemas/Org"},"mst_source":{"$ref":"#/components/schemas/MstSource"},"updated":{"type":"boolean","description":"`true`: hồ sơ pháp lý đã được ghi lại từ nguồn MST."},"warnings":{"type":"array","items":{"type":"string"}}},"required":["company","mst_source","updated","warnings"]},"RevealedAccountNumber":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AccountId"},"object":{"type":"string","enum":["bank_account_secret"]},"account_number":{"type":"string","pattern":"^\\d{6,20}$"},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Thời điểm hết hạn hiển thị (5 phút sau khi cấp).","example":"2026-10-19T01:30:15Z"}},"required":["id","object","account_number","expires_at"],"description":"Số tài khoản đầy đủ, chỉ trả qua `:reveal`. Không lưu cache, không phát lại."},"RevokeApiKey":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}},"example":{"reason":"Khoá bị lộ trong kho mã nguồn."}},"RevokeOtherSessionsResult":{"type":"object","properties":{"revoked":{"type":"integer","minimum":0}},"required":["revoked"]},"Role":{"type":"object","properties":{"key":{"type":"string","enum":["owner","admin","accountant_chief","accountant","developer","viewer","auditor"]},"name":{"type":"string","description":"Tên tiếng Việt của vai trò."},"permissions":{"type":"object","additionalProperties":{"type":"string","enum":["allow","self","stepup"]},"description":"Quyền → `allow` | `self` (chỉ bản ghi của chính mình) | `stepup` (cần xác thực lại gần đây)."}},"required":["key","name","permissions"],"description":"Vai trò hệ thống và các quyền của nó."},"RoleList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Role"}},"step_up_permissions":{"type":"array","items":{"type":"string"},"description":"Các quyền luôn cần xác thực lại gần đây, bất kể vai trò."},"next_cursor":{"type":"null"},"has_more":{"type":"boolean","enum":[false]}},"required":["object","data","step_up_permissions","next_cursor","has_more"]},"RotateApiKey":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"expires_at":{"type":"string","format":"date-time"}},"example":{"name":"Đồng bộ kế toán (xoay quý 3)","expires_at":"2030-06-30T00:00:00+07:00"}},"RotatedApiKey":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/ApiKeyIssued"},"old_key":{"$ref":"#/components/schemas/ApiKey"}},"required":["key","old_key"],"description":"`key`: khoá thay thế (bí mật hiện một lần). `old_key`: khoá cũ, vẫn dùng được trong thời gian ân hạn."},"SaveOnboardingDraft":{"type":"object","properties":{"step":{"type":"string","enum":["b1","b2","done"]},"data":{"type":"object","additionalProperties":{},"description":"Không đặt mật khẩu hay token ở đây; tối đa 64 KB."}},"required":["step","data"],"example":{"step":"b2","data":{"mst":"0100109106","display_name":"CONG TY ABC"}}},"SavedView":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/SavedViewId"},"object":{"type":"string","enum":["saved_view"]},"name":{"type":"string","minLength":1,"maxLength":80},"visibility":{"$ref":"#/components/schemas/SavedViewVisibility"},"company_id":{"type":["string","null"],"pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Công ty của chế độ xem `company`; `null` với `me`/`firm`.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"owner_id":{"$ref":"#/components/schemas/UserId"},"mine":{"type":"boolean","description":"Người gọi là chủ của chế độ xem này."},"filters":{"$ref":"#/components/schemas/SavedViewFilters"},"show_count_on_card":{"type":"boolean"},"show_in_dashboard_todo":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","object","name","visibility","company_id","owner_id","mine","filters","show_count_on_card","show_in_dashboard_todo","created_at","updated_at"],"description":"Chế độ xem giao dịch đã lưu."},"SavedViewFilters":{"type":"object","additionalProperties":{},"description":"Bộ lọc của danh sách giao dịch (cùng tên tham số của `GET /v1/transactions`: `preset`, `status`, `direction`, `account_id`, `since`, `until`, `memo`, `q`, …). Máy chủ không diễn giải, giao diện áp dụng."},"SavedViewId":{"type":"string","pattern":"^svw_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã chế độ xem đã lưu (`svw_…`).","example":"svw_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"SavedViewList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SavedView"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"SavedViewVisibility":{"type":"string","enum":["me","company","firm"],"description":"`me`: chỉ mình tôi. `company`: cả công ty (cần `company_id`). `firm`: cả tổ chức (cần quyền quản trị tổ chức)."},"SecurityPolicy":{"type":"object","properties":{"require_2fa":{"type":"boolean"},"require_2fa_grace_days":{"type":"integer","minimum":0,"maximum":30},"session_max_hours":{"type":"integer","minimum":1,"maximum":720},"admin_ip_allowlist":{"type":"array","items":{"type":"string"},"description":"Dải CIDR được phép thao tác quản trị; rỗng = mọi nơi."},"new_location_alert":{"type":"boolean"},"self_approval":{"type":"object","properties":{"enabled":{"type":"boolean"},"threshold_vnd":{"type":"integer","exclusiveMinimum":0,"description":"Hạn mức tự duyệt, VND (số nguyên)."}},"required":["enabled","threshold_vnd"]}},"required":["require_2fa","require_2fa_grace_days","session_max_hours","admin_ip_allowlist","new_location_alert","self_approval"],"description":"Chính sách bảo mật của tổ chức."},"SecurityPolicyPatch":{"type":"object","properties":{"require_2fa":{"type":"boolean"},"require_2fa_grace_days":{"type":"integer","minimum":0,"maximum":30},"session_max_hours":{"type":"integer","minimum":1,"maximum":720},"admin_ip_allowlist":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":50},"new_location_alert":{"type":"boolean"},"self_approval":{"type":"object","properties":{"enabled":{"type":"boolean"},"threshold_vnd":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}}},"additionalProperties":false,"description":"Các trường cần đổi; trường bỏ trống giữ nguyên giá trị.","example":{"require_2fa":true,"require_2fa_grace_days":7,"session_max_hours":8}},"SendResult":{"type":"object","properties":{"class":{"$ref":"#/components/schemas/SendResultClass"},"delivery_id":{"$ref":"#/components/schemas/IntegrationDeliveryId"},"http_status":{"type":"integer"},"latency_ms":{"type":"integer","minimum":0},"retry_after_ms":{"type":"integer","minimum":0},"error":{"type":"string"}},"required":["class"],"description":"Kết quả gửi thông báo ra kênh ngoài."},"SendResultClass":{"type":"string","enum":["delivered","retry","rate_limited","fatal"],"description":"Phân loại kết quả gửi của adapter."},"ServiceCreditBalanceResponse":{"type":"object","properties":{"balance_vnd":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Số dư credit dịch vụ hiện có (không phải ví tiền, không rút được).","example":4500000},"entries":{"type":"array","items":{"$ref":"#/components/schemas/ServiceCreditEntry"}}},"required":["balance_vnd","entries"],"description":"Số dư và lịch sử biến động credit dịch vụ."},"ServiceCreditEntry":{"type":"object","properties":{"id":{"type":"string","description":"Mã dòng sổ cái credit."},"kind":{"type":"string","enum":["topup","invoice_deduct","overpay_credit","adjustment_credit","adjustment_debit","refund"]},"amount_vnd":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Biến động VND (dương = cộng, âm = trừ).","example":4500000},"balance_after_vnd":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Số dư sau biến động (luôn >= 0).","example":4500000},"reference_id":{"type":["string","null"],"description":"Mã tham chiếu (hoá đơn, topup, v.v.)."},"description":{"type":"string"},"created_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","kind","amount_vnd","balance_after_vnd","reference_id","description","created_at"],"description":"Dòng sổ cái credit dịch vụ."},"Session":{"type":"object","properties":{"id":{"type":"string"},"current":{"type":"boolean","description":"Phiên đang gửi yêu cầu này."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"last_seen_at":{"$ref":"#/components/schemas/Timestamp"},"ip":{"type":["string","null"]},"user_agent":{"type":["string","null"]},"mfa_at":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Lần qua bước xác thực hai yếu tố của phiên.","example":"2026-10-19T01:30:15Z"},"step_up_at":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Lần xác thực lại gần nhất (step-up).","example":"2026-10-19T01:30:15Z"}},"required":["id","current","created_at","last_seen_at","ip","user_agent","mfa_at","step_up_at"],"description":"Một phiên đăng nhập của người dùng."},"SessionList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Session"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"SettlementImport":{"type":"object","properties":{"job_id":{"$ref":"#/components/schemas/StatementImportId"},"state":{"type":"string","description":"`created` · `validating` · `preview_ready` · `committing` · `completed` · `completed_with_errors` · `failed` · `cancelled`."},"preview":{"type":["object","null"],"properties":{"platform":{"$ref":"#/components/schemas/SettlementPlatform"},"shop_id":{"type":"string"},"statement_ref":{"type":"string"},"period":{"type":"string"},"orders_count":{"type":"integer","minimum":0},"invalid_orders":{"type":"integer","minimum":0},"statement_amount":{"$ref":"#/components/schemas/Vnd"},"revenue":{"$ref":"#/components/schemas/Vnd"},"platform_fee":{"$ref":"#/components/schemas/Vnd"},"voucher_seller":{"$ref":"#/components/schemas/Vnd"},"bank_match":{"type":"object","properties":{"state":{"type":"string"},"level":{"type":["string","null"]},"confidence":{"type":["number","null"]}},"required":["state","level","confidence"]}},"required":["platform","shop_id","statement_ref","period","orders_count","invalid_orders","statement_amount","revenue","platform_fee","voucher_seller","bank_match"]},"error_code":{"type":["string","null"]}},"required":["job_id","state","preview","error_code"],"description":"Tác vụ nhập sao kê sàn và bản xem trước do workflow tạo."},"SettlementPlatform":{"type":"string","enum":["shopee","tiktok","lazada"],"description":"Sàn thương mại điện tử: `shopee` · `tiktok` · `lazada`."},"SettlementReportId":{"type":"string","pattern":"^srp_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã bản báo cáo đối soát (`srp_…`).","example":"srp_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"SettlementReportKind":{"type":"string","enum":["receivable_payable_aging","payout_reconciliation","partner_statement","platform_fee_actual"],"description":"Loại báo cáo đối soát: `receivable_payable_aging` tuổi nợ · `payout_reconciliation` đối soát sao kê sàn · `partner_statement` bảng kê đối tác/hãng · `platform_fee_actual` phí sàn thực trả vs biểu phí."},"SettlementReportSchedule":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/SettlementReportScheduleId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"kind":{"$ref":"#/components/schemas/SettlementReportKind"},"cron":{"type":"string"},"partner_id":{"anyOf":[{"$ref":"#/components/schemas/PartnerId"},{"type":"null"}]},"recipients":{"type":"array","items":{"type":"string","format":"email"}},"channel":{"type":"string","enum":["email","in_app"],"default":"email"},"enabled":{"type":"boolean","default":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","org_id","kind","cron","recipients","created_at","updated_at","channel","enabled"],"description":"Lịch tự động sinh và gửi báo cáo đối soát."},"SettlementReportScheduleId":{"type":"string","pattern":"^srs_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã lịch báo cáo đối soát (`srs_…`).","example":"srs_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"SettlementSettings":{"type":"object","properties":{"allowable_drift_vnd":{"type":"integer","minimum":0,"maximum":1000000,"description":"Chênh lệch tối đa (VND) giữa sao kê và tiền về mà vẫn được khớp ở mức L3 (phí liên ngân hàng, làm tròn)."},"variance_alert_threshold_vnd":{"type":"integer","minimum":0,"description":"Chênh lệch tuyệt đối vượt ngưỡng này thì phát sự kiện `settlement.payout_variance` (0 = mọi chênh lệch)."}},"required":["allowable_drift_vnd","variance_alert_threshold_vnd"],"description":"Ngưỡng đối soát payout của công ty."},"SettlementSummary":{"type":"object","properties":{"receivable_total":{"$ref":"#/components/schemas/Vnd"},"receivable_platforms":{"$ref":"#/components/schemas/Vnd"},"receivable_agents":{"$ref":"#/components/schemas/Vnd"},"payable_total":{"$ref":"#/components/schemas/Vnd"},"payable_brands":{"$ref":"#/components/schemas/Vnd"},"payable_ctv":{"$ref":"#/components/schemas/Vnd"},"nearest_payable_due":{"anyOf":[{"$ref":"#/components/schemas/Date"},{"type":"null"}]},"net_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Phải thu trừ phải trả (còn lại chưa gạch).","example":4500000},"payout_matched_count":{"type":"integer","minimum":0},"payout_total_count":{"type":"integer","minimum":0},"payout_variance_total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Tổng chênh lệch (đối soát − sao kê) của các đợt payout còn lệch.","example":4500000},"payout_variance_count":{"type":"integer","minimum":0}},"required":["receivable_total","receivable_platforms","receivable_agents","payable_total","payable_brands","payable_ctv","nearest_payable_due","net_amount","payout_matched_count","payout_total_count","payout_variance_total","payout_variance_count"],"description":"Tổng quan đối soát: phải thu, phải trả, đợt payout đã khớp và chênh lệch."},"SftpConfig":{"type":"object","properties":{"host":{"type":"string","minLength":1,"maxLength":253},"port":{"type":"integer","minimum":1,"maximum":65535,"default":22},"path":{"type":"string","minLength":1,"maxLength":255,"description":"Thư mục hoặc mẫu tên tệp trên máy chủ SFTP, ví dụ `/out/camt053/*.xml`."},"username":{"type":"string","minLength":1,"maxLength":128},"host_key_sha256":{"type":["string","null"],"pattern":"^SHA256:[A-Za-z0-9+/]{43}$","description":"Khoá máy chủ đã ghim. `null` ở lịch tạo trước khi có ghim khoá: cổng ngân hàng không chạy lịch đó cho tới khi bạn nhập dấu vân tay."}},"required":["host","path","username","host_key_sha256","port"],"description":"Nơi lấy tệp trên máy chủ SFTP của ngân hàng."},"ShiftId":{"type":"string","pattern":"^shf_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã ca thu ngân (`shf_…`).","example":"shf_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"SkuBrandMap":{"type":"object","properties":{"id":{"type":"string"},"sku":{"type":"string","minLength":1,"maxLength":100},"brand":{"type":"string","minLength":1,"maxLength":100},"partner_id":{"anyOf":[{"$ref":"#/components/schemas/PartnerId"},{"type":"null"}]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","sku","brand","created_at","updated_at"],"description":"Ánh xạ SKU sàn sang nhãn hàng / đối tác hãng."},"SpendCap":{"type":"object","properties":{"spend_cap_vnd":{"type":["integer","null"],"minimum":-9007199254740991,"maximum":9007199254740991,"description":"Hạn mức trần chi tiêu (null = không hạn chế).","example":4500000}},"required":["spend_cap_vnd"],"description":"Trần chi tiêu của tổ chức."},"SplitRule":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/SplitRuleId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"kind":{"$ref":"#/components/schemas/SplitRuleKind"},"partner_id":{"$ref":"#/components/schemas/PartnerId"},"name":{"type":"string","minLength":1,"maxLength":120},"active_version":{"type":"integer"},"current_version":{"$ref":"#/components/schemas/SplitRuleVersion"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","org_id","kind","partner_id","name","created_at","updated_at"],"description":"Quy tắc chia doanh thu cho đối tác."},"SplitRuleBasis":{"type":"string","enum":["net_after_platform_fee","gross","gross_profit","pre_voucher","list_price_discount"],"description":"Cơ sở tính chia: `net_after_platform_fee` sau phí sàn · `gross` tổng tiền hàng · `gross_profit` lãi gộp · `pre_voucher` trước voucher sàn · `list_price_discount` chiết khấu giá niêm yết."},"SplitRuleConds":{"type":"object","properties":{"brands":{"type":"array","items":{"type":"string"}},"platforms":{"type":"array","items":{"$ref":"#/components/schemas/SettlementPlatform"}},"ctv_codes":{"type":"array","items":{"type":"string"}},"sku_prefixes":{"type":"array","items":{"type":"string"}}},"description":"Điều kiện lọc áp dụng quy tắc chia."},"SplitRuleId":{"type":"string","pattern":"^spl_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã quy tắc chia doanh thu (`spl_…`).","example":"spl_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"SplitRuleKind":{"type":"string","enum":["payable_brand","payable_ctv","receivable_agent"],"description":"`payable_brand` phải trả hãng/nhà cung cấp · `payable_ctv` phải trả CTV · `receivable_agent` phải thu đại lý."},"SplitRuleLintWarning":{"type":"object","properties":{"code":{"type":"string","enum":["overlap"]},"severity":{"type":"string","enum":["ambiguous","shadowing"],"description":"`ambiguous` cùng ưu tiên và cùng ngày hiệu lực (không thể duyệt) · `shadowing` một quy tắc thắng theo ưu tiên/ngày hiệu lực."},"other_rule_id":{"$ref":"#/components/schemas/SplitRuleId"},"other_version_id":{"$ref":"#/components/schemas/SplitRuleVersionId"},"other_rule_name":{"type":"string"},"other_partner_id":{"$ref":"#/components/schemas/PartnerId"},"winner":{"type":"string","enum":["this","other"],"description":"Quy tắc được áp dụng cho các đơn hàng trùng điều kiện."},"detail":{"type":"string"}},"required":["code","severity","other_rule_id","other_version_id","other_rule_name","other_partner_id","winner","detail"],"description":"Cảnh báo chồng lấn điều kiện giữa hai quy tắc chia cùng loại."},"SplitRuleList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SplitRule"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"SplitRuleTrigger":{"type":"string","enum":["on_delivered","on_payout","after_return_window_7d","monthly_close","day_5_next_month","invoice_net_30"],"description":"Thời điểm kích hoạt sinh nghĩa vụ: `on_delivered` khi giao thành công · `on_payout` khi sàn khớp payout · `after_return_window_7d` sau 7 ngày không hoàn · `monthly_close` chốt tháng · `day_5_next_month` mùng 5 tháng sau · `invoice_net_30` sau 30 ngày xuất hoá đơn."},"SplitRuleVersion":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/SplitRuleVersionId"},"rule_id":{"$ref":"#/components/schemas/SplitRuleId"},"version":{"type":"integer","minimum":1},"conds":{"$ref":"#/components/schemas/SplitRuleConds"},"pct_bp":{"type":"integer","minimum":0,"maximum":10000,"description":"Tỷ lệ chia theo basis points (7000 = 70.00%)"},"basis":{"$ref":"#/components/schemas/SplitRuleBasis"},"trigger":{"$ref":"#/components/schemas/SplitRuleTrigger"},"effective_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Ngày bắt đầu có hiệu lực (YYYY-MM-DD), không áp dụng hồi tố","example":"2026-10-19"},"state":{"$ref":"#/components/schemas/SplitRuleVersionState"},"created_by":{"anyOf":[{"$ref":"#/components/schemas/UserId"},{"type":"null"}]},"approved_by":{"anyOf":[{"$ref":"#/components/schemas/UserId"},{"type":"null"}]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"approved_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"lint_warnings":{"type":"array","items":{"$ref":"#/components/schemas/SplitRuleLintWarning"},"description":"Cảnh báo chồng lấn điều kiện với quy tắc đang áp dụng cùng loại; chỉ có khi tạo hoặc duyệt phiên bản."}},"required":["id","rule_id","version","conds","pct_bp","basis","trigger","effective_from","state","created_at"],"description":"Phiên bản quy tắc chia doanh thu có hiệu lực theo ngày."},"SplitRuleVersionId":{"type":"string","pattern":"^spv_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã phiên bản quy tắc chia (`spv_…`).","example":"spv_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"SplitRuleVersionState":{"type":"string","enum":["draft","pending_approval","active","superseded"],"description":"`draft` bản thảo · `pending_approval` chờ duyệt · `active` đang áp dụng · `superseded` đã thay thế."},"StatementAccepted":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"},"statement":{"$ref":"#/components/schemas/StatementRef"}},"required":["job","statement"],"description":"Tác vụ đã nhận (`202`) hoặc sao kê trùng tệp đã có (`200`, cùng dạng)."},"StatementBalanceCheck":{"type":"object","properties":{"status":{"type":"string","enum":["ok","mismatch","not_checkable"]},"opening":{"type":["integer","null"],"minimum":-9007199254740991,"maximum":9007199254740991,"description":"Số dư đầu kỳ ghi trong tệp.","example":4500000},"closing":{"type":["integer","null"],"minimum":-9007199254740991,"maximum":9007199254740991,"description":"Số dư cuối kỳ ghi trong tệp.","example":4500000},"sum_in":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Tổng tiền vào.","example":4500000},"sum_out":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Tổng tiền ra.","example":4500000},"computed_closing":{"type":["integer","null"],"minimum":-9007199254740991,"maximum":9007199254740991,"description":"`opening + sum_in − sum_out`.","example":4500000},"diff":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Số dư báo cáo trừ số dư tính lại; `0` khi khớp.","example":4500000},"order":{"type":"string","enum":["asc","desc"],"description":"Tệp xếp cũ→mới (`asc`) hay mới→cũ (`desc`)."},"first_bad_row":{"type":["integer","null"],"exclusiveMinimum":0,"description":"Dòng đầu tiên mà chuỗi số dư bị đứt."},"mismatch_count":{"type":"integer","minimum":0},"hints":{"type":"array","items":{"type":"string"},"description":"Gợi ý nguyên nhân: `swap_debit_credit`, `wrong_balance_column`, `reversed_order`, `missing_rows`."}},"required":["status","opening","closing","sum_in","sum_out","computed_closing","diff","order","first_bad_row","mismatch_count","hints"],"description":"Kiểm tra số dư đầu/cuối và chuỗi số dư từng dòng. `mismatch` ⇒ trạng thái `halted_balance_mismatch`."},"StatementColumnField":{"type":"string","enum":["date","time","value_date","debit","credit","amount","dc_flag","balance","description","ref","counterparty_name","counterparty_account","currency"],"description":"Trường của dòng sao kê: `date` ngày, `time` giờ, `value_date` ngày hiệu lực, `debit`/`credit` ghi nợ/có, `amount` số tiền một cột (kèm `dc_flag` hoặc dấu), `balance` số dư sau giao dịch, `description` nội dung, `ref` mã tham chiếu, `counterparty_*` đối tác, `currency` tiền tệ."},"StatementColumnMapping":{"type":"object","properties":{"layout_id":{"type":"string","maxLength":64,"description":"Mã bố cục đã nhận dạng (ví dụ `acb`)."},"header_row":{"type":"integer","minimum":0,"maximum":1000,"description":"Dòng tiêu đề (đếm từ 0)."},"header_rows":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}],"description":"Số dòng tiêu đề (mặc định 1)."},"columns":{"type":"object","properties":{"date":{"type":"integer","minimum":0,"maximum":1023},"time":{"type":"integer","minimum":0,"maximum":1023},"value_date":{"type":"integer","minimum":0,"maximum":1023},"debit":{"type":"integer","minimum":0,"maximum":1023},"credit":{"type":"integer","minimum":0,"maximum":1023},"amount":{"type":"integer","minimum":0,"maximum":1023},"dc_flag":{"type":"integer","minimum":0,"maximum":1023},"balance":{"type":"integer","minimum":0,"maximum":1023},"description":{"type":"integer","minimum":0,"maximum":1023},"ref":{"type":"integer","minimum":0,"maximum":1023},"counterparty_name":{"type":"integer","minimum":0,"maximum":1023},"counterparty_account":{"type":"integer","minimum":0,"maximum":1023},"currency":{"type":"integer","minimum":0,"maximum":1023}},"description":"Chỉ số cột (đếm từ 0) của từng trường; trường nào không có cột thì bỏ qua."}},"required":["header_row","columns"],"description":"Ánh xạ cột của sao kê dạng bảng.","example":{"layout_id":"acb","header_row":8,"columns":{"date":0,"debit":3,"credit":4,"balance":5,"description":2}}},"StatementColumns":{"type":"object","properties":{"header_row":{"type":["integer","null"],"minimum":0},"header_cells":{"type":"array","items":{"type":"string"}},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"$ref":"#/components/schemas/StatementColumnField"},"column":{"type":["integer","null"],"minimum":0,"description":"Cột được gán; `null` = bỏ qua."},"header":{"type":["string","null"]},"is_new":{"type":"boolean","description":"`true`: ánh xạ mới, chưa từng lưu cho bố cục này."}},"required":["field","column","header","is_new"]}},"suggested_mapping":{"anyOf":[{"$ref":"#/components/schemas/StatementColumnMapping"},{"type":"null"}]},"sample_rows":{"type":"array","items":{"$ref":"#/components/schemas/StatementSampleRow"},"maxItems":5}},"required":["header_row","header_cells","fields","suggested_mapping","sample_rows"],"description":"Bước nhận dạng và ánh xạ cột (chỉ có với Excel/CSV)."},"StatementFormat":{"type":"string","enum":["xlsx","xls","csv","mt940","camt053"],"description":"Định dạng tệp: `xlsx`, `xls`, `csv`, `mt940`, `camt053`."},"StatementImport":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StatementImportId"},"object":{"type":"string","enum":["statement"]},"company_id":{"$ref":"#/components/schemas/OrgId"},"bank_account_id":{"$ref":"#/components/schemas/AccountId"},"state":{"$ref":"#/components/schemas/StatementImportState"},"source":{"$ref":"#/components/schemas/StatementSource"},"schedule_id":{"anyOf":[{"$ref":"#/components/schemas/StatementScheduleId"},{"type":"null"}]},"file":{"type":"object","properties":{"name":{"type":["string","null"]},"sha256":{"type":["string","null"],"description":"SHA-256 (hex) của tệp gốc."},"bytes":{"type":["integer","null"],"minimum":0},"format":{"anyOf":[{"$ref":"#/components/schemas/StatementFormat"},{"type":"null"}]},"layout_id":{"type":["string","null"]},"bank_code":{"type":["string","null"]}},"required":["name","sha256","bytes","format","layout_id","bank_code"],"description":"Tệp đã tải lên."},"period":{"type":["object","null"],"properties":{"from":{"$ref":"#/components/schemas/Date"},"to":{"$ref":"#/components/schemas/Date"}},"required":["from","to"],"description":"Kỳ sao kê (giờ Việt Nam)."},"total_rows":{"type":["integer","null"],"minimum":0},"counts":{"$ref":"#/components/schemas/ImportCounts"},"upgraded":{"type":"integer","minimum":0,"description":"Số giao dịch tạm tính đã nâng xác thực."},"mapping_id":{"anyOf":[{"$ref":"#/components/schemas/StatementMappingId"},{"type":"null"}]},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"detail":{"type":["string","null"]}},"required":["code","detail"],"description":"Có khi `state=failed` (ví dụ `MISSING_COLUMN`, `TOO_MANY_ROWS`)."},"preview_job_id":{"anyOf":[{"$ref":"#/components/schemas/JobId"},{"type":"null"}]},"commit_job_id":{"anyOf":[{"$ref":"#/components/schemas/JobId"},{"type":"null"}]},"created_by":{"type":["string","null"]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"started_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"finished_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"preview":{"anyOf":[{"$ref":"#/components/schemas/StatementPreview"},{"type":"null"}],"description":"Có từ `preview_ready` (và khi `halted_balance_mismatch`)."},"result":{"anyOf":[{"$ref":"#/components/schemas/StatementResult"},{"type":"null"}],"description":"Có khi đã nhập xong."}},"required":["id","object","company_id","bank_account_id","state","source","schedule_id","file","period","total_rows","counts","upgraded","mapping_id","error","preview_job_id","commit_job_id","created_by","created_at","started_at","finished_at","updated_at","preview","result"],"description":"Một lần nhập sao kê: trạng thái, xem trước và kết quả."},"StatementImportId":{"type":"string","pattern":"^imp_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã lần nhập sao kê (`imp_…`).","example":"imp_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"StatementImportList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/StatementImportSummary"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"StatementImportState":{"type":"string","enum":["created","validating","preview_ready","committing","completed","completed_with_errors","failed","cancelled","halted_balance_mismatch"],"description":"`created` → `validating` → `preview_ready` → `committing` → `completed` | `completed_with_errors`; `failed`, `cancelled`. `halted_balance_mismatch`: số dư không khớp, không nhập được."},"StatementImportSummary":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StatementImportId"},"object":{"type":"string","enum":["statement"]},"company_id":{"$ref":"#/components/schemas/OrgId"},"bank_account_id":{"$ref":"#/components/schemas/AccountId"},"state":{"$ref":"#/components/schemas/StatementImportState"},"source":{"$ref":"#/components/schemas/StatementSource"},"schedule_id":{"anyOf":[{"$ref":"#/components/schemas/StatementScheduleId"},{"type":"null"}]},"file":{"type":"object","properties":{"name":{"type":["string","null"]},"sha256":{"type":["string","null"],"description":"SHA-256 (hex) của tệp gốc."},"bytes":{"type":["integer","null"],"minimum":0},"format":{"anyOf":[{"$ref":"#/components/schemas/StatementFormat"},{"type":"null"}]},"layout_id":{"type":["string","null"]},"bank_code":{"type":["string","null"]}},"required":["name","sha256","bytes","format","layout_id","bank_code"],"description":"Tệp đã tải lên."},"period":{"type":["object","null"],"properties":{"from":{"$ref":"#/components/schemas/Date"},"to":{"$ref":"#/components/schemas/Date"}},"required":["from","to"],"description":"Kỳ sao kê (giờ Việt Nam)."},"total_rows":{"type":["integer","null"],"minimum":0},"counts":{"$ref":"#/components/schemas/ImportCounts"},"upgraded":{"type":"integer","minimum":0,"description":"Số giao dịch tạm tính đã nâng xác thực."},"mapping_id":{"anyOf":[{"$ref":"#/components/schemas/StatementMappingId"},{"type":"null"}]},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"detail":{"type":["string","null"]}},"required":["code","detail"],"description":"Có khi `state=failed` (ví dụ `MISSING_COLUMN`, `TOO_MANY_ROWS`)."},"preview_job_id":{"anyOf":[{"$ref":"#/components/schemas/JobId"},{"type":"null"}]},"commit_job_id":{"anyOf":[{"$ref":"#/components/schemas/JobId"},{"type":"null"}]},"created_by":{"type":["string","null"]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"started_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"finished_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","object","company_id","bank_account_id","state","source","schedule_id","file","period","total_rows","counts","upgraded","mapping_id","error","preview_job_id","commit_job_id","created_by","created_at","started_at","finished_at","updated_at"],"description":"Một dòng trong danh sách sao kê (không kèm xem trước)."},"StatementMapping":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StatementMappingId"},"object":{"type":"string","enum":["statement_mapping"]},"company_id":{"$ref":"#/components/schemas/OrgId"},"bank_code":{"type":"string","minLength":1,"maxLength":16},"header_fingerprint":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 của các ô tiêu đề đã chuẩn hoá."},"mapping":{"$ref":"#/components/schemas/StatementColumnMapping"},"template_name":{"type":["string","null"]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","object","company_id","bank_code","header_fingerprint","mapping","template_name","created_at","updated_at"],"description":"Mẫu ánh xạ cột đã lưu cho một bố cục sao kê."},"StatementMappingId":{"type":"string","pattern":"^smp_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã mẫu ánh xạ cột sao kê (`smp_…`).","example":"smp_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"StatementMappingList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/StatementMapping"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"StatementPreview":{"type":"object","properties":{"balance_check":{"$ref":"#/components/schemas/StatementBalanceCheck"},"counts":{"$ref":"#/components/schemas/StatementPreviewCounts"},"columns":{"anyOf":[{"$ref":"#/components/schemas/StatementColumns"},{"type":"null"}],"description":"`null` với MT940/CAMT (không có cột)."}},"required":["balance_check","counts","columns"],"description":"Bản xem trước: kiểm số dư, đếm, ánh xạ cột."},"StatementPreviewCounts":{"type":"object","properties":{"new":{"type":"integer","minimum":0},"merged":{"type":"integer","minimum":0,"description":"Khớp giao dịch sẵn có."},"upgraded":{"type":"integer","minimum":0,"description":"Trong số khớp: số giao dịch tạm tính sẽ được nâng xác thực."},"skipped":{"type":"integer","minimum":0,"description":"Trùng, bỏ qua."},"error":{"type":"integer","minimum":0},"locked":{"type":"integer","minimum":0,"description":"Dòng thuộc kỳ đã khoá: không nhập."}},"required":["new","merged","upgraded","skipped","error","locked"],"description":"Kết quả chạy thử (chưa ghi gì vào sổ)."},"StatementPreviewRow":{"type":"object","properties":{"row_no":{"type":"integer","exclusiveMinimum":0,"description":"Số dòng trong tệp gốc (đếm từ 1)."},"date":{"$ref":"#/components/schemas/Date"},"time":{"type":["string","null"],"description":"`HH:mm` hoặc `HH:mm:ss` khi tệp có giờ."},"direction":{"type":"string","enum":["in","out"]},"amount":{"$ref":"#/components/schemas/Vnd"},"balance_after":{"anyOf":[{"$ref":"#/components/schemas/Vnd"},{"type":"null"}]},"description":{"type":"string"},"bank_ref":{"type":["string","null"]},"counterparty_name":{"type":["string","null"]},"status":{"type":"string","enum":["new","merged","skipped","error","locked"]},"upgrade":{"type":"boolean","description":"`true`: khớp giao dịch tạm tính và sẽ nâng xác thực (\"Khớp & nâng xác thực\")."},"error":{"type":["string","null"]},"tx_id":{"type":["string","null"],"pattern":"^tx_[0-9a-hjkmnp-tv-z]{26}$","description":"Giao dịch khớp (khi `status=merged`).","example":"tx_0f5k2m9q4h7t3n8r6v1w0x5yz0"}},"required":["row_no","date","time","direction","amount","balance_after","description","bank_ref","counterparty_name","status","upgrade","error","tx_id"],"description":"Một dòng của bản xem trước."},"StatementRef":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StatementImportId"},"state":{"$ref":"#/components/schemas/StatementImportState"}},"required":["id","state"]},"StatementResult":{"type":"object","properties":{"anchors":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["opening","closing"]},"as_of":{"$ref":"#/components/schemas/Timestamp"},"reported":{"$ref":"#/components/schemas/Vnd"},"state":{"type":"string","enum":["ok","mismatch","gap_suspected"]}},"required":["kind","as_of","reported","state"]}},"unmatched_provisional":{"type":"array","items":{"$ref":"#/components/schemas/TxId"},"maxItems":200,"description":"Giao dịch tạm tính trong kỳ mà sao kê không có (\"Không có trong sao kê\"), tối đa 200."},"unmatched_count":{"type":"integer","minimum":0},"promoted":{"type":"integer","minimum":0,"description":"Số giao dịch tạm tính đã được nâng lên xác thực."}},"required":["anchors","unmatched_provisional","unmatched_count","promoted"],"description":"Kết quả sau khi nhập: neo số dư và giao dịch tạm tính không có trong sao kê."},"StatementRowsPage":{"type":"object","properties":{"object":{"type":"string","enum":["statement_rows"]},"page":{"type":"integer","exclusiveMinimum":0},"page_size":{"type":"integer","exclusiveMinimum":0},"total_rows":{"type":"integer","minimum":0},"total_pages":{"type":"integer","minimum":0},"data":{"type":"array","items":{"$ref":"#/components/schemas/StatementPreviewRow"}}},"required":["object","page","page_size","total_rows","total_pages","data"],"description":"Một trang (500 dòng) của bản xem trước."},"StatementSampleRow":{"type":"object","properties":{"row_no":{"type":"integer","exclusiveMinimum":0},"date":{"anyOf":[{"$ref":"#/components/schemas/Date"},{"type":"null"}]},"direction":{"type":["string","null"],"enum":["in","out",null]},"amount":{"anyOf":[{"$ref":"#/components/schemas/Vnd"},{"type":"null"}]},"balance_after":{"anyOf":[{"$ref":"#/components/schemas/Vnd"},{"type":"null"}]},"description":{"type":"string"},"valid":{"type":"boolean"},"error":{"type":["string","null"],"description":"Mã lỗi dòng (`bad_date`, `non_integer_vnd`, …)."}},"required":["row_no","date","direction","amount","balance_after","description","valid","error"],"description":"Một dòng mẫu của bước ánh xạ cột."},"StatementSchedule":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StatementScheduleId"},"object":{"type":"string","enum":["statement_schedule"]},"company_id":{"$ref":"#/components/schemas/OrgId"},"bank_account_id":{"$ref":"#/components/schemas/AccountId"},"source":{"type":"string","enum":["email_attachment","manual_upload","sftp"]},"format":{"type":"string","enum":["auto","xlsx","csv","mt940","camt053"]},"cron":{"type":["string","null"]},"next_run_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"last_run_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"last_job_id":{"anyOf":[{"$ref":"#/components/schemas/StatementImportId"},{"type":"null"}],"description":"Sao kê của lần chạy gần nhất."},"alias_id":{"anyOf":[{"$ref":"#/components/schemas/EmailAliasId"},{"type":"null"}]},"sftp":{"anyOf":[{"$ref":"#/components/schemas/SftpConfig"},{"type":"null"}],"description":"Chỉ có với `source=sftp`. Mật khẩu/khoá không bao giờ trả về."},"auto_commit":{"type":"boolean","description":"`true`: tự nhập khi không có dòng lỗi và số dư khớp; ngược lại chờ người xác nhận."},"overdue_after_days":{"type":"integer","minimum":1,"maximum":90,"description":"Quá số ngày này kể từ lúc đến hạn mà chưa có sao kê: trạng thái `overdue` (\"Quá hạn nhắc\")."},"enabled":{"type":"boolean"},"status":{"type":"string","enum":["never","ok","failed","overdue"]},"last_result":{"type":["object","null"],"additionalProperties":{},"description":"Đếm của lần chạy gần nhất (`rows`, `new`, `skipped`, `error`…), không có nội dung dòng."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","object","company_id","bank_account_id","source","format","cron","next_run_at","last_run_at","last_job_id","alias_id","sftp","auto_commit","overdue_after_days","enabled","status","last_result","created_at","updated_at"],"description":"Lịch nhận sao kê của một tài khoản."},"StatementScheduleId":{"type":"string","pattern":"^ssc_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã lịch nhận sao kê (`ssc_…`).","example":"ssc_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"StatementScheduleList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/StatementSchedule"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"StatementSource":{"type":"string","enum":["upload","email_attachment","sftp","schedule_run"],"description":"Nơi tệp đến: `upload` tải tay, `email_attachment` thư đính kèm, `sftp`, `schedule_run` chạy theo lịch."},"StoreId":{"type":"string","pattern":"^sto_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã cửa hàng (`sto_…`).","example":"sto_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"StoreRef":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StoreId"},"name":{"type":"string"},"slug":{"type":"string"}},"required":["id","name","slug"]},"SwitchRoot":{"type":"object","properties":{"root_id":{"type":"string","pattern":"^org_[0-9a-hjkmnp-tv-z]{26}$","description":"Gốc tổ chức muốn chuyển sang.","example":"org_0f5k2m9q4h7t3n8r6v1w0x5yz0"}},"required":["root_id"]},"SyncChange":{"type":"object","properties":{"seq":{"type":"integer","exclusiveMinimum":0,"description":"Số thứ tự thay đổi trong tài khoản (tăng đơn điệu, không bỏ sót)."},"account_id":{"$ref":"#/components/schemas/AccountId"},"change":{"type":"string","enum":["created","verified","merged","unmerged","quarantined","released","annotated","source_added","rejected","recon_changed"]},"transaction":{"$ref":"#/components/schemas/Transaction"}},"required":["seq","account_id","change","transaction"],"description":"Một thay đổi. `transaction` là trạng thái hiện tại của giao dịch, không phải ảnh chụp lúc thay đổi."},"SyncPage":{"type":"object","properties":{"object":{"type":"string","enum":["sync_page"]},"changes":{"type":"array","items":{"$ref":"#/components/schemas/SyncChange"}},"next_cursor":{"type":"string","maxLength":4096,"pattern":"^cur_[A-Za-z0-9_-]+(\\.[A-Za-z0-9_-]+)?$","description":"Luôn có; lưu lại và dùng cho lần gọi kế tiếp, kể cả khi `changes` rỗng.","example":"cur_eyJ2IjoxfQ.AAAAAAAAAAAAAAAAAAAAAA"},"has_more":{"type":"boolean"}},"required":["object","changes","next_cursor","has_more"],"description":"Các thay đổi giao dịch kể từ con trỏ."},"Timestamp":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Thời điểm RFC 3339, luôn ở UTC (hậu tố `Z`).","example":"2026-10-19T01:30:15Z"},"TopupQrRequest":{"type":"object","properties":{"amount_vnd":{"type":"integer","exclusiveMinimum":0,"maximum":50000000,"minimum":50000,"description":"Số tiền nạp (tối thiểu 50.000 ₫).","example":4500000}},"required":["amount_vnd"],"description":"Yêu cầu nạp credit dịch vụ."},"TopupQrResponse":{"type":"object","properties":{"topup_id":{"type":"string","description":"Mã giao dịch nạp credit."},"memo_code":{"type":"string","description":"Mã nội dung DTP…"},"amount_vnd":{"$ref":"#/components/schemas/PositiveVnd"},"qr_payload":{"type":"string"},"expires_at":{"$ref":"#/components/schemas/Timestamp"},"bank_account":{"$ref":"#/components/schemas/BankAccountRecipient"}},"required":["topup_id","memo_code","amount_vnd","qr_payload","expires_at","bank_account"],"description":"Mã VietQR nạp credit dịch vụ."},"Transaction":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/TxId"},"object":{"type":"string","enum":["transaction"]},"account":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AccountId"},"label":{"type":"string","example":"ACB •••4521"},"last4":{"type":"string","pattern":"^\\d{4}$"},"bank":{"type":"string","example":"ACB"}},"required":["id","label","last4","bank"]},"company":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/OrgId"},"mst":{"type":["string","null"]}},"required":["id","mst"]},"amount":{"$ref":"#/components/schemas/PositiveVnd"},"currency":{"type":"string","enum":["VND"]},"direction":{"type":"string","enum":["in","out"]},"status":{"$ref":"#/components/schemas/TransactionStatus"},"verified_by":{"type":["string","null"],"enum":["openapi","statement","trusted_sender","email_dkim","manual","import",null],"description":"Bằng chứng đã xác thực giao dịch; `null` khi còn `provisional`."},"lifecycle":{"type":"string","enum":["active","merged_child","quarantined","rejected","released"]},"recon_status":{"type":"string","enum":["unreconciled","suggested","pending_approval","reconciled","not_required","routed_settlement"]},"sources":{"type":"array","items":{"type":"string","enum":["android","ios","email","openapi","statement","import"]},"description":"Các kênh đã báo giao dịch này (sau khi gộp)."},"memo_code":{"type":["string","null"],"description":"Mã nội dung chuyển khoản `DTP…` đã trích."},"description":{"type":["string","null"]},"counterparty":{"type":["object","null"],"properties":{"name_masked":{"type":["string","null"]}},"required":["name_masked"]},"balance_after":{"type":["integer","null"],"minimum":-9007199254740991,"maximum":9007199254740991,"description":"Số dư sau giao dịch nếu nguồn có; không bao giờ suy đoán.","example":4500000},"occurred_at":{"$ref":"#/components/schemas/Timestamp"},"occurred_precision":{"type":"string","enum":["date","minute","second"]},"received_at":{"$ref":"#/components/schemas/Timestamp"},"payment_request":{"anyOf":[{"$ref":"#/components/schemas/PaymentRequestId"},{"type":"null"}]},"merged_into":{"type":["string","null"],"pattern":"^tx_[0-9a-hjkmnp-tv-z]{26}$","description":"Khi bị gộp, mã giao dịch chính; mã `tx_` cũ vẫn truy cập được.","example":"tx_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"source_count":{"type":"integer","minimum":1,"description":"Số nguồn đã gộp vào giao dịch này (“Gộp từ n nguồn”)."},"quarantine_reason":{"type":["string","null"],"description":"Lý do cách ly khi `lifecycle` là `quarantined`/`rejected`: `unverified_sender`, `device_sig_invalid`, `dkim_fail`, `domain_mismatch` hoặc lý do do người vận hành nhập; `null` nếu không bị cách ly."},"dedupe_hint":{"type":["string","null"],"enum":["ambiguous","near_duplicate","locked_period","quarantined_source",null],"description":"Gợi ý khử trùng lúc nhập: `ambiguous` (nhiều ứng viên, không gộp), `near_duplicate` (giống nhưng chưa đủ điểm), `locked_period` (kỳ đã khoá), `quarantined_source` (nguồn bị cách ly nên không gộp)."},"chain_flag":{"type":["string","null"],"enum":["chain_mismatch","gap_suspected",null],"description":"Chuỗi số dư nghi ngờ quanh giao dịch: `chain_mismatch` số dư mâu thuẫn, `gap_suspected` nghi thiếu giao dịch. Chỉ đánh dấu nhất quán — không đổi trạng thái xác thực (D36)."}},"required":["id","object","account","company","amount","currency","direction","status","verified_by","lifecycle","recon_status","sources","memo_code","description","counterparty","balance_after","occurred_at","occurred_precision","received_at","payment_request","merged_into"],"description":"Giao dịch ngân hàng."},"TransactionApprovalRef":{"type":"object","properties":{"object":{"type":"string","enum":["approval_request"]},"id":{"$ref":"#/components/schemas/ApprovalRequestId"},"kind":{"type":"string","enum":["tx_verify_manual"]},"state":{"type":"string","enum":["pending","approved","rejected","withdrawn","expired"]},"transaction_id":{"$ref":"#/components/schemas/TxId"},"expires_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["object","id","kind","state","transaction_id","expires_at"],"description":"Yêu cầu duyệt xác nhận thủ công đang chờ người thứ hai."},"TransactionEvent":{"type":"object","properties":{"object":{"type":"string","enum":["transaction_event"]},"at":{"$ref":"#/components/schemas/Timestamp"},"kind":{"type":"string","enum":["created","verified","merged","unmerged","quarantined","released","activated","rejected","recon_changed","annotated","source_added","relation_added","quota_eligible"]},"actor":{"type":"string","description":"`user:usr_…`, `system:pipeline`, `key:apk_…`…"},"detail":{"type":"object","additionalProperties":{}}},"required":["object","at","kind","actor","detail"],"description":"Một dòng trong nhật ký của giao dịch (chỉ thêm, không sửa)."},"TransactionEventList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/TransactionEvent"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"TransactionExportFile":{"type":"object","properties":{"object":{"type":"string","enum":["transaction_export"]},"data":{"type":"array","items":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}]}}}},"required":["object","data"],"description":"Tệp JSON của lệnh xuất: mỗi phần tử là một dòng giao dịch (số TK chỉ 4 số cuối, tên người gửi đã che)."},"TransactionList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"TransactionListPreset":{"type":"string","enum":["all","needs_action","in_today","provisional_24h","unreconciled","quarantined"],"description":"Bộ lọc nhanh: `all` Tất cả · `needs_action` Cần xử lý (tạm tính >24 giờ hoặc đã xác thực nhưng chưa đối soát) · `in_today` Vào hôm nay (tiền vào từ 00:00 giờ Việt Nam) · `provisional_24h` Tạm tính >24 giờ · `unreconciled` Chưa đối soát · `quarantined` Cách ly (liệt kê cả giao dịch cách ly dù mặc định bị ẩn)."},"TransactionListSort":{"type":"string","enum":["occurred_at_desc","occurred_at_asc","amount_desc","amount_asc"],"description":"Thứ tự danh sách (mặc định `occurred_at_desc`, mới nhất trước). Con trỏ gắn với thứ tự: dùng con trỏ của thứ tự khác trả `400 invalid_cursor`."},"TransactionSource":{"type":"object","properties":{"object":{"type":"string","enum":["transaction_source"]},"channel":{"type":"string","enum":["android","ios","email","openapi","statement","import"]},"received_at":{"$ref":"#/components/schemas/Timestamp"},"trust_at_receipt":{"type":"string","enum":["verified","provisional","quarantined"]},"sender_trust":{"type":"string","enum":["os_sender_match","app_package_match","unverified_sender","unavailable","none"]},"trust_basis":{"type":["string","null"],"enum":["trusted_sender","sender_verified_ios","email_dkim_direct","email_dkim_forwarded","none",null]},"source_ref":{"type":["string","null"],"description":"Mã tham chiếu của nguồn (id ngân hàng, message-id…), đã che nếu nhạy cảm."},"parser_id":{"type":["string","null"],"description":"Bộ phân tích đã đọc tin (`vcb.sms`…); `null` với nguồn không qua parser."},"parser_version":{"type":["string","null"],"description":"Phiên bản bộ phân tích."},"confidence":{"type":["number","null"],"minimum":0,"maximum":1,"description":"Độ tin cậy của parser (0–1). `null` khi hệ thống không lưu — hiện `tx_sources` chưa có cột này."},"raw_sha256":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$","description":"SHA-256 (hex) của nội dung gốc; còn sau khi bản gốc hết hạn lưu."},"device_id":{"type":["string","null"],"description":"Thiết bị đã gửi tin (`dev_…`)."},"sms_sent_at":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Thời điểm SMSC gửi tin.","example":"2026-10-19T01:30:15Z"},"dkim_summary":{"type":["object","null"],"properties":{"d":{"type":["string","null"]},"selector":{"type":["string","null"]},"result":{"type":["string","null"]},"forwarded":{"type":["boolean","null"]}},"description":"Kết quả DKIM của email: miền ký, selector, kết quả, có chuyển tiếp hay không."},"raw_masked":{"type":["string","null"],"description":"Nội dung gốc đã che mọi chuỗi ≥ 8 chữ số (`•••1234`). Chỉ có khi người gọi có `tx.read_raw`; `null` khi bản gốc đã hết hạn lưu hoặc không còn giải mã được."}},"required":["object","channel","received_at","trust_at_receipt","sender_trust","trust_basis","source_ref"],"description":"Một nguồn bằng chứng của giao dịch."},"TransactionSourceList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/TransactionSource"}},"next_cursor":{"type":["string","null"],"description":"Con trỏ trang kế; `null` khi hết dữ liệu."},"has_more":{"type":"boolean"}},"required":["object","data","next_cursor","has_more"]},"TransactionStatus":{"type":"string","enum":["provisional","confirmed"],"description":"`confirmed`: đã xác thực bởi nguồn đáng tin (tiền về). `provisional`: tạm tính, chưa đủ bằng chứng — không coi là tiền về."},"TransactionSummary":{"type":"object","properties":{"object":{"type":"string","enum":["transaction_summary"]},"from":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"$ref":"#/components/schemas/Date"}]},"to":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"$ref":"#/components/schemas/Date"}]},"presets":{"type":"object","properties":{"all":{"type":"integer","minimum":0},"needs_attention":{"type":"integer","minimum":0},"in_today":{"type":"integer","minimum":0},"provisional_over_24h":{"type":"integer","minimum":0},"unreconciled":{"type":"integer","minimum":0},"quarantined":{"type":"integer","minimum":0}},"required":["all","needs_attention","in_today","provisional_over_24h","unreconciled","quarantined"],"description":"Số giao dịch theo các bộ lọc nhanh: Tất cả · Cần xử lý · Vào hôm nay · Tạm tính >24h · Chưa đối soát · Cách ly."},"totals":{"type":"object","properties":{"in":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Tổng tiền vào (gồm cả tạm tính).","example":4500000},"out":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Tổng tiền ra (gồm cả tạm tính).","example":4500000},"provisional_in":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Trong đó tiền vào còn tạm tính.","example":4500000},"provisional_out":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Trong đó tiền ra còn tạm tính.","example":4500000},"count":{"type":"integer","minimum":0}},"required":["in","out","provisional_in","provisional_out","count"]},"groups":{"type":"array","items":{"type":"object","properties":{"in":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Tổng tiền vào (gồm cả tạm tính).","example":4500000},"out":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Tổng tiền ra (gồm cả tạm tính).","example":4500000},"provisional_in":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Trong đó tiền vào còn tạm tính.","example":4500000},"provisional_out":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Trong đó tiền ra còn tạm tính.","example":4500000},"count":{"type":"integer","minimum":0},"key":{"type":"string"},"label":{"type":["string","null"]}},"required":["in","out","provisional_in","provisional_out","count","key","label"]},"description":"Chỉ có khi truyền `group_by`."}},"required":["object","from","to","presets","totals"],"description":"Tổng hợp giao dịch trong khoảng thời gian."},"TransferOrg":{"type":"object","properties":{"customer_email":{"type":"string","format":"email","description":"Email của khách: họ nhận lời mời làm chủ sở hữu công ty này."},"billing_payer":{"type":"string","enum":["firm","customer"],"default":"customer"},"isolation":{"type":"string","enum":["hard","consolidate"],"default":"hard"}},"required":["customer_email"],"example":{"customer_email":"chu@khach.example","billing_payer":"customer","isolation":"hard"}},"TriggerSandboxEventBody":{"type":"object","properties":{"type":{"type":"string","enum":["transaction.created","transaction.confirmed","transaction.merged","transaction.quarantined","transaction.released","channel.degraded","device.offline","device.online","reconcile.proposed","reconcile.approved","reconcile.rejected","reconcile.reversed","invoice.payment_posted","invoice.payment_writeback_failed","payment.received","payment.partial","payment.overpaid","payment.expired","collect.bill.paid","connection.expiring","connection.failed","apikey.expiring","export.completed","export.failed","export.misa_failed","period.locked","period.unlocked","quota.threshold","cashflow.alert","settlement.payout_variance","obligation.overdue","import.completed","integration.delivery_failed","ping"],"description":"Loại sự kiện gửi tới webhook (Standard Webhooks).","example":"period.locked"},"payload":{"type":"object","additionalProperties":{},"example":{"period":"2026-09","by":"kt.truong@congtyabc.vn","approved_by":null}},"company_id":{"$ref":"#/components/schemas/OrgId"}},"required":["type","payload"]},"TriggerSandboxEventResponse":{"type":"object","properties":{"event_id":{"$ref":"#/components/schemas/EventId"},"triggered":{"type":"boolean"}},"required":["event_id","triggered"]},"TxId":{"type":"string","pattern":"^tx_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã giao dịch (`tx_…`), ổn định vĩnh viễn kể cả khi bị gộp.","example":"tx_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"UnlockPeriodRequest":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"]},"UnmergeTransaction":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"example":{"reason":"Hai giao dịch khác nhau, gộp nhầm"}},"UpcomingCashItem":{"type":"object","properties":{"date":{"$ref":"#/components/schemas/Date"},"amount":{"$ref":"#/components/schemas/PositiveVnd"},"direction":{"$ref":"#/components/schemas/ObligationDirection"},"source":{"type":"string","enum":["settlement","payout_lag","obligation"]},"confidence":{"type":"integer","minimum":0,"maximum":100},"ref":{"type":"string"},"partner_name":{"type":"string"}},"required":["date","amount","direction","source","confidence","ref"],"description":"Mục dòng tiền sắp về / sắp chi trong 7 ngày tới."},"UpdateBankAccount":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":80},"holder_name":{"type":["string","null"],"minLength":1,"maxLength":200},"type":{"type":"string","enum":["business","virtual_sub","savings"]},"state":{"type":"string","enum":["active","stopped_receiving"],"description":"`stopped_receiving`: ngừng nhận giao dịch mới nhưng giữ lịch sử."}}},"UpdateBillingInfo":{"type":"object","properties":{"tax_id":{"type":["string","null"],"default":null,"description":"Mã số thuế doanh nghiệp."},"company_name":{"type":["string","null"],"default":null,"description":"Tên doanh nghiệp trên hoá đơn GTGT."},"invoice_address":{"type":["string","null"],"default":null,"description":"Địa chỉ nhận hoá đơn GTGT."},"invoice_email":{"type":["string","null"],"format":"email","default":null,"description":"Email nhận hoá đơn GTGT điện tử."},"contact_name":{"type":["string","null"],"default":null},"contact_email":{"type":["string","null"],"format":"email","default":null}},"description":"Cập nhật thông tin xuất hoá đơn tài chính."},"UpdateDevice":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"responsible_user_id":{"anyOf":[{"$ref":"#/components/schemas/UserId"},{"type":"null"}]},"account_ids":{"type":"array","items":{"$ref":"#/components/schemas/AccountId"},"maxItems":50},"sources":{"type":"array","items":{"$ref":"#/components/schemas/DeviceSource"},"maxItems":100,"description":"Bật/tắt nguồn. Chỉ tắt thêm được nguồn trong danh sách server; không thêm được nguồn ngoài danh mục."}}},"UpdateMember":{"type":"object","properties":{"role":{"type":"string","enum":["owner","admin","accountant_chief","accountant","developer","viewer","auditor"]},"scope":{"type":"string","enum":["all","list"]},"company_ids":{"type":"array","items":{"$ref":"#/components/schemas/OrgId"},"maxItems":500,"description":"Các công ty của phạm vi `list` (chỉ với vai trò ở nút gốc)."},"require_2fa":{"type":"boolean"}}},"UpdateOrg":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"display_name":{"type":"string","pattern":"^[A-Z0-9 ]{1,25}$"},"address":{"type":["string","null"],"maxLength":500},"legal_rep":{"type":["string","null"],"maxLength":200},"alert_email":{"type":["string","null"],"maxLength":254,"format":"email","description":"`null` xoá email cảnh báo.","example":"ketoan@congty.vn"},"timezone":{"type":"string","minLength":1,"maxLength":64},"coa_profile":{"type":"string","enum":["TT133","TT99"]},"fiscal_year_start":{"type":"string","pattern":"^(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$"},"is_accounting_firm":{"type":"boolean"}}},"UpdatePartnerBody":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/PartnerKind"},"name":{"type":"string","minLength":1,"maxLength":200},"legal_name":{"type":"string","maxLength":200},"mst":{"type":"string","maxLength":20},"cycle":{"type":"object","properties":{"kind":{"type":"string","enum":["daily","weekly","monthly","biweekly"]},"params":{"type":"object","additionalProperties":{}}},"required":["kind"]},"payment_terms_days":{"type":"integer","minimum":0,"maximum":365,"default":0},"data_source":{"type":"string","enum":["excel","api_seller","manual"],"default":"excel"},"bank_account_ref":{"type":"string","maxLength":64},"internal_note":{"type":"string","maxLength":500}}},"UpdatePaymentRequest":{"type":"object","properties":{"amount":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":9999999999999},"expires_in_minutes":{"type":"integer","minimum":5,"maximum":43200},"allow_partial":{"type":"boolean"},"customer_name":{"type":["string","null"],"minLength":1,"maxLength":120},"ref":{"type":["string","null"],"minLength":1,"maxLength":64},"note":{"type":["string","null"],"minLength":1,"maxLength":500}},"example":{"amount":300000,"expires_in_minutes":60}},"UpdateSavedView":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"visibility":{"$ref":"#/components/schemas/SavedViewVisibility"},"company_id":{"anyOf":[{"$ref":"#/components/schemas/OrgId"},{"type":"null"}]},"filters":{"$ref":"#/components/schemas/SavedViewFilters"},"show_count_on_card":{"type":"boolean"},"show_in_dashboard_todo":{"type":"boolean"}}},"UpdateSpendCap":{"type":"object","properties":{"spend_cap_vnd":{"type":["integer","null"],"minimum":-9007199254740991,"maximum":9007199254740991,"description":"Đặt lại hạn mức trần chi tiêu VND (null để gỡ bỏ).","example":4500000}},"required":["spend_cap_vnd"],"description":"Cập nhật trần chi tiêu."},"UpdateStatementSchedule":{"type":"object","properties":{"format":{"type":"string","enum":["auto","xlsx","csv","mt940","camt053"]},"cron":{"type":"string","minLength":9,"maxLength":64,"pattern":"^\\S+( \\S+){4}$","description":"Lịch cron năm trường theo giờ Việt Nam (`phút giờ ngày tháng thứ`), ví dụ `0 9 1 * *` = 9 giờ sáng ngày 1 hằng tháng."},"alias_id":{"anyOf":[{"$ref":"#/components/schemas/EmailAliasId"},{"type":"null"}]},"sftp":{"type":"object","properties":{"host":{"type":"string","minLength":1,"maxLength":253},"port":{"type":"integer","minimum":1,"maximum":65535,"default":22},"path":{"type":"string","minLength":1,"maxLength":255,"description":"Thư mục hoặc mẫu tên tệp trên máy chủ SFTP, ví dụ `/out/camt053/*.xml`."},"username":{"type":"string","minLength":1,"maxLength":128},"host_key_sha256":{"type":"string","pattern":"^SHA256:[A-Za-z0-9+/]{43}$","description":"Bỏ trống để giữ khoá máy chủ đã ghim; bắt buộc khi đổi máy chủ hoặc cổng."},"secret":{"type":"string","minLength":1,"maxLength":4096,"description":"Bỏ trống để giữ khoá cũ."}},"required":["host","path","username"]},"auto_commit":{"type":"boolean"},"overdue_after_days":{"type":"integer","minimum":1,"maximum":90},"enabled":{"type":"boolean"}},"description":"Tài khoản và nguồn không đổi được: tạo lịch mới."},"UpsertConnectionBody":{"type":"object","properties":{"partner_id":{"$ref":"#/components/schemas/PartnerId"},"platform":{"$ref":"#/components/schemas/SettlementPlatform"},"shop_id":{"type":"string","minLength":1,"maxLength":64},"shop_name":{"type":"string","maxLength":120},"mode":{"type":"string","enum":["excel","api_seller","manual"]},"token_sealed":{"type":"string"}},"required":["partner_id","platform","shop_id","mode"],"example":{"partner_id":"ptn_0f5k2m9q4h7t3n8r6v1w0x5yz0","platform":"shopee","shop_id":"shopee_88123456","shop_name":"Cửa hàng Minh Anh","mode":"excel"}},"UsageBreakdownItem":{"type":"object","properties":{"date":{"$ref":"#/components/schemas/Date"},"source":{"type":"string"},"company_id":{"type":"string"},"count":{"type":"integer","minimum":0}},"required":["count"],"description":"Phân tích sử dụng theo nhóm."},"UsageBreakdownResponse":{"type":"object","properties":{"period":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"total_count":{"type":"integer","minimum":0},"items":{"type":"array","items":{"$ref":"#/components/schemas/UsageBreakdownItem"}}},"required":["period","total_count","items"],"description":"Báo cáo phân tích lượng giao dịch sử dụng."},"UserId":{"type":"string","pattern":"^usr_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã người dùng (`usr_…`).","example":"usr_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"Vnd":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Số tiền VND, số nguyên đồng (không có phần thập phân).","example":4500000},"VoucherType":{"type":"string","enum":["BC","BN","PT","PC"],"description":"Loại chứng từ ngân hàng/tiền mặt: BC (Báo Có), BN (Báo Nợ), PT (Phiếu Thu), PC (Phiếu Chi)."},"WebhookCompanyScope":{"type":"string","enum":["all","selected"]},"WebhookDelivery":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/WebhookDeliveryId"},"endpoint_id":{"$ref":"#/components/schemas/WebhookEndpointId"},"event_id":{"$ref":"#/components/schemas/EventId"},"event_created_at":{"$ref":"#/components/schemas/Timestamp"},"attempt":{"type":"integer"},"state":{"$ref":"#/components/schemas/WebhookDeliveryState"},"http_status":{"type":["integer","null"]},"latency_ms":{"type":["integer","null"]},"next_retry_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"resp_snippet":{"type":["string","null"]},"created_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","endpoint_id","event_id","event_created_at","attempt","state","http_status","latency_ms","next_retry_at","resp_snippet","created_at"]},"WebhookDeliveryAttempt":{"type":"object","properties":{"n":{"type":"integer"},"at":{"$ref":"#/components/schemas/Timestamp"},"http_status":{"type":["integer","null"]},"latency_ms":{"type":["integer","null"]},"resp_snippet":{"type":["string","null"]},"error":{"type":["string","null"]}},"required":["n","at","http_status","latency_ms","resp_snippet","error"]},"WebhookDeliveryDetail":{"type":"object","properties":{"delivery":{"$ref":"#/components/schemas/WebhookDelivery"},"attempts":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDeliveryAttempt"}},"request_payload":{}},"required":["delivery","attempts"]},"WebhookDeliveryId":{"type":"string","pattern":"^whd_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã lần giao webhook (`whd_…`).","example":"whd_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"WebhookDeliveryList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}},"required":["object","data"]},"WebhookDeliveryState":{"type":"string","enum":["pending","delivering","succeeded","retry_wait","held","exhausted","dead_letter"]},"WebhookEgress":{"type":"string","enum":["edge","static_ip"]},"WebhookEndpoint":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/WebhookEndpointId"},"company_id":{"anyOf":[{"$ref":"#/components/schemas/OrgId"},{"type":"null"}]},"company_scope":{"$ref":"#/components/schemas/WebhookCompanyScope"},"url":{"type":"string","format":"uri","description":"Địa chỉ nhận webhook HTTPS."},"description":{"type":["string","null"]},"secret_masked":{"type":"string","description":"whsec_••••e91b"},"events":{"type":"array","items":{"type":"string"},"description":"Danh sách loại sự kiện đăng ký."},"api_version":{"type":"string","default":"2026-10-19"},"egress":{"$ref":"#/components/schemas/WebhookEgress"},"send_full_account":{"type":"boolean","description":"Gửi STK đầy đủ thay vì che 4 số cuối."},"memo_pattern_id":{"anyOf":[{"$ref":"#/components/schemas/MemoPatternId"},{"type":"null"}]},"memo_regex":{"type":["string","null"],"description":"RE2 regex lọc nội dung chuyển khoản."},"state":{"$ref":"#/components/schemas/WebhookEndpointState"},"consecutive_failures":{"type":"integer"},"held_count":{"type":"integer","description":"Số sự kiện đang chờ khi tạm ngưng."},"disabled_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"disabled_reason":{"type":["string","null"]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","company_id","company_scope","url","description","secret_masked","events","egress","send_full_account","memo_pattern_id","memo_regex","state","consecutive_failures","held_count","disabled_at","disabled_reason","created_at","updated_at","api_version"]},"WebhookEndpointId":{"type":"string","pattern":"^whe_[0-9a-hjkmnp-tv-z]{26}$","description":"Mã webhook endpoint (`whe_…`).","example":"whe_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"WebhookEndpointList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}},"required":["object","data"]},"WebhookEndpointResumeResponse":{"type":"object","properties":{"resumed":{"type":"boolean"},"flushed_count":{"type":"integer","description":"Số delivery đang chờ được đẩy lại vào hàng đợi."}},"required":["resumed","flushed_count"]},"WebhookEndpointRotateSecretResponse":{"type":"object","properties":{"secret":{"type":"string","description":"Khoá bí mật mới (whsec_...)."},"prev_valid_until":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Thời hạn khoá cũ còn hiệu lực (24 giờ).","example":"2026-10-19T01:30:15Z"}},"required":["secret","prev_valid_until"]},"WebhookEndpointState":{"type":"string","enum":["active","retrying","suspended","disabled"]},"WebhookEndpointTestResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"http_status":{"type":["integer","null"]},"latency_ms":{"type":["integer","null"]},"resp_snippet":{"type":["string","null"]}},"required":["ok","http_status","latency_ms","resp_snippet"]}},"parameters":{"DongTienVersion":{"name":"DongTien-Version","in":"header","required":false,"description":"Phiên bản API (`YYYY-MM-DD`). Bỏ trống: dùng phiên bản ghim theo khoá.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-10-19"}}},"headers":{"CacheControl":{"schema":{"type":"string","enum":["no-store"]},"required":true},"ContentDisposition":{"schema":{"type":"string","description":"`attachment; filename=\"audit-events.csv\"`"},"required":true,"description":"`attachment; filename=\"audit-events.csv\"`"},"DongTienVersion":{"schema":{"type":"string","description":"Phiên bản API đã áp dụng (`YYYY-MM-DD`)."},"required":true,"description":"Phiên bản API đã áp dụng (`YYYY-MM-DD`)."},"ETag":{"schema":{"type":"string"},"required":true},"IdempotencyReplayed":{"schema":{"type":"string","description":"`true` khi đây là kết quả phát lại của yêu cầu trước cùng `Idempotency-Key`."},"required":false,"description":"`true` khi đây là kết quả phát lại của yêu cầu trước cùng `Idempotency-Key`."},"Location":{"schema":{"type":"string","description":"`/v1/statements/{id}`."},"required":true,"description":"`/v1/statements/{id}`."},"RetryAfter":{"schema":{"type":"string","description":"Số giây nên chờ trước khi gửi lại."},"required":true,"description":"Số giây nên chờ trước khi gửi lại."},"XRateLimitLimit":{"schema":{"type":"string","description":"Hạn mức của nhóm route trong cửa sổ hiện tại."},"required":true,"description":"Hạn mức của nhóm route trong cửa sổ hiện tại."},"XRateLimitRemaining":{"schema":{"type":"string","description":"Số lần gọi còn lại."},"required":true,"description":"Số lần gọi còn lại."},"XRateLimitReset":{"schema":{"type":"string","description":"Thời điểm (epoch giây) cửa sổ được đặt lại."},"required":true,"description":"Thời điểm (epoch giây) cửa sổ được đặt lại."},"XRequestId":{"schema":{"type":"string","description":"Mã yêu cầu `req_…`; gửi kèm khi liên hệ hỗ trợ."},"required":true,"description":"Mã yêu cầu `req_…`; gửi kèm khi liên hệ hỗ trợ."}}},"paths":{"/v1/bank-accounts":{"get":{"operationId":"listBankAccounts","summary":"Danh sách tài khoản ngân hàng","description":"Trả các tài khoản trong phạm vi của thông tin xác thực, phân trang theo con trỏ. `company_id` giới hạn một công ty.","tags":["Tài khoản ngân hàng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"account.read","x-dt-scope":"accounts:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"type":"string","enum":["active","stopped_receiving","archived"]},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":16,"description":"Lọc theo mã ngân hàng."},"required":false,"description":"Lọc theo mã ngân hàng.","name":"bank_code","in":"query"},{"schema":{"type":"string","pattern":"^[a-z][a-z_]*(,[a-z][a-z_]*)*$","description":"Mở rộng một cấp, phân cách bằng dấu phẩy. Giá trị: `balance`."},"required":false,"description":"Mở rộng một cấp, phân cách bằng dấu phẩy. Giá trị: `balance`.","name":"expand","in":"query"}],"responses":{"200":{"description":"Danh sách tài khoản.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankAccountList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createBankAccount","summary":"Thêm tài khoản ngân hàng","description":"Bắt buộc `Idempotency-Key`. Cùng ngân hàng + số tài khoản đã có trong tổ chức trả `409 conflict`.","tags":["Tài khoản ngân hàng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"account.create","x-dt-idempotent":"required","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ. Bắt buộc ở máy chủ (thiếu → 400 idempotency_key_required); SDK tự sinh."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ. Bắt buộc ở máy chủ (thiếu → 400 idempotency_key_required); SDK tự sinh.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBankAccount"}}}},"responses":{"201":{"description":"Đã tạo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankAccount"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `idempotency_key_required` — Thiếu header Idempotency-Key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/bank-accounts/{id}":{"get":{"operationId":"getBankAccount","summary":"Chi tiết tài khoản ngân hàng","tags":["Tài khoản ngân hàng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"account.read","x-dt-scope":"accounts:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AccountId"},"required":true,"description":"Mã tài khoản ngân hàng (`acc_…`).","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^[a-z][a-z_]*(,[a-z][a-z_]*)*$","description":"Mở rộng một cấp, phân cách bằng dấu phẩy. Giá trị: `balance`."},"required":false,"description":"Mở rộng một cấp, phân cách bằng dấu phẩy. Giá trị: `balance`.","name":"expand","in":"query"}],"responses":{"200":{"description":"Tài khoản.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankAccount"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"updateBankAccount","summary":"Cập nhật tài khoản ngân hàng","description":"Không đổi được số tài khoản; muốn đổi hãy thêm tài khoản mới và lưu trữ tài khoản cũ.","tags":["Tài khoản ngân hàng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"account.update","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AccountId"},"required":true,"description":"Mã tài khoản ngân hàng (`acc_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBankAccount"}}}},"responses":{"200":{"description":"Tài khoản sau cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankAccount"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/bank-accounts/{id}:archive":{"post":{"operationId":"archiveBankAccount","summary":"Lưu trữ tài khoản ngân hàng","description":"Ngừng nhận giao dịch mới; lịch sử giữ nguyên. Đã lưu trữ rồi trả `409 conflict`.","tags":["Tài khoản ngân hàng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"account.archive","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AccountId"},"required":true,"description":"Mã tài khoản ngân hàng (`acc_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Tài khoản đã lưu trữ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankAccount"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/bank-accounts/{id}:reveal":{"post":{"operationId":"revealBankAccount","summary":"Xem số tài khoản đầy đủ","description":"Cần xác thực lại gần đây (passkey/TOTP ≤ 15 phút) và được ghi nhật ký kiểm toán mức nhạy cảm. Kết quả không bao giờ được lưu lại cho `Idempotency-Key`; phản hồi có `Cache-Control: no-store`.","tags":["Tài khoản ngân hàng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"account.reveal","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AccountId"},"required":true,"description":"Mã tài khoản ngân hàng (`acc_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Số tài khoản đầy đủ, hết hạn sau 5 phút.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevealedAccountNumber"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/bank-accounts/{id}/balance":{"get":{"operationId":"getBankAccountBalance","summary":"Số dư của một tài khoản","tags":["Số dư"],"security":[{"bearerAuth":[]}],"x-dt-permission":"account.read","x-dt-scope":"balances:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AccountId"},"required":true,"description":"Mã tài khoản ngân hàng (`acc_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Số dư.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/balances":{"get":{"operationId":"listBalances","summary":"Số dư của các tài khoản","description":"Số dư từng tài khoản trong phạm vi, phân trang theo con trỏ.","tags":["Số dư"],"security":[{"bearerAuth":[]}],"x-dt-permission":"account.read","x-dt-scope":"balances:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Danh sách số dư.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/transactions":{"get":{"operationId":"listTransactions","summary":"Danh sách giao dịch","description":"Mới nhất trước. Mặc định không gồm giao dịch cách ly và giao dịch đã gộp. Để biết tiền đã về hãy dùng `status=confirmed` hoặc lắng nghe sự kiện `transaction.confirmed`.","tags":["Giao dịch"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.read","x-dt-scope":"transactions:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"$ref":"#/components/schemas/TransactionStatus"},"required":false,"description":"`confirmed`: đã xác thực bởi nguồn đáng tin (tiền về). `provisional`: tạm tính, chưa đủ bằng chứng — không coi là tiền về.","name":"status","in":"query"},{"schema":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"$ref":"#/components/schemas/Date"}],"description":"Từ thời điểm (gồm) theo `occurred_at`."},"required":false,"description":"Từ thời điểm (gồm) theo `occurred_at`.","name":"since","in":"query"},{"schema":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"$ref":"#/components/schemas/Date"}],"description":"Đến thời điểm (không gồm) theo `occurred_at`."},"required":false,"description":"Đến thời điểm (không gồm) theo `occurred_at`.","name":"until","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"$ref":"#/components/schemas/AccountId"},"required":false,"description":"Mã tài khoản ngân hàng (`acc_…`).","name":"account_id","in":"query"},{"schema":{"type":"string","enum":["in","out"]},"required":false,"name":"direction","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Mã nội dung chuyển khoản `DTP…` (khớp chính xác, không phân biệt hoa/thường)."},"required":false,"description":"Mã nội dung chuyển khoản `DTP…` (khớp chính xác, không phân biệt hoa/thường).","name":"memo","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Tìm trong nội dung/đối tác, không phân biệt dấu."},"required":false,"description":"Tìm trong nội dung/đối tác, không phân biệt dấu.","name":"q","in":"query"},{"schema":{"type":"string","description":"Gồm giao dịch bị cách ly (mặc định không).","enum":["true","false"],"default":"false"},"required":false,"description":"Gồm giao dịch bị cách ly (mặc định không).","name":"include_quarantined","in":"query"},{"schema":{"type":"string","description":"Gồm giao dịch đã bị gộp vào giao dịch khác (mặc định không).","enum":["true","false"],"default":"false"},"required":false,"description":"Gồm giao dịch đã bị gộp vào giao dịch khác (mặc định không).","name":"include_merged","in":"query"},{"schema":{"$ref":"#/components/schemas/TransactionListPreset"},"required":false,"description":"Bộ lọc nhanh: `all` Tất cả · `needs_action` Cần xử lý (tạm tính >24 giờ hoặc đã xác thực nhưng chưa đối soát) · `in_today` Vào hôm nay (tiền vào từ 00:00 giờ Việt Nam) · `provisional_24h` Tạm tính >24 giờ · `unreconciled` Chưa đối soát · `quarantined` Cách ly (liệt kê cả giao dịch cách ly dù mặc định bị ẩn).","name":"preset","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{2,20}$","description":"Mã ngân hàng (`ACB`, `VCB`…), không phân biệt hoa/thường."},"required":false,"description":"Mã ngân hàng (`ACB`, `VCB`…), không phân biệt hoa/thường.","name":"bank","in":"query"},{"schema":{"type":"string","enum":["android","ios","email","openapi","statement","import"],"description":"Chỉ giao dịch có ít nhất một nguồn đến từ kênh này."},"required":false,"description":"Chỉ giao dịch có ít nhất một nguồn đến từ kênh này.","name":"source","in":"query"},{"schema":{"type":"string","enum":["provisional","verified"],"description":"Mức xác thực: `provisional` tạm tính, `verified` đã xác thực. Không dùng cùng `status` khác nghĩa."},"required":false,"description":"Mức xác thực: `provisional` tạm tính, `verified` đã xác thực. Không dùng cùng `status` khác nghĩa.","name":"verification","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":9007199254740991,"description":"Số tiền tối thiểu (gồm), VND."},"required":false,"description":"Số tiền tối thiểu (gồm), VND.","name":"amount_min","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":9007199254740991,"description":"Số tiền tối đa (gồm), VND; phải ≥ `amount_min`."},"required":false,"description":"Số tiền tối đa (gồm), VND; phải ≥ `amount_min`.","name":"amount_max","in":"query"},{"schema":{"$ref":"#/components/schemas/TransactionListSort"},"required":false,"description":"Thứ tự danh sách (mặc định `occurred_at_desc`, mới nhất trước). Con trỏ gắn với thứ tự: dùng con trỏ của thứ tự khác trả `400 invalid_cursor`.","name":"sort","in":"query"}],"responses":{"200":{"description":"Danh sách giao dịch.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/transactions/sync":{"get":{"operationId":"syncTransactions","summary":"Đồng bộ thay đổi giao dịch","description":"Đọc thay đổi theo con trỏ thay vì quét lại danh sách. Lần đầu bỏ `cursor` để bắt đầu từ đầu; sau đó luôn dùng `next_cursor` vừa nhận cho đến khi `has_more=false`. Tối đa 100 tài khoản trong phạm vi (nhiều hơn: lọc `account_id`, trả `422 too_many_accounts`).","tags":["Giao dịch"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.read","x-dt-scope":"transactions:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"type":"string","pattern":"^acc_[0-9a-hjkmnp-tv-z]{26}$","description":"Chỉ đồng bộ một tài khoản.","example":"acc_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"required":false,"description":"Chỉ đồng bộ một tài khoản.","name":"account_id","in":"query"}],"responses":{"200":{"description":"Trang thay đổi.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncPage"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/transactions/summary":{"get":{"operationId":"summarizeTransactions","summary":"Tổng hợp giao dịch","description":"Số lượng theo bộ lọc nhanh và tổng vào/ra (kèm phần còn tạm tính). Giao dịch cách ly và đã gộp không nằm trong tổng.","tags":["Giao dịch"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.read","x-dt-scope":"transactions:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"$ref":"#/components/schemas/Date"}],"description":"Mặc định: đầu ngày hôm nay (giờ Việt Nam)."},"required":false,"description":"Mặc định: đầu ngày hôm nay (giờ Việt Nam).","name":"from","in":"query"},{"schema":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"$ref":"#/components/schemas/Date"}],"description":"Mặc định: bây giờ."},"required":false,"description":"Mặc định: bây giờ.","name":"to","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"$ref":"#/components/schemas/AccountId"},"required":false,"description":"Mã tài khoản ngân hàng (`acc_…`).","name":"account_id","in":"query"},{"schema":{"type":"string","enum":["day","source","account"]},"required":false,"name":"group_by","in":"query"}],"responses":{"200":{"description":"Tổng hợp.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionSummary"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/transactions/stream":{"get":{"operationId":"streamTransactions","summary":"Luồng giao dịch thời gian thực (SSE)","description":"Server-Sent Events: `id:` là số thứ tự tăng dần theo tổ chức, `event:` là loại (`tx.created`, `tx.upgraded`, `tx.merged`, `tx.quarantined`, …), `data:` là `RealtimeEvent`. Gửi `Last-Event-ID` để nhận bù tối đa 5 phút; quá hạn nhận khung `event: resync` và nên gọi `/v1/transactions/sync`. Xác thực chỉ bằng vé một lần `?ticket=` (lấy từ `POST /v1/realtime/tickets`); cookie/Bearer không được chấp nhận ở máy chủ này.","tags":["Thời gian thực"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.read","x-dt-scope":"transactions:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"realtime","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","description":"Vé một lần từ `POST /v1/realtime/tickets` (bắt buộc; hiệu lực 60 giây)."},"required":true,"description":"Vé một lần từ `POST /v1/realtime/tickets` (bắt buộc; hiệu lực 60 giây).","name":"ticket","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","description":"Tương đương header `Last-Event-ID`."},"required":false,"description":"Tương đương header `Last-Event-ID`.","name":"last_event_id","in":"query"},{"schema":{"type":"string","description":"Danh sách kênh phân cách bằng dấu phẩy (tập con của vé)."},"required":false,"description":"Danh sách kênh phân cách bằng dấu phẩy (tập con của vé).","name":"topics","in":"query"}],"responses":{"200":{"description":"Luồng `text/event-stream`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"text/event-stream":{"schema":{"type":"string","description":"Khung SSE; mỗi `data:` là một `RealtimeEvent`."}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/transactions/{id}":{"get":{"operationId":"getTransaction","summary":"Chi tiết giao dịch","description":"Giao dịch đã gộp vẫn truy cập được bằng mã cũ và trả `merged_into`.","tags":["Giao dịch"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.read","x-dt-scope":"transactions:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/TxId"},"required":true,"description":"Mã giao dịch (`tx_…`), ổn định vĩnh viễn kể cả khi bị gộp.","name":"id","in":"path"}],"responses":{"200":{"description":"Giao dịch.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/transactions/{id}/sources":{"get":{"operationId":"listTransactionSources","summary":"Nguồn gốc của giao dịch","description":"Các nguồn đã báo giao dịch và mức tin cậy lúc nhận. Cần quyền xem dữ liệu gốc; mỗi lần xem được ghi nhật ký.","tags":["Giao dịch"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.read_raw","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/TxId"},"required":true,"description":"Mã giao dịch (`tx_…`), ổn định vĩnh viễn kể cả khi bị gộp.","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Các nguồn.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionSourceList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/transactions/{id}/events":{"get":{"operationId":"listTransactionEvents","summary":"Nhật ký của giao dịch","tags":["Giao dịch"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.read","x-dt-scope":"transactions:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/TxId"},"required":true,"description":"Mã giao dịch (`tx_…`), ổn định vĩnh viễn kể cả khi bị gộp.","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Nhật ký theo thời gian.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionEventList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/transactions/{id}:unmerge":{"post":{"operationId":"unmergeTransaction","summary":"Tách giao dịch đã gộp","description":"Giao dịch con (`merged_into` có giá trị) trở lại `active`; giao dịch chính giảm số nguồn. Ghi nhật ký kiểm toán; quota được tính lại bất đồng bộ. Giao dịch không phải bản gộp trả `409 conflict`.","tags":["Giao dịch"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.unmerge","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/TxId"},"required":true,"description":"Mã giao dịch (`tx_…`), ổn định vĩnh viễn kể cả khi bị gộp.","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnmergeTransaction"}}}},"responses":{"200":{"description":"Giao dịch sau khi tách.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/transactions/{id}:manual-verify":{"post":{"operationId":"manualVerifyTransaction","summary":"Đề nghị xác nhận thủ công","description":"Chỉ tạo yêu cầu duyệt (`tx_verify_manual`): giao dịch vẫn `provisional` cho tới khi người thứ hai (khác người đề nghị) duyệt bằng `:decide-manual-verify`. Cần `reason` và `evidence`. Đã có yêu cầu đang chờ trả `409 conflict`; giao dịch đã `verified`, cách ly hoặc đã gộp trả `409 conflict`.","tags":["Giao dịch"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.verify_manual.propose","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/TxId"},"required":true,"description":"Mã giao dịch (`tx_…`), ổn định vĩnh viễn kể cả khi bị gộp.","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManualVerifyTransaction"}}}},"responses":{"202":{"description":"Đã tạo yêu cầu duyệt.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionApprovalRef"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/transactions/{id}:decide-manual-verify":{"post":{"operationId":"decideManualVerifyTransaction","summary":"Duyệt hoặc từ chối xác nhận thủ công","description":"Người thứ hai quyết định yêu cầu đang chờ của giao dịch. Cùng người đề nghị trả `403 approver_same_as_maker`. Duyệt xong giao dịch thành `verified` với `verified_by=manual` và phát đúng một `transaction.confirmed`.","tags":["Giao dịch"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.verify_manual.approve","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/TxId"},"required":true,"description":"Mã giao dịch (`tx_…`), ổn định vĩnh viễn kể cả khi bị gộp.","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideManualVerify"}}}},"responses":{"200":{"description":"Giao dịch sau quyết định (vẫn `provisional` nếu từ chối).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/transactions/{id}:release-quarantine":{"post":{"operationId":"releaseQuarantinedTransaction","summary":"Gỡ cách ly giao dịch","description":"Bắt buộc `reason` và `evidence`; ghi nhật ký kiểm toán. Giao dịch trở lại `active` nhưng vẫn `provisional` (không bao giờ tự xác thực). Không ở trạng thái cách ly trả `409 conflict`.","tags":["Giao dịch"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.release_quarantine","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/TxId"},"required":true,"description":"Mã giao dịch (`tx_…`), ổn định vĩnh viễn kể cả khi bị gộp.","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuarantineDecision"}}}},"responses":{"200":{"description":"Giao dịch sau khi gỡ cách ly.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/transactions/{id}:reject-quarantine":{"post":{"operationId":"rejectQuarantinedTransaction","summary":"Loại bỏ giao dịch cách ly","description":"Bắt buộc `reason` và `evidence`; ghi nhật ký kiểm toán. Giao dịch chuyển `rejected` (cuối cùng, không tính vào số dư/quota/xuất). Không ở trạng thái cách ly trả `409 conflict`.","tags":["Giao dịch"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.release_quarantine","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/TxId"},"required":true,"description":"Mã giao dịch (`tx_…`), ổn định vĩnh viễn kể cả khi bị gộp.","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuarantineDecision"}}}},"responses":{"200":{"description":"Giao dịch sau khi loại bỏ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/transactions:bulk-note":{"post":{"operationId":"bulkNoteTransactions","summary":"Ghi chú / gắn thẻ hàng loạt","description":"Tối đa 100 giao dịch một lần. Chỉ là nhãn của người dùng, không tạo bút toán. Giao dịch ngoài phạm vi của người gọi báo `not_found` thay vì lỗi cả lô.","tags":["Giao dịch"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.annotate","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkNote"}}}},"responses":{"200":{"description":"Kết quả.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkNoteResult"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/transactions:export":{"post":{"operationId":"exportTransactions","summary":"Xuất giao dịch","description":"Trả `202` và mã tác vụ. Tối đa 50,000 dòng; ô bắt đầu bằng `= + - @` được trung hoà để không chạy thành công thức. Không tính quota; ghi nhật ký kiểm toán. Giao dịch cách ly chỉ xuất khi `include_quarantined=true`.","tags":["Giao dịch"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.read","x-dt-scope":"transactions:read","x-dt-idempotent":"optional","x-dt-rate-class":"export","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportTransactions"}}}},"responses":{"202":{"description":"Đã nhận lệnh xuất. Tác vụ `export.transactions` thường đã xong khi trả lời; `result.download_path` trỏ tới tệp (hết hạn sau 24 giờ).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/transaction-exports/{id}/file":{"get":{"operationId":"downloadTransactionExport","summary":"Tải tệp xuất giao dịch","description":"Chỉ người đã tạo lệnh xuất (hoặc cùng quyền xem trong công ty) tải được. Hết hạn sau 24 giờ trả `404`. Mỗi lần tải được ghi nhật ký kiểm toán.","tags":["Giao dịch"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.read","x-dt-scope":"transactions:read","x-dt-rate-class":"export","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/JobId"},"required":true,"description":"Mã tác vụ bất đồng bộ (`job_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Tệp CSV, JSON hoặc XLSX.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"text/csv":{"schema":{"type":"string"}},"application/json":{"schema":{"$ref":"#/components/schemas/TransactionExportFile"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/saved-views":{"get":{"operationId":"listSavedViews","summary":"Danh sách chế độ xem đã lưu","description":"Chế độ xem của chính người gọi cộng chế độ xem `company`/`firm` trong phạm vi được xem. Không phân trang (mỗi người tối đa 100 chế độ xem).","tags":["Chế độ xem"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/SavedViewVisibility"},"required":false,"description":"`me`: chỉ mình tôi. `company`: cả công ty (cần `company_id`). `firm`: cả tổ chức (cần quyền quản trị tổ chức).","name":"visibility","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"}],"responses":{"200":{"description":"Danh sách.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedViewList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createSavedView","summary":"Lưu chế độ xem","description":"`firm` cần quyền `tenant.manage`; `company` cần `company_id` thuộc phạm vi. Mỗi người tối đa 100 chế độ xem (vượt → `409 conflict`); trùng tên trong cùng phạm vi trả `409 conflict`.","tags":["Chế độ xem"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.read","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSavedView"}}}},"responses":{"201":{"description":"Đã lưu.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedView"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/saved-views/{id}":{"patch":{"operationId":"updateSavedView","summary":"Cập nhật chế độ xem","description":"Chỉ chủ chế độ xem sửa được; người khác thấy `404`. Đổi sang/từ `firm` cần `tenant.manage`.","tags":["Chế độ xem"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.read","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/SavedViewId"},"required":true,"description":"Mã chế độ xem đã lưu (`svw_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSavedView"}}}},"responses":{"200":{"description":"Sau cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedView"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteSavedView","summary":"Xoá chế độ xem","description":"Chỉ chủ chế độ xem xoá được. Chỉ xoá bộ lọc đã lưu, không xoá giao dịch.","tags":["Chế độ xem"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.read","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/SavedViewId"},"required":true,"description":"Mã chế độ xem đã lưu (`svw_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"204":{"description":"Đã xoá.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/dashboard/summary":{"get":{"operationId":"getDashboardSummary","summary":"Tổng quan bảng điều khiển","description":"Số dư báo cáo, tiền vào/ra (kèm phần tạm tính), bộ đếm việc cần xử lý. Giao dịch cách ly và đã gộp không nằm trong tổng. Quota và dòng tiền do các route riêng trả.","tags":["Bảng điều khiển"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.read","x-dt-scope":"transactions:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","enum":["today","7d","30d","month"],"default":"today"},"required":false,"name":"period","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"}],"responses":{"200":{"description":"Tổng quan.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardSummary"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/realtime/tickets":{"post":{"operationId":"createRealtimeTicket","summary":"Cấp vé thời gian thực","description":"Vé chỉ mở được một kết nối trong 60 giây và mang đúng phạm vi công/tài khoản của người gọi (khoá API giới hạn tài khoản vẫn bị giới hạn). Yêu cầu kênh ngoài phạm vi trả `404`.","tags":["Thời gian thực"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.read","x-dt-scope":"transactions:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealtimeTicketRequest"}}}},"responses":{"201":{"description":"Vé.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealtimeTicket"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/realtime/ws":{"get":{"operationId":"openRealtimeSocket","summary":"Mở WebSocket thời gian thực","description":"Nâng cấp lên WebSocket (`101`). Vé bắt buộc (`?ticket=`), dùng một lần. Máy chủ gửi khung JSON `RealtimeEvent`; ping/pong tự động. Từ chối trước khi nâng cấp: `401` vé sai/hết hạn/đã dùng, `403` kênh ngoài vé, `429` quá 5 kết nối.","tags":["Thời gian thực"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tx.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"realtime","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","description":"Vé một lần từ `POST /v1/realtime/tickets` (bắt buộc; hiệu lực 60 giây)."},"required":true,"description":"Vé một lần từ `POST /v1/realtime/tickets` (bắt buộc; hiệu lực 60 giây).","name":"ticket","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","description":"Tương đương header `Last-Event-ID`."},"required":false,"description":"Tương đương header `Last-Event-ID`.","name":"last_event_id","in":"query"},{"schema":{"type":"string","description":"Danh sách kênh phân cách bằng dấu phẩy (tập con của vé)."},"required":false,"description":"Danh sách kênh phân cách bằng dấu phẩy (tập con của vé).","name":"topics","in":"query"}],"responses":{"101":{"description":"Đã chuyển sang WebSocket."},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/devices/pairing-codes":{"post":{"operationId":"createDevicePairingCode","summary":"Tạo mã ghép thiết bị Android","description":"Mã `PAIR-XXXX-XXXX` (Crockford 40 bit) hiệu lực 5 phút, dùng một lần; máy sai mã 5 lần thì mã bị khoá. Tạo mã mới vô hiệu mọi mã chưa dùng cùng (tổ chức, loại). Mã chỉ lưu dạng băm HMAC nên không xem lại được. Không dùng `Idempotency-Key` (kết quả là bí mật).","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.manage","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDevicePairingCode"}}}},"responses":{"201":{"description":"Mã ghép mới.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevicePairingCode"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/devices":{"get":{"operationId":"listDevices","summary":"Danh sách thiết bị","description":"Thiết bị trong phạm vi của thông tin xác thực. Heartbeat sống ở Durable Object, Postgres chỉ rollup mỗi 60 s nên `last_seen_at` có thể trễ tới 1 phút.","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"$ref":"#/components/schemas/DeviceKind"},"required":false,"name":"kind","in":"query"},{"schema":{"$ref":"#/components/schemas/DeviceState"},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":80,"description":"Tìm theo tên/model thiết bị."},"required":false,"description":"Tìm theo tên/model thiết bị.","name":"q","in":"query"},{"schema":{"type":["boolean","null"],"default":false},"required":false,"name":"include_revoked","in":"query"}],"responses":{"200":{"description":"Danh sách.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createIosDevice","summary":"Tạo thiết bị iPhone (Shortcuts)","description":"Tạo thiết bị ở trạng thái `pending_pair` (hết hạn sau 24 giờ nếu chưa nhận được tin nào) và trả token `dtd_…` MỘT LẦN. Không dùng `Idempotency-Key` (kết quả là bí mật). Ghi nhật ký kiểm toán `device.create`.","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.manage","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIosDevice"}}}},"responses":{"201":{"description":"Đã tạo; có token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IosDeviceCredential"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/devices/{id}":{"get":{"operationId":"getDevice","summary":"Chi tiết thiết bị","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/DeviceId"},"required":true,"description":"Mã thiết bị chuyển tiếp tin (`dev_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Thiết bị.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Device"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"updateDevice","summary":"Cập nhật thiết bị","description":"Đổi tên, người phụ trách, tài khoản phụ trách hoặc tắt bớt nguồn. Đổi nguồn tăng `config_version`; máy nhận cấu hình mới ở heartbeat kế tiếp.","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/DeviceId"},"required":true,"description":"Mã thiết bị chuyển tiếp tin (`dev_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDevice"}}}},"responses":{"200":{"description":"Sau cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Device"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteDevice","summary":"Gỡ thiết bị","description":"Thu hồi ngay: request kế tiếp của máy nhận `401 device_revoked` (≤ 5 giây); tin còn trong hàng đợi của máy sẽ không được nhận. Ghi nhật ký kiểm toán `device.revoke`. Gỡ lại thiết bị đã gỡ trả `409 conflict`.","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/DeviceId"},"required":true,"description":"Mã thiết bị chuyển tiếp tin (`dev_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Thiết bị sau khi gỡ (`state = revoked`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Device"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/devices/{id}:ping":{"post":{"operationId":"pingDevice","summary":"Gửi lệnh kiểm tra tới thiết bị","description":"Xếp lệnh `ping`/`diagnose`/`test_send` vào hàng của máy; máy nhận ở heartbeat kế tiếp. Không dùng FCM. Thiết bị iOS trả `409 conflict` (Shortcuts không nhận lệnh). Ghi nhật ký kiểm toán `device.command`.","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/DeviceId"},"required":true,"description":"Mã thiết bị chuyển tiếp tin (`dev_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PingDevice"}}}},"responses":{"202":{"description":"Lệnh đã xếp hàng.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceCommand"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/devices/{id}:nudge":{"post":{"operationId":"nudgeDevice","summary":"Nhắc người phụ trách thiết bị","description":"Gửi nhắc tới người phụ trách (kênh thông báo của phase 18). Tối đa 1 lần mỗi 6 giờ cho mỗi thiết bị; quá hạn mức trả `429 rate_limited`.","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/DeviceId"},"required":true,"description":"Mã thiết bị chuyển tiếp tin (`dev_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Đã nhắc.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceNudge"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/devices/{id}/queue":{"get":{"operationId":"getDeviceQueue","summary":"Hàng đợi tin chờ gửi trên thiết bị","description":"Đọc ảnh chụp 20 mục đầu của hàng đợi, nội dung rút gọn 80 ký tự và che số tài khoản. Chưa có ảnh chụp mới thì xếp lệnh `upload_queue_preview` (trả `state: requested`, hỏi lại sau ≤ 45 giây). Ảnh chụp hết hạn sau 15 phút. Mỗi lần đọc ghi nhật ký kiểm toán `device.queue_read`.","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.read_queue","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/DeviceId"},"required":true,"description":"Mã thiết bị chuyển tiếp tin (`dev_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Hàng đợi.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceQueue"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/devices/{id}/events":{"get":{"operationId":"listDeviceEvents","summary":"Nhật ký thiết bị","description":"Nhật ký chỉ-thêm của thiết bị (mới nhất trước), phân trang theo con trỏ.","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/DeviceId"},"required":true,"description":"Mã thiết bị chuyển tiếp tin (`dev_…`).","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"type":"string","maxLength":40},"required":false,"name":"kind","in":"query"}],"responses":{"200":{"description":"Nhật ký.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceEventList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/devices/{id}:rotate-token":{"post":{"operationId":"rotateIosDeviceToken","summary":"Xoay token iPhone","description":"Tạo token mới; token cũ còn hiệu lực 30 phút để cập nhật Shortcut rồi trả `401`. Thiết bị, bộ đếm và cảnh báo im lặng giữ nguyên (cùng `device_id`). KHÔNG khôi phục độ tin cậy đã bị hạ (D42): dùng `:restore-trust`. Chỉ thiết bị iOS; Android trả `409 conflict`. Ghi nhật ký kiểm toán `device.token_rotate`. Không dùng `Idempotency-Key`.","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.manage","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/DeviceId"},"required":true,"description":"Mã thiết bị chuyển tiếp tin (`dev_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Token mới.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IosDeviceCredential"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/devices/{id}:restore-trust":{"post":{"operationId":"restoreIosDeviceTrust","summary":"Xoay token và tin cậy lại iPhone","description":"Cần xác thực lại (step-up). Xoay token (như `:rotate-token`) và xoá việc hạ tin cậy D42; giao dịch mới của máy lại có thể `verified` nếu đủ điều kiện. Giao dịch đã ghi không đổi. Ghi nhật ký kiểm toán `device.token_rotate` với `trust_restored: true`.","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.manage","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/DeviceId"},"required":true,"description":"Mã thiết bị chuyển tiếp tin (`dev_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Token mới; `device.trust_downgraded_at` là `null`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IosDeviceCredential"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/banks/ios-keywords":{"get":{"operationId":"listIosBankKeywords","summary":"Từ khoá automation iPhone theo ngân hàng","description":"Danh mục chung (không theo công ty): từ khoá mà tin biến động số dư của từng ngân hàng luôn chứa, dùng cho bước \"Tạo automation\". Từ khoá chỉ để bắt tin, không tham gia xác thực nguồn.","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IosBankKeywordList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/devices/{id}/banks":{"get":{"operationId":"listDeviceBanks","summary":"Automation theo ngân hàng của iPhone","description":"Các ngân hàng của tài khoản máy phụ trách (và ngân hàng đã có thống kê), kèm từ khoá, trạng thái và bộ đếm hôm nay; cùng công tắc `ios_trust_enabled` từng tài khoản. Bộ đếm sống ở Durable Object và được rollup tối đa mỗi 60 giây. Thiết bị Android trả `409 conflict`.","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/DeviceId"},"required":true,"description":"Mã thiết bị chuyển tiếp tin (`dev_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Danh sách.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceBankList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/devices/{id}/banks/{bank_code}":{"patch":{"operationId":"patchDeviceBank","summary":"Đánh dấu đã tạo automation cho ngân hàng","description":"Chỉ ghi nhận lựa chọn của người dùng (\"Đã tạo\"), để hiện `untested` cho tới khi có tin. Không bật/tắt việc nhận tin: bỏ automation là việc trong app Shortcuts.","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/DeviceId"},"required":true,"description":"Mã thiết bị chuyển tiếp tin (`dev_…`).","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^[A-Z0-9]{2,12}$"},"required":true,"name":"bank_code","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchDeviceBank"}}}},"responses":{"200":{"description":"Sau cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceBankStatus"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/devices/{id}/accounts/{account_id}":{"patch":{"operationId":"patchDeviceIosAccount","summary":"Bật/tắt \"Tính giao dịch iOS là đã xác thực\" cho một tài khoản","description":"Tắt: giao dịch iOS của tài khoản này luôn `provisional` (đã `verified` thì giữ nguyên). Nếu máy đang phụ trách mọi tài khoản của công ty, lần đổi đầu tiên ghim máy vào danh sách tài khoản hiện có.","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/DeviceId"},"required":true,"description":"Mã thiết bị chuyển tiếp tin (`dev_…`).","name":"id","in":"path"},{"schema":{"$ref":"#/components/schemas/AccountId"},"required":true,"description":"Mã tài khoản ngân hàng (`acc_…`).","name":"account_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchDeviceIosAccount"}}}},"responses":{"200":{"description":"Sau cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceIosAccount"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/devices/{id}/test-sms":{"post":{"operationId":"testIosDeviceSms","summary":"Gửi tin thử qua iPhone","description":"Mở lần thử 90 giây. Người dùng chuyển khoản số tiền nhỏ với nội dung `TEST DTP…` tới tài khoản của mình; khi SMS ngân hàng tới Shortcut, máy chủ khớp mã trong tin và trả kết quả (kênh `GET …/test-stream`). Lần thử không tạo giao dịch riêng: tin vẫn đi qua đường nhập thường (tạm tính). Thiết bị Android trả `409 conflict`.","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/DeviceId"},"required":true,"description":"Mã thiết bị chuyển tiếp tin (`dev_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"201":{"description":"Lần thử đã mở.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IosSmsTest"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/devices/{id}/test-stream":{"get":{"operationId":"streamIosDeviceSmsTest","summary":"Theo dõi lần gửi thử (SSE)","description":"`text/event-stream`: sự kiện `channel_test` (JSON `IosSmsTest`) mỗi khi trạng thái đổi, `ping` mỗi 15 giây, rồi đóng khi `received` / `expired` hoặc sau 90 giây. Chọn lần thử bằng `?test=cht_…` (mặc định lần mới nhất của máy).","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/DeviceId"},"required":true,"description":"Mã thiết bị chuyển tiếp tin (`dev_…`).","name":"id","in":"path"},{"schema":{"$ref":"#/components/schemas/ChannelTestId"},"required":false,"description":"Mã lần gửi thử kênh (`cht_…`).","name":"test","in":"query"}],"responses":{"200":{"description":"Luồng SSE.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/app/ios-shortcut/latest":{"get":{"operationId":"getIosShortcutLatest","summary":"Bản Shortcut iPhone mới nhất","description":"Công khai. Chỉ trả bản `staged`/`stable`/`mandatory` mới nhất; chưa có bản nào → `404 resource_not_found`. Liên kết iCloud do quy trình phát hành (ký trên macOS) đặt.","tags":["Thiết bị"],"security":[],"x-dt-permission":"public","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Manifest.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IosShortcutRelease"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/accounts/{id}/recommendations":{"get":{"operationId":"listAccountRecommendations","summary":"Gợi ý tăng độ phủ cho tài khoản","description":"Dựa trên các kênh đang nhận tin của tài khoản. Tài khoản chỉ có iPhone Shortcut (tin tạm tính, không có chữ ký thiết bị) → gợi ý chuyển tiếp email và sao kê hằng ngày; automation `parse_error` → gợi ý sửa từ khoá. Chỉ gợi ý, không đổi dữ liệu.","tags":["Tài khoản ngân hàng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"account.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AccountId"},"required":true,"description":"Mã tài khoản ngân hàng (`acc_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Danh sách.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CoverageRecommendationList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/device-alert-rules":{"get":{"operationId":"getDeviceAlertRules","summary":"Quy tắc cảnh báo thiết bị","description":"Chưa lưu thì trả mặc định (`updated_at = null`).","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"device.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"}],"responses":{"200":{"description":"Quy tắc.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceAlertRules"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"operationId":"putDeviceAlertRules","summary":"Lưu quy tắc cảnh báo thiết bị","description":"Thay toàn bộ quy tắc của công ty (`company_id` trong thân).","tags":["Thiết bị"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.org_rule.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PutDeviceAlertRules"}}}},"responses":{"200":{"description":"Quy tắc sau khi lưu.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceAlertRules"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/app/android/latest":{"get":{"operationId":"getAndroidLatest","summary":"Bản app Android mới nhất","description":"Công khai, không cần xác thực. Chỉ trả bản đang `staged`/`stable`/`mandatory`; bản `halted` bị bỏ qua (trả bản ổn định trước đó). Máy chỉ cài khi qua cổng rollout theo băm `device_id` và chữ ký Ed25519 hợp lệ. Chưa có bản nào → `404 resource_not_found`.","tags":["Thiết bị"],"security":[],"x-dt-permission":"public","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","enum":["stable","beta"],"default":"stable"},"required":false,"name":"channel","in":"query"}],"responses":{"200":{"description":"Manifest.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AndroidReleaseManifest"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/payment-requests":{"get":{"operationId":"listPaymentRequests","summary":"Danh sách yêu cầu thanh toán","description":"Mới nhất trước. `view=attention` gồm yêu cầu `provisional`, `short`, `over` chưa xử lý và `expired` có tiền về muộn.","tags":["Thu tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payment_request.read","x-dt-scope":"collect:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"type":"string","enum":["waiting","provisional","short","paid","over","expired","cancelled"]},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","enum":["all","waiting","received","attention"],"default":"all"},"required":false,"name":"view","in":"query"},{"schema":{"$ref":"#/components/schemas/StoreId"},"required":false,"description":"Mã cửa hàng (`sto_…`).","name":"store_id","in":"query"},{"schema":{"$ref":"#/components/schemas/CounterId"},"required":false,"description":"Mã quầy thu ngân (`ctr_…`).","name":"counter_id","in":"query"},{"schema":{"$ref":"#/components/schemas/AccountId"},"required":false,"description":"Mã tài khoản ngân hàng (`acc_…`).","name":"account_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Tìm theo mã `DTP…`, `ref` hoặc tên khách."},"required":false,"description":"Tìm theo mã `DTP…`, `ref` hoặc tên khách.","name":"q","in":"query"},{"schema":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"$ref":"#/components/schemas/Date"}],"description":"Tạo từ thời điểm này (giờ Việt Nam nếu là ngày)."},"required":false,"description":"Tạo từ thời điểm này (giờ Việt Nam nếu là ngày).","name":"from","in":"query"},{"schema":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"$ref":"#/components/schemas/Date"}]},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"Danh sách yêu cầu.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequestList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createPaymentRequest","summary":"Tạo yêu cầu thanh toán","description":"Sinh mã `DTP…`, dựng VietQR (số tiền khoá khi có `amount`) và trang `pay_url`. Cần `Idempotency-Key`. Tài khoản chưa có kênh xác thực được trả `warnings: [\"ACCOUNT_PROVISIONAL_ONLY\"]`: tiền về sẽ ở trạng thái tạm tính và yêu cầu không tự chuyển `paid` (D36). Không giữ tiền.","tags":["Thu tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payment_request.create","x-dt-scope":"collect:write","x-dt-idempotent":"required","x-dt-rate-class":"collect","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ. Bắt buộc ở máy chủ (thiếu → 400 idempotency_key_required); SDK tự sinh."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ. Bắt buộc ở máy chủ (thiếu → 400 idempotency_key_required); SDK tự sinh.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentRequest"}}}},"responses":{"201":{"description":"Yêu cầu đã tạo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `idempotency_key_required` — Thiếu header Idempotency-Key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/payment-requests/{id}":{"get":{"operationId":"getPaymentRequest","summary":"Chi tiết yêu cầu thanh toán","description":"Tra theo `pr_…` hoặc mã nội dung `DTP…`.","tags":["Thu tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payment_request.read","x-dt-scope":"collect:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PaymentRequestRef"},"required":true,"description":"Mã yêu cầu `pr_…` hoặc mã nội dung `DTP…`.","name":"id","in":"path"}],"responses":{"200":{"description":"Yêu cầu.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"updatePaymentRequest","summary":"Sửa yêu cầu thanh toán","description":"Chỉ khi yêu cầu còn `waiting` và chưa có giao dịch nào gắn; mã `DTP…` và tài khoản không bao giờ đổi. Đổi số tiền sinh lại QR. Trái điều kiện trả `409 conflict`.","tags":["Thu tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payment_request.update","x-dt-scope":"collect:write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PaymentRequestRef"},"required":true,"description":"Mã yêu cầu `pr_…` hoặc mã nội dung `DTP…`.","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePaymentRequest"}}}},"responses":{"200":{"description":"Yêu cầu sau khi sửa.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/payment-requests/{id}:cancel":{"post":{"operationId":"cancelPaymentRequest","summary":"Huỷ yêu cầu thanh toán","description":"Chỉ khi còn `waiting`. Tiền chuyển sau khi huỷ không gắn vào yêu cầu: vào việc cần xử lý (`late_payment`). Phát `payment_request.cancelled`.","tags":["Thu tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payment_request.cancel","x-dt-scope":"collect:write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PaymentRequestRef"},"required":true,"description":"Mã yêu cầu `pr_…` hoặc mã nội dung `DTP…`.","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelPaymentRequest"}}}},"responses":{"200":{"description":"Yêu cầu đã huỷ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/payment-requests/{id}:remind":{"post":{"operationId":"remindPaymentRequest","summary":"Nhắc thanh toán","description":"Ghi dòng `reminded` vào nhật ký và đưa lời nhắc gửi tới `recipient` vào hàng đợi thông báo. Chỉ với yêu cầu `waiting`, `provisional` hoặc `short`.","tags":["Thu tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payment_request.remind","x-dt-scope":"collect:write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PaymentRequestRef"},"required":true,"description":"Mã yêu cầu `pr_…` hoặc mã nội dung `DTP…`.","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequestNotify"}}}},"responses":{"200":{"description":"Yêu cầu.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/payment-requests/{id}:resend-remainder":{"post":{"operationId":"resendPaymentRequestRemainder","summary":"Gửi phần còn lại","description":"Chỉ khi `short`. Giữ nguyên mã `DTP…`, đặt `locked_amount = amount − đã nhận (xác thực)` và sinh lại QR.","tags":["Thu tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payment_request.update","x-dt-scope":"collect:write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PaymentRequestRef"},"required":true,"description":"Mã yêu cầu `pr_…` hoặc mã nội dung `DTP…`.","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Yêu cầu với QR phần còn lại.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/payment-requests/{id}:resolve-overpay":{"post":{"operationId":"resolvePaymentRequestOverpay","summary":"Đánh dấu đã xử lý tiền thừa","description":"Chỉ khi `over`. Chỉ đánh dấu `overpay_resolved_at`: hệ thống không hoàn tiền (D2).","tags":["Thu tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payment_request.resolve_overpay","x-dt-scope":"collect:write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PaymentRequestRef"},"required":true,"description":"Mã yêu cầu `pr_…` hoặc mã nội dung `DTP…`.","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveOverpay"}}}},"responses":{"200":{"description":"Yêu cầu.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/payment-requests/{id}:receipt":{"post":{"operationId":"receiptPaymentRequest","summary":"Gửi biên nhận","description":"Chỉ khi `paid` hoặc `over`. Ghi dòng `receipt` vào nhật ký và đưa biên nhận gửi tới `recipient` vào hàng đợi thông báo (gửi lại cùng người nhận không tạo thêm tin).","tags":["Thu tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payment_request.remind","x-dt-scope":"collect:write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PaymentRequestRef"},"required":true,"description":"Mã yêu cầu `pr_…` hoặc mã nội dung `DTP…`.","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequestNotify"}}}},"responses":{"200":{"description":"Yêu cầu.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/payment-requests/{id}/transactions":{"get":{"operationId":"listPaymentRequestTransactions","summary":"Giao dịch đã khớp với yêu cầu","description":"Gồm cả giao dịch tạm tính (chưa tính vào `received_verified`).","tags":["Thu tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payment_request.read","x-dt-scope":"collect:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PaymentRequestRef"},"required":true,"description":"Mã yêu cầu `pr_…` hoặc mã nội dung `DTP…`.","name":"id","in":"path"}],"responses":{"200":{"description":"Giao dịch khớp.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequestTransactionList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/payment-requests/{id}/timeline":{"get":{"operationId":"listPaymentRequestTimeline","summary":"Nhật ký yêu cầu thanh toán","description":"Chỉ thêm, theo thời gian tăng dần.","tags":["Thu tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payment_request.read","x-dt-scope":"collect:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PaymentRequestRef"},"required":true,"description":"Mã yêu cầu `pr_…` hoặc mã nội dung `DTP…`.","name":"id","in":"path"}],"responses":{"200":{"description":"Các dòng nhật ký.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequestEventList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/collect/bills":{"post":{"operationId":"createCollectBill","summary":"Tạo bill và QR động cho POS","description":"Tra cửa hàng/quầy theo `slug`; ca đang mở của quầy nhận bill. Gửi lại cùng `bill_ref` và cùng nội dung trả lại bill cũ (`Idempotency-Replayed`); cùng `bill_ref` khác nội dung trả `422`. Cần `Idempotency-Key` (nên bằng `bill_ref`). Khi bill được trả đủ bằng tiền đã xác thực phát `collect.bill.paid`.","tags":["Thu tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"collect.bill.create","x-dt-scope":"collect:write","x-dt-idempotent":"required","x-dt-rate-class":"collect","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ. Bắt buộc ở máy chủ (thiếu → 400 idempotency_key_required); SDK tự sinh."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ. Bắt buộc ở máy chủ (thiếu → 400 idempotency_key_required); SDK tự sinh.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBill"}}}},"responses":{"201":{"description":"Bill và yêu cầu thanh toán (QR).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bill"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `idempotency_key_required` — Thiếu header Idempotency-Key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"get":{"operationId":"listCollectBills","summary":"Danh sách bill","description":"Mới nhất trước; lọc theo quầy hoặc ca.","tags":["Thu tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payment_request.read","x-dt-scope":"collect:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"$ref":"#/components/schemas/CounterId"},"required":false,"description":"Mã quầy thu ngân (`ctr_…`).","name":"counter","in":"query"},{"schema":{"type":"string","pattern":"^shf_[0-9a-hjkmnp-tv-z]{26}$"},"required":false,"name":"shift","in":"query"},{"schema":{"type":"string","enum":["waiting","paid","expired","cash_paid","cancelled"]},"required":false,"name":"state","in":"query"}],"responses":{"200":{"description":"Danh sách bill.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/collect/bills/{bill_ref}:cancel":{"post":{"operationId":"cancelCollectBill","summary":"Huỷ bill","description":"Bill đang `waiting` chuyển `cancelled` và yêu cầu thanh toán của nó cũng bị huỷ. Bill đã `paid`/`cash_paid` trả `409 conflict`. POS sửa số tiền: huỷ rồi tạo `bill_ref` mới.","tags":["Thu tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"collect.bill.create","x-dt-scope":"collect:write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"bill_ref","in":"path"},{"schema":{"type":"string","pattern":"^ctr_[0-9a-hjkmnp-tv-z]{26}$","description":"Quầy của bill (`bill_ref` chỉ duy nhất trong một quầy).","example":"ctr_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"required":true,"description":"Quầy của bill (`bill_ref` chỉ duy nhất trong một quầy).","name":"counter","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Bill sau khi huỷ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bill"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/collect/bills/{bill_ref}:mark-cash":{"post":{"operationId":"markCollectBillCash","summary":"Bill đã trả tiền mặt","description":"Bill `waiting` chuyển `cash_paid`; yêu cầu thanh toán bị huỷ với lý do `cash`. Tiền chuyển khoản đến sau đó vào việc cần xử lý.","tags":["Thu tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"collect.bill.create","x-dt-scope":"collect:write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"bill_ref","in":"path"},{"schema":{"type":"string","pattern":"^ctr_[0-9a-hjkmnp-tv-z]{26}$","description":"Quầy của bill (`bill_ref` chỉ duy nhất trong một quầy).","example":"ctr_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"required":true,"description":"Quầy của bill (`bill_ref` chỉ duy nhất trong một quầy).","name":"counter","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Bill sau khi đánh dấu.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bill"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/statements/preview":{"post":{"operationId":"previewStatement","summary":"Tải sao kê lên để xem trước","description":"Nhận tệp (`multipart/form-data`, tối đa 25 MB), kiểm tra nội dung bằng chữ ký tệp, niêm phong rồi lưu và chạy xem trước: nhận dạng bố cục, kiểm số dư đầu/cuối, chạy thử gộp trùng. Chưa ghi gì vào sổ. Trả `202` với tác vụ để theo dõi; khi `state=preview_ready` đọc `GET /v1/statements/{id}`. Cùng một tệp đã có trên tài khoản này: `200` kèm sao kê cũ, không tạo thêm. Tệp sai chữ ký: `422`; quá 25 MB: `413`.","tags":["Nhập sao kê"],"security":[{"bearerAuth":[]}],"x-dt-permission":"statement.import","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PreviewStatementForm"}}}},"responses":{"200":{"description":"Tệp này đã được tải lên trước đó cho tài khoản: trả sao kê cũ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementAccepted"}}}},"202":{"description":"Đã nhận tệp; đang nhận dạng và xem trước.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Location":{"$ref":"#/components/headers/Location"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementAccepted"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/statements":{"get":{"operationId":"listStatements","summary":"Danh sách sao kê đã tải","description":"Mới nhất trước. Lọc theo tài khoản và trạng thái.","tags":["Nhập sao kê"],"security":[{"bearerAuth":[]}],"x-dt-permission":"statement.import","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"$ref":"#/components/schemas/AccountId"},"required":false,"description":"Mã tài khoản ngân hàng (`acc_…`).","name":"bank_account_id","in":"query"},{"schema":{"$ref":"#/components/schemas/StatementImportState"},"required":false,"description":"`created` → `validating` → `preview_ready` → `committing` → `completed` | `completed_with_errors`; `failed`, `cancelled`. `halted_balance_mismatch`: số dư không khớp, không nhập được.","name":"state","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Danh sách.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementImportList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/statements/{id}":{"get":{"operationId":"getStatement","summary":"Chi tiết sao kê","description":"Trạng thái, tệp, kỳ, đếm, bản xem trước (kiểm số dư, đếm mới/khớp/trùng/lỗi, ánh xạ cột) và kết quả sau khi nhập (neo số dư, giao dịch tạm tính không có trong sao kê).","tags":["Nhập sao kê"],"security":[{"bearerAuth":[]}],"x-dt-permission":"statement.import","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/StatementImportId"},"required":true,"description":"Mã lần nhập sao kê (`imp_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Sao kê.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementImport"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/statements/{id}/rows":{"get":{"operationId":"listStatementRows","summary":"Dòng xem trước của sao kê","description":"Một trang 500 dòng của bản xem trước, theo thứ tự thời gian. `status` lọc các dòng trong trang. Chỉ có khi sao kê đã tới `preview_ready` (hoặc sau đó); trước đó trả `409 conflict`.","tags":["Nhập sao kê"],"security":[{"bearerAuth":[]}],"x-dt-permission":"statement.import","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/StatementImportId"},"required":true,"description":"Mã lần nhập sao kê (`imp_…`).","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100000,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"string","enum":["new","merged","skipped","error","locked"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Trang dòng.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementRowsPage"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/statements/{id}/errors":{"get":{"operationId":"getStatementErrors","summary":"Tải nhật ký dòng lỗi","description":"Văn bản thuần (`text/plain`) theo dạng NDJSON: mỗi dòng một JSON `{row_no, code}` của một dòng lỗi trong sao kê. `404` khi sao kê không có dòng lỗi.","tags":["Nhập sao kê"],"security":[{"bearerAuth":[]}],"x-dt-permission":"statement.import","x-dt-rate-class":"export","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/StatementImportId"},"required":true,"description":"Mã lần nhập sao kê (`imp_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Nhật ký lỗi, mỗi dòng một JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"text/plain":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/statements/{id}:commit":{"post":{"operationId":"commitStatement","summary":"Nhập sao kê vào sổ","description":"Chỉ khi `state=preview_ready`. Sao kê số dư lệch (`halted_balance_mismatch`) trả `409 balance_mismatch`: không có cách ép nhập, hãy sửa ánh xạ cột rồi chạy lại hoặc huỷ. Trạng thái khác trả `409 conflict`. Gọi lại khi đang nhập trả chính tác vụ đó.","tags":["Nhập sao kê"],"security":[{"bearerAuth":[]}],"x-dt-permission":"statement.import","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/StatementImportId"},"required":true,"description":"Mã lần nhập sao kê (`imp_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"202":{"description":"Đã nhận lệnh nhập.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementAccepted"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/statements/{id}:cancel":{"post":{"operationId":"cancelStatement","summary":"Huỷ sao kê chưa nhập","description":"Bỏ bản xem trước chưa nhập (`created`, `preview_ready` hoặc `halted_balance_mismatch`). Đang nhập hoặc đã xong trả `409 conflict`. Tệp cùng nội dung có thể tải lên lại sau khi huỷ.","tags":["Nhập sao kê"],"security":[{"bearerAuth":[]}],"x-dt-permission":"statement.import","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/StatementImportId"},"required":true,"description":"Mã lần nhập sao kê (`imp_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Sao kê đã huỷ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementImportSummary"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/statements/{id}:rerun":{"post":{"operationId":"rerunStatement","summary":"Chạy lại xem trước với ánh xạ khác","description":"Chỉ từ `preview_ready` hoặc `halted_balance_mismatch`. Đọc lại tệp đã lưu với ánh xạ mới (`mapping_id` hoặc `mapping`), tuỳ chọn lưu làm mẫu. Trả `202` với tác vụ xem trước mới.","tags":["Nhập sao kê"],"security":[{"bearerAuth":[]}],"x-dt-permission":"statement.import","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/StatementImportId"},"required":true,"description":"Mã lần nhập sao kê (`imp_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RerunStatement"}}}},"responses":{"202":{"description":"Đã nhận lệnh chạy lại.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementAccepted"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/statement-mappings":{"get":{"operationId":"listStatementMappings","summary":"Danh sách mẫu ánh xạ cột","description":"Mẫu mới cập nhật trước, tối đa 200. Lọc theo mã ngân hàng và/hoặc dấu vân tay tiêu đề.","tags":["Nhập sao kê"],"security":[{"bearerAuth":[]}],"x-dt-permission":"statement.import","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":16},"required":false,"name":"bank_code","in":"query"},{"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"},"required":false,"name":"header_fingerprint","in":"query"}],"responses":{"200":{"description":"Danh sách.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementMappingList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"operationId":"putStatementMapping","summary":"Lưu mẫu ánh xạ cột","description":"Mỗi (ngân hàng, dấu vân tay tiêu đề) chỉ có một mẫu: lưu lại cùng khoá thì thay thế mẫu cũ (`200` cả khi tạo mới). Cần có cột ngày và cột số tiền (hoặc cả ghi nợ lẫn ghi có).","tags":["Nhập sao kê"],"security":[{"bearerAuth":[]}],"x-dt-permission":"statement.import","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PutStatementMapping"}}}},"responses":{"200":{"description":"Mẫu đã lưu.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementMapping"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/statement-schedules":{"get":{"operationId":"listStatementSchedules","summary":"Danh sách lịch nhận sao kê","description":"Mới tạo trước, tối đa 200. Lọc theo tài khoản.","tags":["Nhập sao kê"],"security":[{"bearerAuth":[]}],"x-dt-permission":"statement_schedule.manage","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"$ref":"#/components/schemas/AccountId"},"required":false,"description":"Mã tài khoản ngân hàng (`acc_…`).","name":"bank_account_id","in":"query"}],"responses":{"200":{"description":"Danh sách.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementScheduleList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createStatementSchedule","summary":"Tạo lịch nhận sao kê","description":"`email_attachment`: sao kê đến qua alias thư của công ty. `manual_upload`: nhắc người tải tay theo `cron`; quá `overdue_after_days` ngày mà chưa có thì trạng thái `overdue`. `sftp`: ngân hàng đẩy CAMT.053 lên máy chủ SFTP, cổng ngân hàng lấy về theo `cron`. Cần `cron` trừ nguồn thư; SFTP cần cấu hình máy chủ.","tags":["Nhập sao kê"],"security":[{"bearerAuth":[]}],"x-dt-permission":"statement_schedule.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStatementSchedule"}}}},"responses":{"201":{"description":"Đã tạo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementSchedule"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/statement-schedules/{id}":{"patch":{"operationId":"updateStatementSchedule","summary":"Sửa lịch nhận sao kê","description":"Sửa định dạng, lịch, cấu hình SFTP, tự nhập, hạn quá hạn, bật/tắt. Tài khoản và nguồn không đổi. `cron` chỉ với `manual_upload`/`sftp`; `sftp` chỉ với lịch SFTP.","tags":["Nhập sao kê"],"security":[{"bearerAuth":[]}],"x-dt-permission":"statement_schedule.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/StatementScheduleId"},"required":true,"description":"Mã lịch nhận sao kê (`ssc_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStatementSchedule"}}}},"responses":{"200":{"description":"Sau cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementSchedule"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteStatementSchedule","summary":"Xoá lịch nhận sao kê","description":"Xoá lịch; các sao kê đã nhập từ lịch này được giữ.","tags":["Nhập sao kê"],"security":[{"bearerAuth":[]}],"x-dt-permission":"statement_schedule.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/StatementScheduleId"},"required":true,"description":"Mã lịch nhận sao kê (`ssc_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"204":{"description":"Đã xoá.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/statement-schedules/{id}:run":{"post":{"operationId":"runStatementSchedule","summary":"Chạy lịch ngay","description":"Xử lý lại tệp gần nhất của lịch như một sao kê mới (theo `auto_commit` của lịch). `409 conflict` khi lịch chưa có tệp nào, hoặc là lịch `manual_upload` (tải tệp lên qua `POST /v1/statements/preview`). Việc lấy tệp từ SFTP do cổng ngân hàng thực hiện theo lịch.","tags":["Nhập sao kê"],"security":[{"bearerAuth":[]}],"x-dt-permission":"statement_schedule.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/StatementScheduleId"},"required":true,"description":"Mã lịch nhận sao kê (`ssc_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"202":{"description":"Đã nhận.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementAccepted"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/jobs/{id}":{"get":{"operationId":"getJob","summary":"Trạng thái tác vụ bất đồng bộ","description":"Theo dõi nhập sao kê, xuất, đồng bộ… Khi `state` là `queued` hoặc `running` phản hồi có `Retry-After` (giây) cho lần hỏi kế. Tác vụ của người khác hoặc ngoài phạm vi trả `404 resource_not_found`.","tags":["Tác vụ"],"security":[{"bearerAuth":[]}],"x-dt-permission":"any","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/JobId"},"required":true,"description":"Mã tác vụ bất đồng bộ (`job_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Tác vụ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Retry-After":{"schema":{"type":"string","description":"Có khi tác vụ chưa kết thúc: số giây nên chờ."},"required":false,"description":"Có khi tác vụ chưa kết thúc: số giây nên chờ."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/me":{"get":{"operationId":"getMe","summary":"Người gọi, các công ty và chế độ chạy","description":"Mọi thông tin xác thực hợp lệ đều gọi được. `companies` chỉ liệt kê những công ty thông tin xác thực này truy cập được; `mode` là `sandbox` với khoá `dt_test_`.","tags":["Danh tính"],"security":[{"bearerAuth":[]}],"x-dt-permission":"any","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Người gọi.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/me/roots":{"get":{"operationId":"listMeRoots","summary":"Các gốc tổ chức của người dùng","description":"Mọi gốc tổ chức mà người dùng đang đăng nhập thuộc về (lâu nhất trước), kèm gốc phiên đang làm việc (`active`). Chỉ cho người dùng đăng nhập, không dùng với khoá API hay OAuth. Không phân trang.","tags":["Danh tính"],"security":[{"bearerAuth":[]}],"x-dt-permission":"any","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách gốc.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeRootList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/me/root:switch":{"post":{"operationId":"switchRoot","summary":"Chuyển gốc tổ chức của phiên","description":"Đổi gốc tổ chức mà phiên đăng nhập này làm việc; các phiên khác không đổi và hiệu lực từ yêu cầu kế tiếp. Gốc người dùng không thuộc về trả `404 resource_not_found` (không phân biệt với gốc không tồn tại). Có ghi nhật ký kiểm toán `session.root_switch` tại gốc đích. Chỉ cho người dùng đăng nhập.","tags":["Danh tính"],"security":[{"bearerAuth":[]}],"x-dt-permission":"any","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwitchRoot"}}}},"responses":{"200":{"description":"Gốc phiên đang làm việc sau khi đổi.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeRoot"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/lookup/mst/{mst}":{"get":{"operationId":"lookupMst","summary":"Tra cứu doanh nghiệp theo mã số thuế","description":"Dữ liệu được lưu đệm 24 giờ; khi nguồn tra cứu lỗi trả bản đã lưu với `stale: true`, không có bản lưu thì `503`. MST không tồn tại trả `404`, sai định dạng trả `422`. Chỉ cho người dùng đăng nhập (kể cả người chưa có tổ chức, ở bước làm quen).","tags":["Danh tính"],"security":[{"bearerAuth":[]}],"x-dt-permission":"org.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":32,"description":"Mã số thuế 10 số, có thể kèm `-NNN`."},"required":true,"description":"Mã số thuế 10 số, có thể kèm `-NNN`.","name":"mst","in":"path"}],"responses":{"200":{"description":"Doanh nghiệp.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MstLookup"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/security/policy":{"get":{"operationId":"getSecurityPolicy","summary":"Chính sách bảo mật của tổ chức","description":"Chưa ghi lần nào thì trả giá trị mặc định. Chỉ người dùng có quyền quản trị tổ chức; không dùng với khoá API hay OAuth.","tags":["Bảo mật"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tenant.manage","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Chính sách.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecurityPolicy"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"put":{"operationId":"updateSecurityPolicy","summary":"Đổi chính sách bảo mật","description":"Cần xác thực lại gần đây (step-up); không dùng với khoá API hay OAuth. Bật tự duyệt hoặc đổi hạn mức tự duyệt chỉ chủ sở hữu được làm.","tags":["Bảo mật"],"security":[{"bearerAuth":[]}],"x-dt-permission":"security.policy.write","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecurityPolicyPatch"}}}},"responses":{"200":{"description":"Chính sách sau khi đổi.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecurityPolicy"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/sessions":{"get":{"operationId":"listSessions","summary":"Các phiên đăng nhập của tôi","description":"Hoạt động gần nhất trước. Chỉ cho người dùng đăng nhập. Không phân trang.","tags":["Danh tính"],"security":[{"bearerAuth":[]}],"x-dt-permission":"any","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách phiên.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/sessions:revoke-others":{"post":{"operationId":"revokeOtherSessions","summary":"Đăng xuất mọi nơi trừ phiên này","tags":["Danh tính"],"security":[{"bearerAuth":[]}],"x-dt-permission":"any","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Số phiên đã kết thúc.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeOtherSessionsResult"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/sessions/{id}":{"delete":{"operationId":"revokeSession","summary":"Đăng xuất một phiên","description":"Xoá phiên ngay: yêu cầu kế tiếp của phiên đó bị từ chối. Phiên của người khác hoặc không tồn tại đều trả `404`.","tags":["Danh tính"],"security":[{"bearerAuth":[]}],"x-dt-permission":"any","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Đã đăng xuất.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/onboarding":{"get":{"operationId":"getOnboardingDraft","summary":"Tiến độ làm quen đã lưu","tags":["Danh tính"],"security":[{"bearerAuth":[]}],"x-dt-permission":"any","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Bản nháp.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingDraft"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"put":{"operationId":"saveOnboardingDraft","summary":"Lưu tiến độ làm quen","description":"Chỉ cho người dùng đăng nhập, chỉ ghi được bản nháp của chính mình.","tags":["Danh tính"],"security":[{"bearerAuth":[]}],"x-dt-permission":"any","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveOnboardingDraft"}}}},"responses":{"200":{"description":"Đã lưu.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingDraft"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/orgs":{"get":{"operationId":"listOrgs","summary":"Danh sách công ty","description":"Các công ty (và nút gốc) trong phạm vi của thông tin xác thực. Không phân trang: luôn trả đủ, `has_more` luôn `false`.","tags":["Tổ chức"],"security":[{"bearerAuth":[]}],"x-dt-permission":"org.read","x-dt-scope":"mcp:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách tổ chức.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"post":{"operationId":"createOrg","summary":"Thêm công ty theo mã số thuế","description":"Tra cứu mã số thuế để điền tên pháp lý, địa chỉ, người đại diện. Người dùng chưa có tổ chức: hệ thống tạo luôn nút gốc và gán họ làm chủ sở hữu. Nguồn MST lỗi không chặn việc tạo (cần gửi `name`).","tags":["Tổ chức"],"security":[{"bearerAuth":[]}],"x-dt-permission":"company.create","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrg"}}}},"responses":{"201":{"description":"Đã tạo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrgResult"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/orgs/{id}":{"get":{"operationId":"getOrg","summary":"Chi tiết công ty","tags":["Tổ chức"],"security":[{"bearerAuth":[]}],"x-dt-permission":"org.read","x-dt-scope":"mcp:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":true,"description":"Mã công ty / tổ chức (`org_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Tổ chức.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Org"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"updateOrg","summary":"Sửa hồ sơ công ty","description":"Đổi hệ thống tài khoản hoặc múi giờ được ghi nhật ký riêng (`org.coa_change`).","tags":["Tổ chức"],"security":[{"bearerAuth":[]}],"x-dt-permission":"org.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":true,"description":"Mã công ty / tổ chức (`org_…`).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrg"}}}},"responses":{"200":{"description":"Tổ chức sau cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Org"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/orgs/{id}:transfer-ownership":{"post":{"operationId":"transferOrgOwnership","summary":"Bàn giao công ty cho khách hàng","description":"Chỉ chủ sở hữu, cần xác thực lại gần đây. Khách nhận lời mời làm chủ sở hữu và trở thành thành viên khi chấp nhận; phản hồi không tiết lộ email đã có tài khoản hay chưa.","tags":["Tổ chức"],"security":[{"bearerAuth":[]}],"x-dt-permission":"company.transfer_ownership","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":true,"description":"Mã công ty / tổ chức (`org_…`).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferOrg"}}}},"responses":{"200":{"description":"Tổ chức sau bàn giao.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Org"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/orgs/{id}:resync-mst":{"post":{"operationId":"resyncOrgMst","summary":"Đồng bộ lại hồ sơ từ mã số thuế","description":"Làm mới tên pháp lý, địa chỉ, người đại diện và tình trạng thuế của một công ty từ nguồn MST (tối đa một lần tra mới mỗi giờ cho mỗi mã). Nguồn lỗi hoặc không biết mã: giữ nguyên dữ liệu, `mst_source.status` cho biết lý do. Tên gọi trong hệ thống và tên hiển thị VietQR không bị đổi. Chỉ áp dụng cho công ty (không phải nút gốc).","tags":["Tổ chức"],"security":[{"bearerAuth":[]}],"x-dt-permission":"org.write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":true,"description":"Mã công ty / tổ chức (`org_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Kết quả đồng bộ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResyncOrgResult"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/orgs/{id}:delete-request":{"post":{"operationId":"requestOrgDeletion","summary":"Yêu cầu xoá công ty","description":"Cần người thứ hai xác nhận (`:delete-confirm`). Chỉ công ty đang `active`; đã có yêu cầu đang chờ trả `409 conflict`.","tags":["Tổ chức"],"security":[{"bearerAuth":[]}],"x-dt-permission":"company.delete_request","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":true,"description":"Mã công ty / tổ chức (`org_…`).","name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteOrgRequest"}}}},"responses":{"200":{"description":"Yêu cầu đang chờ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgApproval"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/orgs/{id}:delete-confirm":{"post":{"operationId":"confirmOrgDeletion","summary":"Xác nhận xoá công ty","description":"Người xác nhận phải khác người yêu cầu. Công ty bị đóng băng 30 ngày (dữ liệu giữ nguyên) rồi mới xoá hẳn.","tags":["Tổ chức"],"security":[{"bearerAuth":[]}],"x-dt-permission":"company.delete_confirm","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":true,"description":"Mã công ty / tổ chức (`org_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Công ty đã đóng băng.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgApproval"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/orgs/{id}:delete-cancel":{"post":{"operationId":"cancelOrgDeletion","summary":"Huỷ yêu cầu xoá công ty","description":"Chỉ người đã gửi yêu cầu được rút lại, khi yêu cầu còn chờ xác nhận. Không có yêu cầu đang chờ trả `404`; yêu cầu vừa được xử lý xong trả `409 conflict`. Phản hồi có `state: withdrawn`.","tags":["Tổ chức"],"security":[{"bearerAuth":[]}],"x-dt-permission":"company.delete_request","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":true,"description":"Mã công ty / tổ chức (`org_…`).","name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelOrgDeletion"}}}},"responses":{"200":{"description":"Yêu cầu đã rút lại.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgApproval"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/org-templates":{"get":{"operationId":"listOrgTemplates","summary":"Danh sách mẫu công ty","description":"Mẫu thuộc về nút gốc, nên chỉ người giữ nút gốc (phạm vi `all`) quản lý được. Không phân trang.","tags":["Tổ chức"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tenant.manage","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách mẫu.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgTemplateList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"post":{"operationId":"createOrgTemplate","summary":"Tạo mẫu công ty","tags":["Tổ chức"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tenant.manage","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrgTemplate"}}}},"responses":{"201":{"description":"Đã tạo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgTemplate"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/members":{"get":{"operationId":"listMembers","summary":"Danh sách thành viên","description":"Thành viên của các nút tổ chức mà người gọi truy cập được, phân trang theo con trỏ. `company_id` giới hạn một công ty.","tags":["Thành viên"],"security":[{"bearerAuth":[]}],"x-dt-permission":"member.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"type":"string","enum":["active","invited"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"`true`: chỉ thành viên chưa bật xác thực hai lớp."},"required":false,"description":"`true`: chỉ thành viên chưa bật xác thực hai lớp.","name":"without_2fa","in":"query"}],"responses":{"200":{"description":"Danh sách thành viên.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemberList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/members/{id}":{"get":{"operationId":"getMember","summary":"Chi tiết thành viên","tags":["Thành viên"],"security":[{"bearerAuth":[]}],"x-dt-permission":"member.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/MemberId"},"required":true,"description":"Mã thành viên (`mbr_…`): một vai trò tại một nút tổ chức.","name":"id","in":"path"}],"responses":{"200":{"description":"Thành viên.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Member"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"updateMember","summary":"Đổi vai trò, phạm vi hoặc yêu cầu 2FA của thành viên","description":"Cần xác thực lại gần đây (passkey/TOTP ≤ 15 phút). Một vai trò không thể cấp nhiều quyền hơn chính nó đang giữ; chỉ chủ sở hữu mới bổ nhiệm hoặc đổi chủ sở hữu khác; nút luôn còn ít nhất một chủ sở hữu đang hoạt động (vi phạm → `409 conflict`). Có hiệu lực từ yêu cầu kế tiếp của thành viên; được ghi nhật ký kiểm toán `member.role_change`.","tags":["Thành viên"],"security":[{"bearerAuth":[]}],"x-dt-permission":"member.role_change","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/MemberId"},"required":true,"description":"Mã thành viên (`mbr_…`): một vai trò tại một nút tổ chức.","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMember"}}}},"responses":{"200":{"description":"Thành viên sau khi cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Member"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"removeMember","summary":"Gỡ thành viên","description":"Cần xác thực lại gần đây. Phiên của thành viên mất quyền từ yêu cầu kế tiếp. Không gỡ được chủ sở hữu cuối cùng của một nút (`409 conflict`); chỉ chủ sở hữu mới gỡ được chủ sở hữu khác.","tags":["Thành viên"],"security":[{"bearerAuth":[]}],"x-dt-permission":"member.remove","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/MemberId"},"required":true,"description":"Mã thành viên (`mbr_…`): một vai trò tại một nút tổ chức.","name":"id","in":"path"}],"responses":{"204":{"description":"Đã gỡ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/invitations":{"post":{"operationId":"createInvitation","summary":"Mời một người qua email","description":"Chỉ mời được vai trò mà người mời nắm đủ quyền; chỉ chủ sở hữu mới mời chủ sở hữu. Phạm vi `list` chỉ áp dụng cho lời mời ở nút gốc. Liên kết chứa mã thông báo chỉ được gửi qua email.","tags":["Thành viên"],"security":[{"bearerAuth":[]}],"x-dt-permission":"member.invite","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvitation"}}}},"responses":{"201":{"description":"Đã tạo lời mời.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationCreated"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"get":{"operationId":"listInvitations","summary":"Danh sách lời mời","description":"Lời mời của các nút tổ chức mà người gọi truy cập được, phân trang theo con trỏ.","tags":["Thành viên"],"security":[{"bearerAuth":[]}],"x-dt-permission":"member.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["pending","accepted","revoked","expired"]},"required":false,"name":"state","in":"query"}],"responses":{"200":{"description":"Danh sách lời mời.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/invitations/preview":{"get":{"operationId":"previewInvitation","summary":"Xem trước lời mời bằng mã thông báo","description":"Không cần đăng nhập: mã thông báo trong liên kết là bằng chứng. Chỉ trả tên tổ chức, vai trò và hạn dùng, không bao giờ trả email, mã định danh hay người mời. Mã không tồn tại, đã hết hạn, đã thu hồi hoặc đã dùng đều trả cùng một `404 resource_not_found`. Phản hồi có `Cache-Control: no-store`.","tags":["Thành viên"],"security":[],"x-dt-permission":"public","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":16,"maxLength":256,"description":"Mã thông báo trong liên kết mời."},"required":true,"description":"Mã thông báo trong liên kết mời.","name":"token","in":"query"}],"responses":{"200":{"description":"Thông tin lời mời.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationPreview"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code`: `resource_not_found` — Không tìm thấy. Một câu trả lời duy nhất cho mã sai, hết hạn, đã thu hồi hoặc đã dùng.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/invitations:accept":{"post":{"operationId":"acceptInvitation","summary":"Nhận lời mời bằng mã thông báo","description":"Chỉ người dùng đã đăng nhập (không dùng khoá API hay OAuth) bằng đúng email được mời và đã xác minh email. Lời mời không còn hiệu lực → `409 conflict`; email không khớp → `403 permission_denied`; mã không tồn tại → `404 resource_not_found`.","tags":["Thành viên"],"security":[{"bearerAuth":[]}],"x-dt-permission":"any","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptInvitation"}}}},"responses":{"200":{"description":"Đã tham gia.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedInvitation"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/invitations/{id}:resend":{"post":{"operationId":"resendInvitation","summary":"Gửi lại lời mời đang chờ","description":"Tạo liên kết mới và cửa sổ hiệu lực mới (liên kết cũ không còn dùng được). Lời mời không ở trạng thái `pending` → `409 conflict`.","tags":["Thành viên"],"security":[{"bearerAuth":[]}],"x-dt-permission":"member.invite","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/InvitationId"},"required":true,"description":"Mã lời mời (`ivt_…`).","name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendInvitation"}}}},"responses":{"200":{"description":"Đã gửi lại.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationCreated"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/invitations/{id}:revoke":{"post":{"operationId":"revokeInvitation","summary":"Thu hồi lời mời đang chờ","description":"Lời mời không ở trạng thái `pending` → `409 conflict`.","tags":["Thành viên"],"security":[{"bearerAuth":[]}],"x-dt-permission":"member.invite","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/InvitationId"},"required":true,"description":"Mã lời mời (`ivt_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Lời mời đã thu hồi.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/roles":{"get":{"operationId":"listRoles","summary":"Vai trò hệ thống và quyền của từng vai trò","description":"Sinh từ cùng bảng quyền mà máy chủ dùng để cho phép hoặc từ chối, nên không thể lệch với thực tế. Không phân trang.","tags":["Thành viên"],"security":[{"bearerAuth":[]}],"x-dt-permission":"member.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Các vai trò.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/access-grants":{"get":{"operationId":"listAccessGrants","summary":"Danh sách quyền truy cập chéo","description":"Cả hai phía: quyền đã cấp (`given`, người gọi là bên cấp) và quyền được nhận (`received`, người gọi là bên nhận), mới nhất trước. `direction` và `status` thu hẹp kết quả.","tags":["Tổ chức"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tenant.manage","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"$ref":"#/components/schemas/AccessGrantStatus"},"required":false,"description":"`pending`: chờ bên kia kích hoạt; `active`: đang hiệu lực (trừ khi `expires_at` đã qua); `revoked`: đã thu hồi, không khôi phục.","name":"status","in":"query"},{"schema":{"$ref":"#/components/schemas/AccessGrantDirection"},"required":false,"description":"`given`: người gọi là bên cấp (dữ liệu của họ được chia sẻ); `received`: người gọi là bên nhận (văn phòng kế toán).","name":"direction","in":"query"}],"responses":{"200":{"description":"Danh sách quyền truy cập.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessGrantList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"proposeAccessGrant","summary":"Đề xuất quyền truy cập chéo","description":"Cần xác thực lại gần đây. Bên cấp hoặc bên nhận đều đề xuất được; quyền ở trạng thái `pending` tới khi bên còn lại kích hoạt. Người gọi không thuộc phía nào, hoặc bên cấp không tồn tại: `404`. Đã có quyền chưa thu hồi cho cùng cặp (bên cấp, bên nhận): `409 conflict`. `expires_at` đã qua hoặc vai trò `owner`: `422`.","tags":["Tổ chức"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tenant.manage","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposeAccessGrant"}}}},"responses":{"201":{"description":"Đã đề xuất.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessGrant"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/access-grants/{id}:activate":{"post":{"operationId":"activateAccessGrant","summary":"Kích hoạt quyền truy cập chéo","description":"Do bên KHÔNG đề xuất thực hiện, cần xác thực lại gần đây. Bên đề xuất tự kích hoạt: `403`. Quyền không còn `pending` (đã kích hoạt, đã thu hồi) hoặc đã quá `expires_at`: `409 conflict`. Không phải một bên của quyền: `404`.","tags":["Tổ chức"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tenant.manage","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AccessGrantId"},"required":true,"description":"Mã quyền truy cập chéo (`grt_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Quyền đang hiệu lực.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessGrant"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/access-grants/{id}:revoke":{"post":{"operationId":"revokeAccessGrant","summary":"Thu hồi quyền truy cập chéo","description":"Cả hai bên đều thu hồi được, bất cứ lúc nào, cần xác thực lại gần đây; có hiệu lực ở yêu cầu kế tiếp và không khôi phục (muốn cấp lại, đề xuất quyền mới). Đã thu hồi rồi: `409 conflict`. Không phải một bên của quyền: `404`.","tags":["Tổ chức"],"security":[{"bearerAuth":[]}],"x-dt-permission":"tenant.manage","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AccessGrantId"},"required":true,"description":"Mã quyền truy cập chéo (`grt_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Quyền đã thu hồi.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessGrant"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/api-keys":{"get":{"operationId":"listApiKeys","summary":"Danh sách khoá API của tổ chức","description":"Chỉ người giữ nút gốc với phạm vi `all` xem được (còn lại `403 permission_denied`). Phân trang theo con trỏ.","tags":["Khoá API"],"security":[{"bearerAuth":[]}],"x-dt-permission":"apikey.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["active","revoked","expired"]},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","enum":["live","test"],"description":"`live`: dữ liệu thật; `test`: sandbox."},"required":false,"description":"`live`: dữ liệu thật; `test`: sandbox.","name":"env","in":"query"}],"responses":{"200":{"description":"Danh sách khoá.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createApiKey","summary":"Tạo khoá API (bí mật chỉ trả một lần)","description":"Cần xác thực lại gần đây. Khoá không mang scope mà người tạo không thực hiện được ở mọi công ty khoá chạm tới (`403 permission_denied`); công ty hoặc tài khoản ngoài phạm vi → `404`. Được ghi nhật ký kiểm toán `apikey.create`.","tags":["Khoá API"],"security":[{"bearerAuth":[]}],"x-dt-permission":"apikey.write","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKey"}}}},"responses":{"201":{"description":"Khoá vừa tạo (kèm bí mật).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyIssued"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/api-keys/{id}":{"get":{"operationId":"getApiKey","summary":"Chi tiết khoá API (không bao giờ có bí mật)","tags":["Khoá API"],"security":[{"bearerAuth":[]}],"x-dt-permission":"apikey.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ApiKeyId"},"required":true,"description":"Mã khoá API (`apk_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Khoá.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/api-keys/{id}/calls":{"get":{"operationId":"listApiKeyCalls","summary":"Các lệnh gọi mẫu gần đây của khoá","description":"Phương thức, đường dẫn, mã trạng thái (không có nội dung). Tối đa 50 lệnh gần nhất, không phân trang.","tags":["Khoá API"],"security":[{"bearerAuth":[]}],"x-dt-permission":"apikey.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ApiKeyId"},"required":true,"description":"Mã khoá API (`apk_…`).","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Các lệnh gọi.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCallList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/api-keys/{id}:rotate":{"post":{"operationId":"rotateApiKey","summary":"Xoay khoá: cấp khoá thay thế, khoá cũ còn dùng 24 giờ","description":"Cần xác thực lại gần đây. Chỉ xoay được khoá đang `active` (còn lại `409 conflict`); người xoay phải có khả năng cấp mọi scope của khoá cũ. Được ghi nhật ký kiểm toán `apikey.rotate`; phản hồi có `Cache-Control: no-store`.","tags":["Khoá API"],"security":[{"bearerAuth":[]}],"x-dt-permission":"apikey.write","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ApiKeyId"},"required":true,"description":"Mã khoá API (`apk_…`).","name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateApiKey"}}}},"responses":{"200":{"description":"Khoá thay thế và khoá cũ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotatedApiKey"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/api-keys/{id}:revoke":{"post":{"operationId":"revokeApiKey","summary":"Thu hồi khoá (có hiệu lực trên mọi máy chủ trong vòng 5 giây)","description":"Cần xác thực lại gần đây. Khoá đã thu hồi → `409 conflict`. Thu hồi khoá thay thế trong thời gian ân hạn cũng thu hồi khoá tiền nhiệm. Được ghi nhật ký kiểm toán `apikey.revoke`.","tags":["Khoá API"],"security":[{"bearerAuth":[]}],"x-dt-permission":"apikey.write","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ApiKeyId"},"required":true,"description":"Mã khoá API (`apk_…`).","name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeApiKey"}}}},"responses":{"200":{"description":"Khoá đã thu hồi.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/api-keys/{id}:extend":{"post":{"operationId":"extendApiKey","summary":"Dời hạn khoá (tối đa 12 tháng kể từ bây giờ; khôi phục được khoá đã hết hạn)","description":"Cần xác thực lại gần đây. Khoá đã thu hồi mãi mãi bị thu hồi (`409 conflict`). Được ghi nhật ký kiểm toán `apikey.extend`.","tags":["Khoá API"],"security":[{"bearerAuth":[]}],"x-dt-permission":"apikey.write","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ApiKeyId"},"required":true,"description":"Mã khoá API (`apk_…`).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtendApiKey"}}}},"responses":{"200":{"description":"Khoá sau khi dời hạn.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/audit-events":{"get":{"operationId":"listAuditEvents","summary":"Danh sách nhật ký kiểm toán (mới nhất trước)","description":"Phân trang theo con trỏ. `actor` lọc theo chủ thể: `usr_…` (người dùng), `apk_…` (khoá API) hoặc `system`. Công ty không thuộc phạm vi người gọi → `404`.","tags":["Nhật ký kiểm toán"],"security":[{"bearerAuth":[]}],"x-dt-permission":"audit.read","x-dt-scope":"audit:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"type":"string","pattern":"^(?:usr_[0-9a-hjkmnp-tv-z]{26}|apk_[0-9a-hjkmnp-tv-z]{26}|system)$","description":"Lọc theo chủ thể: `usr_…`, `apk_…` hoặc `system`."},"required":false,"description":"Lọc theo chủ thể: `usr_…`, `apk_…` hoặc `system`.","name":"actor","in":"query"},{"schema":{"type":"string","maxLength":80,"description":"Lọc theo hành động, vd. `apikey.revoke`."},"required":false,"description":"Lọc theo hành động, vd. `apikey.revoke`.","name":"action","in":"query"},{"schema":{"type":"string","maxLength":60},"required":false,"name":"object_type","in":"query"},{"schema":{"type":"string","maxLength":80},"required":false,"name":"object_id","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Từ thời điểm (bao gồm)."},"required":false,"description":"Từ thời điểm (bao gồm).","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Đến thời điểm (không bao gồm)."},"required":false,"description":"Đến thời điểm (không bao gồm).","name":"to","in":"query"}],"responses":{"200":{"description":"Trang nhật ký.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEventList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/audit-events:export":{"post":{"operationId":"exportAuditEvents","summary":"Xuất nhật ký kiểm toán ra CSV","description":"Cần xác thực lại gần đây. Tối đa 50000 dòng (nhiều hơn → `422 validation_failed`: hãy thu hẹp thời gian hoặc công ty); không xuất phần diff và ghi chú. Việc xuất được ghi vào chuỗi nhật ký ở mức nhạy cảm; phản hồi có `Cache-Control: no-store`.","tags":["Nhật ký kiểm toán"],"security":[{"bearerAuth":[]}],"x-dt-permission":"audit.export","x-dt-step-up":true,"x-dt-rate-class":"export","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportAuditEvents"}}}},"responses":{"200":{"description":"Tệp CSV.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Content-Disposition":{"$ref":"#/components/headers/ContentDisposition"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/audit-events/{id}":{"get":{"operationId":"getAuditEvent","summary":"Chi tiết một dòng nhật ký kiểm toán","tags":["Nhật ký kiểm toán"],"security":[{"bearerAuth":[]}],"x-dt-permission":"audit.read","x-dt-scope":"audit:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AuditEventId"},"required":true,"description":"Mã dòng nhật ký kiểm toán (`aud_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Dòng nhật ký.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEvent"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/approvals":{"get":{"operationId":"listApprovals","summary":"Hàng chờ phê duyệt (mọi loại)","description":"Yêu cầu của các công ty người gọi truy cập được; với vai trò chỉ xem của chính mình thì chỉ thấy yêu cầu do mình đề nghị. Việc duyệt hoặc từ chối nằm ở route của đối tượng được duyệt.","tags":["Phê duyệt"],"security":[{"bearerAuth":[]}],"x-dt-permission":"approval.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["pending","approved","rejected","withdrawn","expired"]},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","enum":["allocation","obligation_allocation","partner_create","split_rule_version","payout_variance_recognition","export_batch","period_lock","period_unlock","mapping_change","category_retro_apply","tx_verify_manual","quarantine_release","merge_locked_period","shift_close","company_delete","flag_change","plan_change"]},"required":false,"name":"kind","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"type":"string","enum":["me"],"description":"`me`: chỉ yêu cầu đang chờ chính người gọi quyết định (chưa quyết và không do họ đề nghị)."},"required":false,"description":"`me`: chỉ yêu cầu đang chờ chính người gọi quyết định (chưa quyết và không do họ đề nghị).","name":"approver","in":"query"}],"responses":{"200":{"description":"Danh sách yêu cầu.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/approvals/readiness":{"get":{"operationId":"getApprovalReadiness","summary":"Ai có thể duyệt tại một công ty","description":"Chỉ đọc: không ghi gì. Công ty ngoài phạm vi người gọi → `404`.","tags":["Phê duyệt"],"security":[{"bearerAuth":[]}],"x-dt-permission":"approval.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":true,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"}],"responses":{"200":{"description":"Tình trạng sẵn sàng duyệt.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalReadiness"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/approvals/{id}":{"get":{"operationId":"getApproval","summary":"Chi tiết một yêu cầu phê duyệt","tags":["Phê duyệt"],"security":[{"bearerAuth":[]}],"x-dt-permission":"approval.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ApprovalRequestId"},"required":true,"description":"Mã yêu cầu duyệt (`apr_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Yêu cầu.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Approval"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/openapi.json":{"get":{"operationId":"getOpenApiDocument","summary":"Tài liệu OpenAPI 3.1","description":"Bản công khai của hợp đồng API (OpenAPI 3.1). Có `ETag`; cache 5 phút ở CDN.","tags":["Hệ thống"],"security":[],"x-dt-permission":"public","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-cors":"marketing","x-dt-service":"api","responses":{"200":{"description":"OpenAPI 3.1.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiDocument"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/openapi-3.0.json":{"get":{"operationId":"getOpenApi30Document","summary":"Tài liệu OpenAPI 3.0","description":"Cùng nội dung, hạ xuống OpenAPI 3.0 cho công cụ chưa hỗ trợ 3.1.","tags":["Hệ thống"],"security":[],"x-dt-permission":"public","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-cors":"marketing","x-dt-service":"api","responses":{"200":{"description":"OpenAPI 3.0.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiDocument"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/webhook-endpoints":{"get":{"operationId":"listWebhookEndpoints","summary":"Danh sách webhook endpoints","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"webhook.read","x-dt-scope":"webhooks:write","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"$ref":"#/components/schemas/WebhookEndpointState"},"required":false,"name":"state","in":"query"}],"responses":{"200":{"description":"Danh sách webhook endpoints.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createWebhookEndpoint","summary":"Tạo webhook endpoint mới","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"webhook.manage","x-dt-scope":"webhooks:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookEndpointBody"}}}},"responses":{"201":{"description":"Endpoint đã tạo kèm khoá bí mật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookEndpointResponse"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/webhook-endpoints/{id}":{"get":{"operationId":"getWebhookEndpoint","summary":"Chi tiết webhook endpoint","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"webhook.read","x-dt-scope":"webhooks:write","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/WebhookEndpointId"},"required":true,"description":"Mã webhook endpoint (`whe_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Chi tiết webhook endpoint.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"patchWebhookEndpoint","summary":"Cập nhật webhook endpoint","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"webhook.manage","x-dt-scope":"webhooks:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/WebhookEndpointId"},"required":true,"description":"Mã webhook endpoint (`whe_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchWebhookEndpointBody"}}}},"responses":{"200":{"description":"Endpoint đã cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteWebhookEndpoint","summary":"Xoá webhook endpoint","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"webhook.manage","x-dt-scope":"webhooks:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/WebhookEndpointId"},"required":true,"description":"Mã webhook endpoint (`whe_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Đã xoá endpoint.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhook-endpoints/{id}:test":{"post":{"operationId":"testWebhookEndpoint","summary":"Gửi sự kiện thử nghiệm ping tới endpoint","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"webhook.test","x-dt-scope":"webhooks:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/WebhookEndpointId"},"required":true,"description":"Mã webhook endpoint (`whe_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Kết quả gửi thử nghiệm.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointTestResponse"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhook-endpoints/{id}:resume":{"post":{"operationId":"resumeWebhookEndpoint","summary":"Bật lại endpoint đang bị tạm ngưng và xả hàng đợi","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"webhook.manage","x-dt-scope":"webhooks:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/WebhookEndpointId"},"required":true,"description":"Mã webhook endpoint (`whe_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Endpoint đã được bật lại.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointResumeResponse"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhook-endpoints/{id}:rotate-secret":{"post":{"operationId":"rotateWebhookEndpointSecret","summary":"Xoay khoá ký webhook (hỗ trợ 2 khoá song song 24 giờ)","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"webhook.manage","x-dt-scope":"webhooks:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/WebhookEndpointId"},"required":true,"description":"Mã webhook endpoint (`whe_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Khoá ký mới.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointRotateSecretResponse"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhook-deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"Danh sách lần giao webhook","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"webhook.read","x-dt-scope":"webhooks:write","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/WebhookEndpointId"},"required":false,"description":"Mã webhook endpoint (`whe_…`).","name":"endpoint_id","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"$ref":"#/components/schemas/WebhookDeliveryState"},"required":false,"name":"state","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Danh sách lần giao.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhook-deliveries/{id}":{"get":{"operationId":"getWebhookDelivery","summary":"Chi tiết lần giao webhook kèm lịch sử các lần thử","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"webhook.read","x-dt-scope":"webhooks:write","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/WebhookDeliveryId"},"required":true,"description":"Mã lần giao webhook (`whd_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Chi tiết lần giao.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryDetail"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhook-deliveries/{id}:replay":{"post":{"operationId":"replayWebhookDelivery","summary":"Phát lại một lần giao webhook (giữ nguyên webhook-id)","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"webhook.replay","x-dt-rate-class":"replay","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/WebhookDeliveryId"},"required":true,"description":"Mã lần giao webhook (`whd_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Kết quả phát lại.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplayDeliveryResponse"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhook-deliveries:replay-failed":{"post":{"operationId":"replayFailedDeliveries","summary":"Phát lại hàng loạt các lần giao lỗi (giới hạn 30 lần/phút/tổ chức)","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"webhook.replay","x-dt-rate-class":"replay","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplayFailedDeliveriesBody"}}}},"responses":{"200":{"description":"Kết quả phát lại hàng loạt.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplayFailedDeliveriesResponse"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/events":{"get":{"operationId":"listEvents","summary":"Danh sách sự kiện hệ thống (90 ngày)","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"webhook.read","x-dt-scope":"webhooks:write","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"type","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Danh sách sự kiện.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventListResponse"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/events/{id}":{"get":{"operationId":"getEvent","summary":"Chi tiết sự kiện","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"webhook.read","x-dt-scope":"webhooks:write","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/EventId"},"required":true,"description":"Mã sự kiện (`evt_…`), ổn định qua retry.","name":"id","in":"path"}],"responses":{"200":{"description":"Chi tiết sự kiện.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventListItem"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/event-types":{"get":{"operationId":"listEventTypes","summary":"Danh mục các loại sự kiện webhook công khai","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"webhook.read","x-dt-scope":"webhooks:write","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh mục sự kiện.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventTypeListResponse"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/sandbox/events:trigger":{"post":{"operationId":"triggerSandboxEvent","summary":"Kích hoạt sự kiện sandbox thử nghiệm","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"webhook.test","x-dt-scope":"webhooks:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriggerSandboxEventBody"}}}},"responses":{"201":{"description":"Sự kiện sandbox đã được đưa vào hàng đợi.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriggerSandboxEventResponse"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/cashflow/overview":{"get":{"operationId":"getCashflowOverview","summary":"Tổng quan dòng tiền hợp nhất","description":"Số dư hợp nhất (đã xác thực + tạm tính), vào/ra 30 ngày so kỳ trước, biểu đồ 12 tuần và tỷ trọng danh mục.","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"cashflow.read","x-dt-scope":"cashflow:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","description":"Danh sách id công ty phân cách bởi dấu phẩy"},"required":false,"description":"Danh sách id công ty phân cách bởi dấu phẩy","name":"company_ids","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"Dữ liệu tổng quan dòng tiền.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"consolidated_balance":{"type":"object","properties":{"verified":{"$ref":"#/components/schemas/Vnd"},"provisional":{"$ref":"#/components/schemas/Vnd"},"total":{"$ref":"#/components/schemas/Vnd"},"coverage_pct":{"type":"number","minimum":0,"maximum":100}},"required":["verified","provisional","total","coverage_pct"]},"periods":{"type":"object","properties":{"current_30d":{"type":"object","properties":{"inflow":{"$ref":"#/components/schemas/Vnd"},"outflow":{"$ref":"#/components/schemas/Vnd"},"net":{"$ref":"#/components/schemas/Vnd"}},"required":["inflow","outflow","net"]},"previous_30d":{"type":"object","properties":{"inflow":{"$ref":"#/components/schemas/Vnd"},"outflow":{"$ref":"#/components/schemas/Vnd"},"net":{"$ref":"#/components/schemas/Vnd"}},"required":["inflow","outflow","net"]}},"required":["current_30d","previous_30d"]},"weekly_chart":{"type":"array","items":{"type":"object","properties":{"week":{"type":"string"},"inflow":{"$ref":"#/components/schemas/Vnd"},"outflow":{"$ref":"#/components/schemas/Vnd"},"net":{"$ref":"#/components/schemas/Vnd"}},"required":["week","inflow","outflow","net"]}},"bank_accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"bank_code":{"type":"string"},"last4":{"type":"string"},"label":{"type":["string","null"]},"verified_balance":{"$ref":"#/components/schemas/Vnd"},"coverage_pct":{"type":"number","minimum":0,"maximum":100}},"required":["id","bank_code","last4","label","verified_balance","coverage_pct"]}},"categories_breakdown":{"type":"array","items":{"type":"object","properties":{"category_id":{"type":["string","null"],"format":"uuid"},"key":{"type":"string"},"name_vn":{"type":"string"},"direction":{"$ref":"#/components/schemas/CategoryDirection"},"amount":{"$ref":"#/components/schemas/Vnd"},"tx_count":{"type":"integer","minimum":0},"pct":{"type":"number","minimum":0,"maximum":100}},"required":["category_id","key","name_vn","direction","amount","tx_count","pct"]}}},"required":["consolidated_balance","periods","weekly_chart","bank_accounts","categories_breakdown"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cashflow/forecast":{"get":{"operationId":"getCashflowForecast","summary":"Dự báo dòng tiền 13 tuần","description":"Dự báo 13 tuần theo 3 kịch bản (cơ sở, thận trọng, lạc quan), P10/P50/P90.","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"cashflow.read","x-dt-scope":"cashflow:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ForecastScenario"},"required":false,"description":"Kịch bản dự báo dòng tiền: Cơ sở, Thận trọng, Lạc quan.","name":"scenario","in":"query"},{"schema":{"type":"string"},"required":false,"name":"company_ids","in":"query"}],"responses":{"200":{"description":"Dự báo dòng tiền 13 tuần.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"$ref":"#/components/schemas/ForecastRunId"},"scenario":{"$ref":"#/components/schemas/ForecastScenario"},"history_weeks":{"type":"integer","minimum":0},"coverage_pct":{"type":"number","minimum":0,"maximum":100},"ran_at":{"$ref":"#/components/schemas/Timestamp"},"data_confidence":{"type":"string","enum":["high","medium","low"]},"weeks":{"type":"array","items":{"type":"object","properties":{"week_no":{"type":"integer","minimum":1,"maximum":13},"week_start":{"type":"string"},"opening":{"$ref":"#/components/schemas/Vnd"},"inflow":{"$ref":"#/components/schemas/Vnd"},"outflow":{"$ref":"#/components/schemas/Vnd"},"closing_p50":{"$ref":"#/components/schemas/Vnd"},"p10":{"$ref":"#/components/schemas/Vnd"},"p90":{"$ref":"#/components/schemas/Vnd"},"events":{"type":"array","items":{"type":"object","additionalProperties":{}},"default":[]}},"required":["week_no","week_start","opening","inflow","outflow","closing_p50","p10","p90"]}},"known_items":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"amount":{"$ref":"#/components/schemas/Vnd"},"direction":{"$ref":"#/components/schemas/CategoryDirection"},"source":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1}},"required":["date","amount","direction","source","confidence"]}}},"required":["run_id","scenario","history_weeks","coverage_pct","ran_at","data_confidence","weeks","known_items"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cashflow/forecast:run":{"post":{"operationId":"triggerCashflowForecastRun","summary":"Chạy lại dự báo dòng tiền theo yêu cầu","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"cashflow.read","x-dt-scope":"cashflow:read","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Kết quả dự báo vừa chạy.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"$ref":"#/components/schemas/ForecastRunId"},"scenario":{"$ref":"#/components/schemas/ForecastScenario"},"history_weeks":{"type":"integer","minimum":0},"coverage_pct":{"type":"number","minimum":0,"maximum":100},"ran_at":{"$ref":"#/components/schemas/Timestamp"},"data_confidence":{"type":"string","enum":["high","medium","low"]},"weeks":{"type":"array","items":{"type":"object","properties":{"week_no":{"type":"integer","minimum":1,"maximum":13},"week_start":{"type":"string"},"opening":{"$ref":"#/components/schemas/Vnd"},"inflow":{"$ref":"#/components/schemas/Vnd"},"outflow":{"$ref":"#/components/schemas/Vnd"},"closing_p50":{"$ref":"#/components/schemas/Vnd"},"p10":{"$ref":"#/components/schemas/Vnd"},"p90":{"$ref":"#/components/schemas/Vnd"},"events":{"type":"array","items":{"type":"object","additionalProperties":{}},"default":[]}},"required":["week_no","week_start","opening","inflow","outflow","closing_p50","p10","p90"]}},"known_items":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"amount":{"$ref":"#/components/schemas/Vnd"},"direction":{"$ref":"#/components/schemas/CategoryDirection"},"source":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1}},"required":["date","amount","direction","source","confidence"]}}},"required":["run_id","scenario","history_weeks","coverage_pct","ran_at","data_confidence","weeks","known_items"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/cashflow/forecast-settings":{"get":{"operationId":"getForecastSettings","summary":"Cấu hình dự báo dòng tiền","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"cashflow.read","x-dt-scope":"cashflow:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Cấu hình dự báo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"$ref":"#/components/schemas/OrgId"},"min_balance_threshold":{"$ref":"#/components/schemas/Vnd"},"scenarios":{"type":"object","additionalProperties":{}},"fixed_calendar":{"type":"array","items":{"type":"object","additionalProperties":{}}},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["org_id","min_balance_threshold","scenarios","fixed_calendar","created_at","updated_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"put":{"operationId":"updateForecastSettings","summary":"Cập nhật cấu hình dự báo dòng tiền","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"forecast.settings.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"min_balance_threshold":{"$ref":"#/components/schemas/Vnd"},"scenarios":{"type":"object","additionalProperties":{}},"fixed_calendar":{"type":"array","items":{"type":"object","additionalProperties":{}}}}}}}},"responses":{"200":{"description":"Cấu hình dự báo đã cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"$ref":"#/components/schemas/OrgId"},"min_balance_threshold":{"$ref":"#/components/schemas/Vnd"},"scenarios":{"type":"object","additionalProperties":{}},"fixed_calendar":{"type":"array","items":{"type":"object","additionalProperties":{}}},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["org_id","min_balance_threshold","scenarios","fixed_calendar","created_at","updated_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/cashflow/counterparties":{"get":{"operationId":"getCashflowCounterparties","summary":"Phân tích đối tác dòng tiền","description":"Top 90 ngày đối tác theo chiều vào/ra, mức độ tập trung và trạng thái thuế.","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"cashflow.read","x-dt-scope":"cashflow:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","enum":["in","out"]},"required":false,"name":"direction","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Danh sách phân tích đối tác.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"counterparties":{"type":"array","items":{"type":"object","properties":{"counterparty_id":{"type":"string"},"name":{"type":"string"},"tax_code":{"type":["string","null"]},"tax_status":{"type":["string","null"]},"direction":{"$ref":"#/components/schemas/CategoryDirection"},"total_amount":{"$ref":"#/components/schemas/Vnd"},"tx_count":{"type":"integer","minimum":0},"concentration_pct":{"type":"number","minimum":0,"maximum":100},"last_tx_at":{"$ref":"#/components/schemas/Timestamp"},"primary_category_key":{"type":["string","null"]}},"required":["counterparty_id","name","tax_code","tax_status","direction","total_amount","tx_count","concentration_pct","last_tx_at","primary_category_key"]}}},"required":["counterparties"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cashflow/category-rules":{"get":{"operationId":"listCategoryRules","summary":"Danh sách quy tắc phân loại","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"cashflow.read","x-dt-scope":"cashflow:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách quy tắc.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CategoryRule"}}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"post":{"operationId":"createCategoryRule","summary":"Tạo quy tắc phân loại mới","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"category_rule.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"example":{"name":"Tiền điện EVN","conds":[{"field":"content","op":"contains","value":"EVN","join":"and"}],"direction":"out","category_id":"0192f3a4-5b6c-7d8e-9f01-23456789abcd","action":"assign"},"schema":{"type":"object","properties":{"seq_no":{"type":"integer"},"name":{"type":"string","minLength":1,"maxLength":120},"conds":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["content","counterparty_mst","counterparty_name","recipient_account_in_list","amount","account","direction"]},"op":{"type":"string","enum":["contains","starts_with","regex","eq","in","gte"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"array","items":{"type":"string"}}]},"join":{"type":"string","enum":["and","or"],"default":"and"}},"required":["field","op","value"]},"minItems":1},"direction":{"$ref":"#/components/schemas/CategoryDirection"},"category_id":{"type":["string","null"],"format":"uuid"},"action":{"type":"string","enum":["assign","tag_review"],"default":"assign"},"scope":{"type":"object","additionalProperties":{}}},"required":["name","conds"]}}}},"responses":{"201":{"description":"Quy tắc vừa tạo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryRule"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/cashflow/category-rules/{id}":{"patch":{"operationId":"updateCategoryRule","summary":"Cập nhật quy tắc phân loại","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"category_rule.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/CategoryRuleId"},"required":true,"description":"Mã quy tắc phân loại danh mục (`crl_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"seq_no":{"type":"integer"},"name":{"type":"string","minLength":1,"maxLength":120},"conds":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["content","counterparty_mst","counterparty_name","recipient_account_in_list","amount","account","direction"]},"op":{"type":"string","enum":["contains","starts_with","regex","eq","in","gte"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"array","items":{"type":"string"}}]},"join":{"type":"string","enum":["and","or"],"default":"and"}},"required":["field","op","value"]},"minItems":1},"direction":{"anyOf":[{"$ref":"#/components/schemas/CategoryDirection"},{"type":"null"}]},"category_id":{"type":["string","null"],"format":"uuid"},"action":{"type":"string","enum":["assign","tag_review"]},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Quy tắc sau cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryRule"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteCategoryRule","summary":"Xoá quy tắc phân loại","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"category_rule.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/CategoryRuleId"},"required":true,"description":"Mã quy tắc phân loại danh mục (`crl_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Đã xoá quy tắc.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]}},"required":["success"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cashflow/category-rules/{id}/enabled":{"put":{"operationId":"setCategoryRuleEnabled","summary":"Bật/tắt quy tắc phân loại","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"category_rule.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/CategoryRuleId"},"required":true,"description":"Mã quy tắc phân loại danh mục (`crl_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"enabled":true},"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}}},"responses":{"200":{"description":"Trạng thái quy tắc đã cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryRule"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cashflow/category-rules/{id}:preview-impact":{"post":{"operationId":"previewCategoryRuleImpact","summary":"Xem trước tác động của quy tắc phân loại","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"category_rule.write","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/CategoryRuleId"},"required":true,"description":"Mã quy tắc phân loại danh mục (`crl_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Số lượng giao dịch sẽ khớp.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"matched_count":{"type":"integer","minimum":0},"uncategorized_matched":{"type":"integer","minimum":0},"reclassified_matched":{"type":"integer","minimum":0},"sample_transaction_ids":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["matched_count","uncategorized_matched","reclassified_matched","sample_transaction_ids"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cashflow/category-rules/{id}:retro-apply":{"post":{"operationId":"retroApplyCategoryRule","summary":"Đề xuất áp dụng quy tắc phân loại cho giao dịch cũ","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"category_rule.retro_apply.propose","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/CategoryRuleId"},"required":true,"description":"Mã quy tắc phân loại danh mục (`crl_…`).","name":"id","in":"path"}],"responses":{"202":{"description":"Yêu cầu duyệt đã được tạo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"state":{"type":"string"},"matched_count":{"type":"integer"}},"required":["request_id","state","matched_count"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cashflow/category-rules/{id}:decide-retro-apply":{"post":{"operationId":"decideRetroApplyCategoryRule","summary":"Duyệt hoặc từ chối áp dụng quy tắc cho giao dịch cũ","description":"Người thứ hai (khác người đề nghị) quyết định yêu cầu `category_retro_apply` đang chờ. Cùng người đề nghị trả `403 approver_same_as_maker`. Duyệt xong, giao dịch khớp được gán danh mục (nhãn do người gán tay luôn được giữ). Nếu tập giao dịch khớp đã đổi so với lúc đề nghị, yêu cầu hết hạn và trả `409 conflict`.","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"category_rule.retro_apply.approve","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/CategoryRuleId"},"required":true,"description":"Mã quy tắc phân loại danh mục (`crl_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideCategoryRetroApply"}}}},"responses":{"200":{"description":"Kết quả quyết định.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["approved","rejected"]},"applied_count":{"type":"integer","minimum":0}},"required":["state","applied_count"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cashflow/category-suggestions/{id}:accept":{"post":{"operationId":"acceptCategorySuggestion","summary":"Chấp nhận gợi ý phân loại từ AI","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"category_rule.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Đã chấp nhận gợi ý.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]}},"required":["success"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cashflow/category-suggestions/{id}:dismiss":{"post":{"operationId":"dismissCategorySuggestion","summary":"Bỏ qua gợi ý phân loại từ AI","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"category_rule.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Đã bỏ qua gợi ý.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]}},"required":["success"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cashflow/categorization:bulk-accept":{"post":{"operationId":"bulkAcceptCategorization","summary":"Chấp nhận hàng loạt gợi ý phân loại có độ tin cậy cao","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"category_rule.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":["number","null"],"minimum":0,"maximum":1,"default":0.9},"required":false,"name":"min_confidence","in":"query"}],"responses":{"200":{"description":"Số lượng giao dịch đã áp dụng.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"accepted_count":{"type":"integer"}},"required":["accepted_count"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cashflow/alerts":{"get":{"operationId":"listCashflowAlerts","summary":"Danh sách cảnh báo dòng tiền","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"cashflow.read","x-dt-scope":"cashflow:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","enum":["open","snoozed","dismissed"]},"required":false,"name":"state","in":"query"}],"responses":{"200":{"description":"Danh sách cảnh báo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"$ref":"#/components/schemas/OrgId"},"rule_id":{"type":["string","null"],"format":"uuid"},"kind":{"type":"string"},"severity":{"type":"string","enum":["info","warning","critical"]},"state":{"type":"string","enum":["open","snoozed","dismissed","sent"]},"title":{"type":"string"},"message":{"type":"string"},"subject":{"type":"object","additionalProperties":{}},"dedupe_key":{"type":"string"},"snoozed_until":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"resolved_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["id","org_id","rule_id","kind","severity","state","title","message","subject","dedupe_key","snoozed_until","created_at","resolved_at"]}}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cashflow/alerts/{id}:snooze":{"post":{"operationId":"snoozeCashflowAlert","summary":"Tạm ẩn cảnh báo dòng tiền (mặc định 7 ngày)","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"alert_rule.manage","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer","minimum":1,"maximum":30,"default":7}}}}}},"responses":{"200":{"description":"Cảnh báo đã được tạm ẩn.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]}},"required":["success"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cashflow/alerts/{id}:dismiss":{"post":{"operationId":"dismissCashflowAlert","summary":"Bỏ qua cảnh báo dòng tiền","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"alert_rule.manage","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Đã bỏ qua cảnh báo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]}},"required":["success"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cashflow/alert-rules":{"get":{"operationId":"listCashflowAlertRules","summary":"Danh sách quy tắc cảnh báo dòng tiền","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"cashflow.read","x-dt-scope":"cashflow:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách quy tắc.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"$ref":"#/components/schemas/OrgId"},"kind":{"type":"string","enum":["forecast_below_threshold","anomaly_3sigma","overdue_receivable","coverage_drop","counterparty_concentration","inactive_mst_receiving"]},"params":{"type":"object","additionalProperties":{}},"severity":{"type":"string","enum":["info","warning","critical"]},"channels":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","org_id","kind","params","severity","channels","enabled","created_at","updated_at"]}}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"post":{"operationId":"createCashflowAlertRule","summary":"Tạo quy tắc cảnh báo dòng tiền","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"alert_rule.manage","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["forecast_below_threshold","anomaly_3sigma","overdue_receivable","coverage_drop","counterparty_concentration","inactive_mst_receiving"]},"params":{"type":"object","additionalProperties":{},"default":{}},"severity":{"type":"string","enum":["info","warning","critical"],"default":"warning"},"channels":{"type":"array","items":{"type":"string"},"default":["in_app"]},"enabled":{"type":"boolean","default":true}},"required":["kind"]}}}},"responses":{"201":{"description":"Quy tắc vừa tạo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"$ref":"#/components/schemas/OrgId"},"kind":{"type":"string","enum":["forecast_below_threshold","anomaly_3sigma","overdue_receivable","coverage_drop","counterparty_concentration","inactive_mst_receiving"]},"params":{"type":"object","additionalProperties":{}},"severity":{"type":"string","enum":["info","warning","critical"]},"channels":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","org_id","kind","params","severity","channels","enabled","created_at","updated_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/cashflow/alert-rules/{id}":{"put":{"operationId":"updateCashflowAlertRule","summary":"Cập nhật quy tắc cảnh báo dòng tiền","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"alert_rule.manage","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"params":{"type":"object","additionalProperties":{}},"severity":{"type":"string","enum":["info","warning","critical"]},"channels":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Quy tắc sau khi cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"$ref":"#/components/schemas/OrgId"},"kind":{"type":"string","enum":["forecast_below_threshold","anomaly_3sigma","overdue_receivable","coverage_drop","counterparty_concentration","inactive_mst_receiving"]},"params":{"type":"object","additionalProperties":{}},"severity":{"type":"string","enum":["info","warning","critical"]},"channels":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","org_id","kind","params","severity","channels","enabled","created_at","updated_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cashflow/category-rules:preview-impact":{"post":{"operationId":"previewUnsavedCategoryRuleImpact","summary":"Xem trước tác động của quy tắc phân loại chưa lưu","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"category_rule.write","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"seq_no":{"type":"integer"},"name":{"type":"string","minLength":1,"maxLength":120},"conds":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["content","counterparty_mst","counterparty_name","recipient_account_in_list","amount","account","direction"]},"op":{"type":"string","enum":["contains","starts_with","regex","eq","in","gte"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"array","items":{"type":"string"}}]},"join":{"type":"string","enum":["and","or"],"default":"and"}},"required":["field","op","value"]},"minItems":1},"direction":{"$ref":"#/components/schemas/CategoryDirection"},"category_id":{"type":["string","null"],"format":"uuid"},"action":{"type":"string","enum":["assign","tag_review"],"default":"assign"},"scope":{"type":"object","additionalProperties":{}}}}}}},"responses":{"200":{"description":"Số lượng giao dịch sẽ khớp.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"matched_count":{"type":"integer","minimum":0},"uncategorized_matched":{"type":"integer","minimum":0},"reclassified_matched":{"type":"integer","minimum":0},"sample_transaction_ids":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["matched_count","uncategorized_matched","reclassified_matched","sample_transaction_ids"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/cashflow/category-suggestions":{"get":{"operationId":"listCategorySuggestions","summary":"Danh sách gợi ý phân loại từ AI","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"cashflow.read","x-dt-scope":"cashflow:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách gợi ý phân loại.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"pattern_title":{"type":"string"},"conditions":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["content","counterparty_mst","counterparty_name","recipient_account_in_list","amount","account","direction"]},"op":{"type":"string","enum":["contains","starts_with","regex","eq","in","gte"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"array","items":{"type":"string"}}]},"join":{"type":"string","enum":["and","or"],"default":"and"}},"required":["field","op","value"]}},"direction":{"type":"string","enum":["in","out","both"]},"target_category":{"type":"string"},"confidence":{"type":"number"},"matched_count":{"type":"integer"},"total_amount":{"type":"number"},"explanation":{"type":"string"}},"required":["id","pattern_title","conditions","direction","target_category","confidence","matched_count","total_amount","explanation"]}}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/cashflow/pending-classifications":{"get":{"operationId":"listPendingClassifications","summary":"Danh sách giao dịch chờ phân loại","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"cashflow.read","x-dt-scope":"cashflow:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách giao dịch chờ phân loại.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"time":{"type":"string"},"account_label":{"type":"string"},"memo":{"type":"string"},"amount":{"type":"number"},"direction":{"type":"string","enum":["in","out"]},"suggested_category":{"type":"string"},"confidence":{"type":"number"}},"required":["id","time","account_label","memo","amount","direction","suggested_category","confidence"]}}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/categories":{"get":{"operationId":"listCategories","summary":"Danh sách danh mục hệ thống và công ty","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"cashflow.read","x-dt-scope":"cashflow:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách các danh mục thu chi.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/cashflow/categories":{"get":{"operationId":"listCashflowCategories","summary":"Danh sách danh mục dòng tiền","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"cashflow.read","x-dt-scope":"cashflow:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách danh mục thu chi.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"post":{"operationId":"createCashflowCategory","summary":"Tạo danh mục dòng tiền tuỳ biến cho công ty","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"category_rule.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"example":{"key":"tien_dien_nuoc","name_vn":"Tiền điện nước","direction":"out"},"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9_]+$"},"name_vn":{"type":"string","minLength":1,"maxLength":120},"direction":{"$ref":"#/components/schemas/CategoryDirection"}},"required":["key","name_vn","direction"]}}}},"responses":{"201":{"description":"Danh mục vừa tạo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/cashflow/categories/{id}":{"patch":{"operationId":"updateCashflowCategory","summary":"Cập nhật danh mục dòng tiền tuỳ biến","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"category_rule.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name_vn":{"type":"string","minLength":1,"maxLength":120},"direction":{"$ref":"#/components/schemas/CategoryDirection"}}}}}},"responses":{"200":{"description":"Danh mục sau cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/ai/settings":{"get":{"operationId":"getAiSettings","summary":"Cài đặt chế độ AI của tổ chức","description":"Chế độ AI (off/platform/byok), data_mode (platform_ok/byok_only) và chính sách fallback.","tags":["Trí tuệ nhân tạo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"ai.connection.manage","x-dt-step-up":true,"x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Cấu hình AI của tổ chức.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"root_id":{"$ref":"#/components/schemas/OrgId"},"mode":{"$ref":"#/components/schemas/AiMode"},"data_mode":{"$ref":"#/components/schemas/AiDataMode"},"allow_platform_fallback":{"type":"boolean"},"updated_by":{"type":["string","null"],"format":"uuid"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["root_id","mode","data_mode","allow_platform_fallback","updated_by","updated_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"put":{"operationId":"updateAiSettings","summary":"Cập nhật chế độ AI của tổ chức","description":"Cập nhật chế độ AI, data_mode và fallback. Bắt buộc xác thực tăng cường (step-up).","tags":["Trí tuệ nhân tạo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"ai.connection.manage","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"$ref":"#/components/schemas/AiMode"},"data_mode":{"$ref":"#/components/schemas/AiDataMode"},"allow_platform_fallback":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Cấu hình AI sau cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"root_id":{"$ref":"#/components/schemas/OrgId"},"mode":{"$ref":"#/components/schemas/AiMode"},"data_mode":{"$ref":"#/components/schemas/AiDataMode"},"allow_platform_fallback":{"type":"boolean"},"updated_by":{"type":["string","null"],"format":"uuid"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["root_id","mode","data_mode","allow_platform_fallback","updated_by","updated_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/ai/connections":{"get":{"operationId":"listAiConnections","summary":"Danh sách kết nối AI (BYOK & Platform)","tags":["Trí tuệ nhân tạo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"ai.connection.manage","x-dt-step-up":true,"x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách kết nối AI.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AiConnectionId"},"root_id":{"$ref":"#/components/schemas/OrgId"},"provider":{"type":"string","enum":["openai","anthropic","google","azure","openrouter","deepseek","openai_compatible"]},"kind":{"type":"string","enum":["chat","embedding"],"default":"chat"},"name":{"type":"string","minLength":1,"maxLength":100},"base_url":{"type":"string","format":"uri"},"base_url_host":{"type":"string"},"connect_mode":{"$ref":"#/components/schemas/AiConnectMode"},"origin":{"type":"string"},"key_last4":{"type":["string","null"]},"models":{"type":"array","items":{"type":"string"},"default":[]},"state":{"$ref":"#/components/schemas/AiConnectionState"},"last_checked_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","root_id","provider","name","base_url","base_url_host","connect_mode","origin","key_last4","state","last_checked_at","created_at","updated_at"]}}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"post":{"operationId":"createAiConnection","summary":"Tạo kết nối AI riêng (BYOK)","description":"Mã hoá khoá API bằng AES-256-GCM. URL được kiểm tra qua net-guard (chặn SSRF).","tags":["Trí tuệ nhân tạo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"ai.connection.manage","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"example":{"provider":"openai_compatible","kind":"chat","name":"Gateway AI nội bộ","base_url":"https://ai.congty.vn/v1","connect_mode":"public","api_key":"sk-demo-1234567890abcdef"},"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["openai","anthropic","google","azure","openrouter","deepseek","openai_compatible"]},"kind":{"type":"string","enum":["chat","embedding"],"default":"chat"},"name":{"type":"string","minLength":1,"maxLength":100},"base_url":{"type":"string","format":"uri"},"connect_mode":{"$ref":"#/components/schemas/AiConnectMode"},"api_key":{"type":"string","minLength":1},"extra_headers":{"type":"object","additionalProperties":{"type":"string"}},"query_params":{"type":"object","additionalProperties":{"type":"string"}}},"required":["provider","name","base_url","api_key"]}}}},"responses":{"201":{"description":"Kết nối AI vừa tạo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AiConnectionId"},"root_id":{"$ref":"#/components/schemas/OrgId"},"provider":{"type":"string","enum":["openai","anthropic","google","azure","openrouter","deepseek","openai_compatible"]},"kind":{"type":"string","enum":["chat","embedding"],"default":"chat"},"name":{"type":"string","minLength":1,"maxLength":100},"base_url":{"type":"string","format":"uri"},"base_url_host":{"type":"string"},"connect_mode":{"$ref":"#/components/schemas/AiConnectMode"},"origin":{"type":"string"},"key_last4":{"type":["string","null"]},"models":{"type":"array","items":{"type":"string"},"default":[]},"state":{"$ref":"#/components/schemas/AiConnectionState"},"last_checked_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","root_id","provider","name","base_url","base_url_host","connect_mode","origin","key_last4","state","last_checked_at","created_at","updated_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/ai/connections/{id}":{"patch":{"operationId":"updateAiConnection","summary":"Cập nhật kết nối AI","description":"Nếu thay đổi base_url, connect_mode, extra_headers hoặc query_params mà không gửi kèm khoá mới, khoá cũ bị xoá, kết nối chuyển về state 'new' và máy chủ trả 422 `key_required` (việc xoá khoá vẫn được lưu).","tags":["Trí tuệ nhân tạo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"ai.connection.manage","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AiConnectionId"},"required":true,"description":"Mã kết nối AI (`aip_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"base_url":{"type":"string","format":"uri"},"connect_mode":{"$ref":"#/components/schemas/AiConnectMode"},"api_key":{"type":"string","minLength":1},"extra_headers":{"type":"object","additionalProperties":{"type":"string"}},"query_params":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"responses":{"200":{"description":"Kết nối AI sau cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AiConnectionId"},"root_id":{"$ref":"#/components/schemas/OrgId"},"provider":{"type":"string","enum":["openai","anthropic","google","azure","openrouter","deepseek","openai_compatible"]},"kind":{"type":"string","enum":["chat","embedding"],"default":"chat"},"name":{"type":"string","minLength":1,"maxLength":100},"base_url":{"type":"string","format":"uri"},"base_url_host":{"type":"string"},"connect_mode":{"$ref":"#/components/schemas/AiConnectMode"},"origin":{"type":"string"},"key_last4":{"type":["string","null"]},"models":{"type":"array","items":{"type":"string"},"default":[]},"state":{"$ref":"#/components/schemas/AiConnectionState"},"last_checked_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","root_id","provider","name","base_url","base_url_host","connect_mode","origin","key_last4","state","last_checked_at","created_at","updated_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteAiConnection","summary":"Xoá kết nối AI","tags":["Trí tuệ nhân tạo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"ai.connection.manage","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AiConnectionId"},"required":true,"description":"Mã kết nối AI (`aip_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Đã xoá kết nối.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]}},"required":["success"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/ai/connections/{id}:test":{"post":{"operationId":"testAiConnection","summary":"Kiểm tra kết nối AI 6 bước","description":"Thực hiện kiểm tra 6 bước: SSRF net-guard -> DNS/TLS -> Xác thực -> Liệt kê models -> Thử 1 token -> Probe.","tags":["Trí tuệ nhân tạo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"ai.connection.manage","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AiConnectionId"},"required":true,"description":"Mã kết nối AI (`aip_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Kết quả kiểm tra kết nối.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"connection_id":{"$ref":"#/components/schemas/AiConnectionId"},"success":{"type":"boolean"},"state":{"$ref":"#/components/schemas/AiConnectionState"},"steps":{"type":"array","items":{"type":"object","properties":{"step":{"type":"string","enum":["net_guard","dns_tls","auth","list_models","sample_call","probe"]},"status":{"type":"string","enum":["passed","failed","skipped"]},"message":{"type":"string"},"latency_ms":{"type":"integer","minimum":0}},"required":["step","status"]}},"discovered_models":{"type":"array","items":{"type":"string"},"default":[]}},"required":["connection_id","success","state","steps"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/ai/connections/{id}:probe":{"post":{"operationId":"probeAiConnection","summary":"Dò khả năng của mô hình (structured output, tool calling, embedding dim)","tags":["Trí tuệ nhân tạo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"ai.connection.manage","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AiConnectionId"},"required":true,"description":"Mã kết nối AI (`aip_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"model_id":"gpt-4o-mini"},"schema":{"type":"object","properties":{"model_id":{"type":"string"}},"required":["model_id"]}}}},"responses":{"200":{"description":"Kết quả dò khả năng mô hình.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"connection_id":{"$ref":"#/components/schemas/AiConnectionId"},"model_id":{"type":"string"},"structured_output":{"type":"boolean"},"tool_call":{"type":"boolean"},"embedding_dim":{"type":["integer","null"],"exclusiveMinimum":0},"context":{"type":"integer","exclusiveMinimum":0},"latency_ms":{"type":"integer","minimum":0}},"required":["connection_id","model_id","structured_output","tool_call","embedding_dim","latency_ms"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/ai/models":{"get":{"operationId":"listAiModelCatalog","summary":"Danh mục mô hình AI (đồng bộ từ models.dev)","tags":["Trí tuệ nhân tạo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"ai.connection.manage","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string"},"required":false,"name":"provider","in":"query"}],"responses":{"200":{"description":"Danh mục mô hình AI.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"model_id":{"type":"string"},"context":{"type":"integer","default":0},"limit_output":{"type":["integer","null"]},"price_in_usd_mtok":{"type":["number","null"]},"price_out_usd_mtok":{"type":["number","null"]},"tool_call":{"type":"boolean","default":false},"structured_output":{"type":["boolean","null"]},"modalities":{"type":"array","items":{"type":"string"},"default":["text"]},"api":{"type":["string","null"]},"npm":{"type":["string","null"]},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["provider","model_id","limit_output","price_in_usd_mtok","price_out_usd_mtok","structured_output","api","npm","updated_at"]}}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/ai/connections/{id}/models":{"get":{"operationId":"listAiConnectionModels","summary":"Danh sách mô hình và khả năng của kết nối","tags":["Trí tuệ nhân tạo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"ai.connection.manage","x-dt-step-up":true,"x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AiConnectionId"},"required":true,"description":"Mã kết nối AI (`aip_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Danh sách mô hình đã ghi nhận.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"connection_id":{"$ref":"#/components/schemas/AiConnectionId"},"model_id":{"type":"string"},"context":{"type":"integer","default":0},"max_output":{"type":["integer","null"]},"tool_call":{"type":"boolean","default":false},"structured_output":{"type":["boolean","null"]},"price_in_usd_mtok":{"type":["number","null"]},"price_out_usd_mtok":{"type":["number","null"]},"source":{"type":"string","enum":["catalog","manual","probe"],"default":"manual"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["connection_id","model_id","max_output","structured_output","price_in_usd_mtok","price_out_usd_mtok","updated_at"]}}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/ai/task-assignments":{"get":{"operationId":"listAiTaskAssignments","summary":"Danh sách gán mô hình theo tác vụ","tags":["Trí tuệ nhân tạo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"ai.task.assign","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách gán tác vụ AI.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"task":{"type":"string","enum":["classify_transaction","reconcile_suggest","assistant","cashflow_explain","embedding"]},"connection_id":{"anyOf":[{"$ref":"#/components/schemas/AiConnectionId"},{"type":"null"}]},"model":{"type":"string"},"fallback":{"type":"array","items":{"type":"object","properties":{"connection_id":{"$ref":"#/components/schemas/AiConnectionId"},"model":{"type":"string"}},"required":["connection_id","model"]},"default":[]},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["task","connection_id","model","updated_at"]}}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"put":{"operationId":"updateAiTaskAssignments","summary":"Gán kết nối và mô hình cho tác vụ AI","tags":["Trí tuệ nhân tạo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"ai.task.assign","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"example":{"task":"classify_transaction","connection_id":"aip_0f5k2m9q4h7t3n8r6v1w0x5yz0","model":"gpt-4o-mini","fallback":[]},"schema":{"type":"object","properties":{"task":{"type":"string","enum":["classify_transaction","reconcile_suggest","assistant","cashflow_explain","embedding"]},"connection_id":{"anyOf":[{"$ref":"#/components/schemas/AiConnectionId"},{"type":"null"}]},"model":{"type":"string"},"fallback":{"type":"array","items":{"type":"object","properties":{"connection_id":{"$ref":"#/components/schemas/AiConnectionId"},"model":{"type":"string"}},"required":["connection_id","model"]},"default":[]}},"required":["task","connection_id","model"]}}}},"responses":{"200":{"description":"Gán tác vụ sau cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"string","enum":["classify_transaction","reconcile_suggest","assistant","cashflow_explain","embedding"]},"connection_id":{"anyOf":[{"$ref":"#/components/schemas/AiConnectionId"},{"type":"null"}]},"model":{"type":"string"},"fallback":{"type":"array","items":{"type":"object","properties":{"connection_id":{"$ref":"#/components/schemas/AiConnectionId"},"model":{"type":"string"}},"required":["connection_id","model"]},"default":[]},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["task","connection_id","model","updated_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/ai/budget":{"get":{"operationId":"getAiBudget","summary":"Ngân sách và giới hạn chi phí AI của tổ chức","tags":["Trí tuệ nhân tạo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"ai.budget.write","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Ngân sách AI.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"root_id":{"$ref":"#/components/schemas/OrgId"},"monthly_cost_cap_vnd":{"anyOf":[{"$ref":"#/components/schemas/Vnd"},{"type":"null"}]},"monthly_token_cap":{"type":["integer","null"],"minimum":0},"on_cap":{"type":"string","enum":["pause","switch_platform"],"default":"pause"},"privacy":{"type":"object","properties":{"mask_names":{"type":"boolean","default":true},"mask_mst":{"type":"boolean","default":true},"send_raw_memo":{"type":"boolean","default":false}}},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["root_id","monthly_cost_cap_vnd","monthly_token_cap","privacy","updated_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"put":{"operationId":"updateAiBudget","summary":"Cập nhật ngân sách và giới hạn chi phí AI","tags":["Trí tuệ nhân tạo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"ai.budget.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"monthly_cost_cap_vnd":{"anyOf":[{"$ref":"#/components/schemas/Vnd"},{"type":"null"}]},"monthly_token_cap":{"type":["integer","null"],"minimum":0},"on_cap":{"type":"string","enum":["pause","switch_platform"]},"privacy":{"type":"object","properties":{"mask_names":{"type":"boolean"},"mask_mst":{"type":"boolean"},"send_raw_memo":{"type":"boolean"}}}}}}}},"responses":{"200":{"description":"Ngân sách AI sau cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"root_id":{"$ref":"#/components/schemas/OrgId"},"monthly_cost_cap_vnd":{"anyOf":[{"$ref":"#/components/schemas/Vnd"},{"type":"null"}]},"monthly_token_cap":{"type":["integer","null"],"minimum":0},"on_cap":{"type":"string","enum":["pause","switch_platform"],"default":"pause"},"privacy":{"type":"object","properties":{"mask_names":{"type":"boolean","default":true},"mask_mst":{"type":"boolean","default":true},"send_raw_memo":{"type":"boolean","default":false}}},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["root_id","monthly_cost_cap_vnd","monthly_token_cap","privacy","updated_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/ai/usage":{"get":{"operationId":"getAiUsage","summary":"Thống kê sử dụng AI theo ngày, kết nối và tác vụ","tags":["Trí tuệ nhân tạo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"ai.usage.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":90,"default":30},"required":false,"name":"days","in":"query"}],"responses":{"200":{"description":"Số liệu sử dụng AI.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"daily":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"tokens_in":{"type":"integer","minimum":0},"tokens_out":{"type":"integer","minimum":0},"calls":{"type":"integer","minimum":0},"est_cost_vnd":{"$ref":"#/components/schemas/Vnd"}},"required":["day","tokens_in","tokens_out","calls","est_cost_vnd"]}},"by_connection":{"type":"array","items":{"type":"object","properties":{"connection_id":{"type":"string"},"calls":{"type":"integer","minimum":0},"tokens":{"type":"integer","minimum":0},"est_cost_vnd":{"$ref":"#/components/schemas/Vnd"}},"required":["connection_id","calls","tokens","est_cost_vnd"]}},"by_task":{"type":"array","items":{"type":"object","properties":{"task":{"type":"string"},"calls":{"type":"integer","minimum":0},"tokens":{"type":"integer","minimum":0},"est_cost_vnd":{"$ref":"#/components/schemas/Vnd"}},"required":["task","calls","tokens","est_cost_vnd"]}}},"required":["daily","by_connection","by_task"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/partners":{"get":{"operationId":"listPartners","summary":"Danh sách đối tác sàn/hãng/CTV","description":"Liệt kê danh sách đối tác đối soát theo tổ chức.","tags":["Đối tác"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-scope":"settlement:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/PartnerKind"},"required":false,"description":"`marketplace` sàn TMĐT · `agent` đại lý bán lẻ · `brand_consignor` hãng/chủ hàng ký gửi · `ctv_group` nhóm cộng tác viên.","name":"kind","in":"query"},{"schema":{"$ref":"#/components/schemas/PartnerState"},"required":false,"description":"`draft` mới tạo · `pending_approval` chờ duyệt · `active` đang hoạt động · `archived` lưu trữ.","name":"state","in":"query"}],"responses":{"200":{"description":"Danh sách đối tác.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createPartner","summary":"Tạo đối tác mới","description":"Tạo đối tác ở trạng thái `draft`. Đối tác mới cần phê duyệt trước khi kích hoạt sinh nghĩa vụ.","tags":["Đối tác"],"security":[{"bearerAuth":[]}],"x-dt-permission":"partner.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePartnerBody"}}}},"responses":{"201":{"description":"Đối tác đã tạo thành công.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Partner"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/settlement/partners/{id}":{"get":{"operationId":"getPartner","summary":"Chi tiết đối tác","description":"Lấy thông tin chi tiết của một đối tác.","tags":["Đối tác"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-scope":"settlement:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PartnerId"},"required":true,"description":"Mã đối tác sàn/hãng/CTV (`ptn_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Chi tiết đối tác.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Partner"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"updatePartner","summary":"Cập nhật thông tin đối tác","tags":["Đối tác"],"security":[{"bearerAuth":[]}],"x-dt-permission":"partner.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PartnerId"},"required":true,"description":"Mã đối tác sàn/hãng/CTV (`ptn_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePartnerBody"}}}},"responses":{"200":{"description":"Thông tin đã cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Partner"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/partners/{id}:approve":{"post":{"operationId":"approvePartner","summary":"Duyệt kích hoạt đối tác","description":"Maker-checker: Người duyệt phải khác người tạo đối tác.","tags":["Đối tác"],"security":[{"bearerAuth":[]}],"x-dt-permission":"partner.approve","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PartnerId"},"required":true,"description":"Mã đối tác sàn/hãng/CTV (`ptn_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Đối tác đã được kích hoạt.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Partner"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/partners/{id}:reject":{"post":{"operationId":"rejectPartner","summary":"Từ chối duyệt đối tác","tags":["Đối tác"],"security":[{"bearerAuth":[]}],"x-dt-permission":"partner.approve","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PartnerId"},"required":true,"description":"Mã đối tác sàn/hãng/CTV (`ptn_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"reason":"Thiếu hồ sơ pháp lý của đối tác"},"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"]}}}},"responses":{"200":{"description":"Đối tác đã bị từ chối.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Partner"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/partners/{id}/members:import":{"post":{"operationId":"importPartnerMembers","summary":"Nhập danh sách thành viên CTV","description":"Nhập file Excel chứa tên, MST/CCCD, STK ngân hàng. Dữ liệu PII được mã hoá AES-256-GCM tại cột lưu trữ.","tags":["Đối tác"],"security":[{"bearerAuth":[]}],"x-dt-permission":"partner.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PartnerId"},"required":true,"description":"Mã đối tác sàn/hãng/CTV (`ptn_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"members":[{"name":"Nguyễn Văn An","tax_id":"8012345678","bank_account":"0123456789","bank_bin":"970436"}]},"schema":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"tax_id":{"type":"string","minLength":9,"maxLength":20},"bank_account":{"type":"string","minLength":4,"maxLength":30},"bank_bin":{"type":"string","maxLength":10},"ctv_code":{"type":"string","minLength":1,"maxLength":50,"description":"Mã CTV gắn trên đơn hàng; dùng để tính cờ thu nhập TNCN trong tháng."}},"required":["name","tax_id","bank_account"]}}},"required":["members"]}}}},"responses":{"200":{"description":"Kết quả nhập thành viên.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"imported":{"type":"integer"},"members":{"type":"array","items":{"$ref":"#/components/schemas/PartnerMember"}}},"required":["total","imported","members"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/partners/{id}/members":{"get":{"operationId":"listPartnerMembers","summary":"Danh sách thành viên CTV của đối tác","description":"STK và MST chỉ trả dạng đã che; bản đầy đủ nằm mã hoá trong cơ sở dữ liệu và không bao giờ ra ngoài API.","tags":["Đối tác"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-scope":"settlement:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PartnerId"},"required":true,"description":"Mã đối tác sàn/hãng/CTV (`ptn_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Thành viên của đối tác.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PartnerMember"}}},"required":["items"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/connections":{"get":{"operationId":"listConnections","summary":"Danh sách kết nối gian hàng","tags":["Đối tác"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-scope":"settlement:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PartnerId"},"required":false,"description":"Mã đối tác sàn/hãng/CTV (`ptn_…`).","name":"partner_id","in":"query"}],"responses":{"200":{"description":"Danh sách kết nối.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PlatformConnection"}}},"required":["data"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"operationId":"upsertConnection","summary":"Tạo hoặc cập nhật kết nối gian hàng","tags":["Đối tác"],"security":[{"bearerAuth":[]}],"x-dt-permission":"partner.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertConnectionBody"}}}},"responses":{"200":{"description":"Kết nối đã được lưu.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformConnection"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/settlement/connections/{id}:reconnect":{"post":{"operationId":"reconnectConnection","summary":"Cấp lại xác thực OAuth gian hàng","tags":["Đối tác"],"security":[{"bearerAuth":[]}],"x-dt-permission":"partner.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PlatformConnectionId"},"required":true,"description":"Mã kết nối gian hàng (`plc_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Đường dẫn cấp lại xác thực.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"auth_url":{"type":"string","format":"uri"}},"required":["auth_url"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/split-rules":{"get":{"operationId":"listSplitRules","summary":"Danh sách quy tắc chia doanh thu","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-scope":"settlement:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/PartnerId"},"required":false,"description":"Mã đối tác sàn/hãng/CTV (`ptn_…`).","name":"partner_id","in":"query"},{"schema":{"$ref":"#/components/schemas/SplitRuleKind"},"required":false,"description":"`payable_brand` phải trả hãng/nhà cung cấp · `payable_ctv` phải trả CTV · `receivable_agent` phải thu đại lý.","name":"kind","in":"query"}],"responses":{"200":{"description":"Danh sách quy tắc chia.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitRuleList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createSplitRule","summary":"Tạo quy tắc chia doanh thu","description":"Tạo quy tắc chia và phiên bản v1 ban đầu ở trạng thái `draft`.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"split_rule.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSplitRuleBody"}}}},"responses":{"201":{"description":"Quy tắc chia đã tạo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitRule"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/settlement/split-rules/{id}":{"get":{"operationId":"getSplitRule","summary":"Chi tiết quy tắc chia","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-scope":"settlement:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/SplitRuleId"},"required":true,"description":"Mã quy tắc chia doanh thu (`spl_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Chi tiết quy tắc và các phiên bản.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitRule"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/split-rules/{id}/versions":{"post":{"operationId":"createSplitRuleVersion","summary":"Tạo phiên bản quy tắc mới","description":"Phiên bản mới chờ duyệt; phiên bản cũ vẫn hoạt động cho đến ngày hiệu lực của phiên bản mới.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"split_rule.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/SplitRuleId"},"required":true,"description":"Mã quy tắc chia doanh thu (`spl_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSplitRuleVersionBody"}}}},"responses":{"201":{"description":"Phiên bản mới đã tạo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitRuleVersion"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/split-rules/{id}/versions/{vid}:approve":{"post":{"operationId":"approveSplitRuleVersion","summary":"Duyệt phiên bản quy tắc","description":"Maker-checker: Người duyệt phải khác người tạo phiên bản. Trả `409 conflict` khi phiên bản chồng lấn điều kiện với quy tắc đang áp dụng cùng loại mà cùng mức ưu tiên và cùng ngày hiệu lực (không xác định được quy tắc nào thắng); trường hợp còn lại trả `lint_warnings`.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"split_rule.approve","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/SplitRuleId"},"required":true,"description":"Mã quy tắc chia doanh thu (`spl_…`).","name":"id","in":"path"},{"schema":{"$ref":"#/components/schemas/SplitRuleVersionId"},"required":true,"description":"Mã phiên bản quy tắc chia (`spv_…`).","name":"vid","in":"path"}],"responses":{"200":{"description":"Phiên bản đã duyệt.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitRuleVersion"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/split-rules/{id}/versions/{vid}:reject":{"post":{"operationId":"rejectSplitRuleVersion","summary":"Từ chối phiên bản quy tắc","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"split_rule.approve","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/SplitRuleId"},"required":true,"description":"Mã quy tắc chia doanh thu (`spl_…`).","name":"id","in":"path"},{"schema":{"$ref":"#/components/schemas/SplitRuleVersionId"},"required":true,"description":"Mã phiên bản quy tắc chia (`spv_…`).","name":"vid","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"reason":"Tỷ lệ chia chưa đúng hợp đồng ký gửi"},"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"]}}}},"responses":{"200":{"description":"Phiên bản đã bị từ chối.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitRuleVersion"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/obligations":{"get":{"operationId":"listObligations","summary":"Danh sách nghĩa vụ thanh toán","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-scope":"settlement:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/PartnerId"},"required":false,"description":"Mã đối tác sàn/hãng/CTV (`ptn_…`).","name":"partner_id","in":"query"},{"schema":{"$ref":"#/components/schemas/ObligationDirection"},"required":false,"description":"`in` phải thu · `out` phải trả.","name":"direction","in":"query"},{"schema":{"$ref":"#/components/schemas/ObligationState"},"required":false,"description":"`not_due` chưa đến hạn · `awaiting_payout` chờ payout · `partially_settled` đã gạch một phần · `settled` tất toán · `variance` chênh lệch.","name":"state","in":"query"},{"schema":{"type":"string","description":"Chỉ nghĩa vụ đã quá hạn.","enum":["true","false"],"default":"false"},"required":false,"description":"Chỉ nghĩa vụ đã quá hạn.","name":"is_overdue","in":"query"}],"responses":{"200":{"description":"Danh sách nghĩa vụ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObligationList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/obligations/{id}":{"get":{"operationId":"getObligation","summary":"Chi tiết nghĩa vụ thanh toán","description":"Bao gồm chi tiết các dòng cấu thành và các đợt gạch nợ.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-scope":"settlement:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ObligationId"},"required":true,"description":"Mã nghĩa vụ thanh toán (`obl_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Chi tiết nghĩa vụ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ObligationId"},"code":{"type":"string","pattern":"^OB-\\d{4}-\\d{4}$"},"org_id":{"$ref":"#/components/schemas/OrgId"},"direction":{"$ref":"#/components/schemas/ObligationDirection"},"partner_id":{"$ref":"#/components/schemas/PartnerId"},"partner_name":{"type":"string"},"total":{"$ref":"#/components/schemas/PositiveVnd"},"paid":{"$ref":"#/components/schemas/Vnd"},"left":{"$ref":"#/components/schemas/Vnd"},"state":{"$ref":"#/components/schemas/ObligationState"},"is_overdue":{"type":"boolean","default":false},"due_date":{"$ref":"#/components/schemas/Date"},"source":{"$ref":"#/components/schemas/ObligationSource"},"split_rule_id":{"anyOf":[{"$ref":"#/components/schemas/SplitRuleId"},{"type":"null"}]},"split_rule_version":{"type":["integer","null"]},"composition":{"$ref":"#/components/schemas/ObligationComposition"},"suggested_memo":{"type":"string","pattern":"^DTP[0-9A-HJKMNP-TV-Z]{6}$"},"payout_id":{"anyOf":[{"$ref":"#/components/schemas/PayoutId"},{"type":"null"}]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ObligationLine"}},"allocations":{"type":"array","items":{"$ref":"#/components/schemas/ObligationAllocation"}}},"required":["id","code","org_id","direction","partner_id","total","state","due_date","source","created_at","updated_at","lines","allocations"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/obligations/{id}/allocations":{"post":{"operationId":"createObligationAllocation","summary":"Tạo gạch nợ nghĩa vụ với giao dịch ngân hàng","description":"Tạo yêu cầu gạch nợ: chỉ giao dịch đã xác thực (`verified`), đúng chiều (phải thu ⇒ tiền vào, phải trả ⇒ tiền ra), tổng gạch không vượt số tiền giao dịch và số dư còn lại của nghĩa vụ. Trả thừa cần `overpay_handling` và luôn qua duyệt.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"obligation_allocation.create","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ObligationId"},"required":true,"description":"Mã nghĩa vụ thanh toán (`obl_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateObligationAllocationBody"}}}},"responses":{"201":{"description":"Yêu cầu gạch nợ đã tạo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObligationAllocation"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/obligations/allocations/{aid}:approve":{"post":{"operationId":"approveObligationAllocation","summary":"Duyệt gạch nợ nghĩa vụ","description":"Checker duyệt allocation: ghi bút toán hai chân vào sổ nghĩa vụ `settlement_entries` / `settlement_lines` (append-only) và cập nhật số tiền đã gạch.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"obligation_allocation.approve","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ObligationAllocationId"},"required":true,"description":"Mã gạch nợ nghĩa vụ (`ola_…`).","name":"aid","in":"path"}],"requestBody":{"content":{"application/json":{"example":{},"schema":{"type":"object","properties":{"biometric_assertion":{"type":"object","properties":{"key_id":{"type":"string","minLength":1,"maxLength":128},"nonce":{"type":"string","pattern":"^[0-9a-fA-F]+$"},"signature":{"type":"string","pattern":"^[0-9a-fA-F]+$"}},"required":["key_id","nonce","signature"]}}}}}},"responses":{"200":{"description":"Gạch nợ đã duyệt thành công.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObligationAllocation"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/obligations/allocations/{aid}:reject":{"post":{"operationId":"rejectObligationAllocation","summary":"Từ chối gạch nợ nghĩa vụ","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"obligation_allocation.approve","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ObligationAllocationId"},"required":true,"description":"Mã gạch nợ nghĩa vụ (`ola_…`).","name":"aid","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"reason":"Giao dịch ngân hàng không thuộc nghĩa vụ này"},"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"]}}}},"responses":{"200":{"description":"Gạch nợ đã bị từ chối.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObligationAllocation"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/obligations/allocations/{aid}:reverse":{"post":{"operationId":"reverseObligationAllocation","summary":"Đảo gạch nợ đã duyệt","description":"Ghi bút toán đảo (append-only) cho gạch nợ đã duyệt và trả lại số dư còn lại của nghĩa vụ. Cần lý do. Kỳ kế toán đã khoá: bút toán đảo được ghi vào kỳ mở kế tiếp.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"obligation_allocation.approve","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ObligationAllocationId"},"required":true,"description":"Mã gạch nợ nghĩa vụ (`ola_…`).","name":"aid","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"reason":"Gạch nhầm giao dịch"},"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"]}}}},"responses":{"200":{"description":"Gạch nợ đã được đảo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObligationAllocation"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/obligations/allocations:bulk-approve":{"post":{"operationId":"bulkApproveObligationAllocations","summary":"Duyệt hàng loạt gạch nợ","description":"Duyệt qua danh sách allocation, mỗi bản ghi kiểm tra độc lập quy tắc maker-checker.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"obligation_allocation.approve","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"allocation_ids":{"type":"array","items":{"$ref":"#/components/schemas/ObligationAllocationId"},"minItems":1,"maxItems":100}},"required":["allocation_ids"]}}}},"responses":{"200":{"description":"Kết quả duyệt hàng loạt.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"approved_count":{"type":"integer"},"rejected_count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ObligationAllocationId"},"status":{"type":"string","enum":["approved","failed"]},"error":{"type":"string"}},"required":["id","status"]}}},"required":["approved_count","rejected_count","results"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/settlement/obligations/{id}:remind":{"post":{"operationId":"remindObligation","summary":"Gửi nhắc nợ đối tác","description":"Gửi email nhắc khoản phải thu/phải trả quá hạn tới địa chỉ liên hệ của đối tác (qua dt-notify, không lặp trong cùng ngày).","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ObligationId"},"required":true,"description":"Mã nghĩa vụ thanh toán (`obl_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"recipient_email":"ketoan@congtyabc.vn"},"schema":{"type":"object","properties":{"recipient_email":{"type":"string","format":"email","description":"Email liên hệ của đối tác nhận nhắc."}},"required":["recipient_email"]}}}},"responses":{"200":{"description":"Đã gửi nhắc thành công.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"sent":{"type":"boolean"},"channel":{"type":"string"}},"required":["sent","channel"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/obligations/{id}:statement-send":{"post":{"operationId":"sendStatement","summary":"Gửi bảng kê đối soát qua email","description":"Tạo bảng kê Excel kèm chữ ký HMAC `statement_hash` và gửi email cho đối tác.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ObligationId"},"required":true,"description":"Mã nghĩa vụ thanh toán (`obl_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"recipient_email":"ketoan@congtyabc.vn","note":"Bảng kê kỳ 01-15/10/2026"},"schema":{"type":"object","properties":{"recipient_email":{"type":"string","format":"email"},"note":{"type":"string","maxLength":500}},"required":["recipient_email"]}}}},"responses":{"200":{"description":"Email bảng kê đã được gửi.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"sent":{"type":"boolean"},"statement_hash":{"type":"string"},"expires_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["sent","statement_hash","expires_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/payouts":{"get":{"operationId":"listPayouts","summary":"Danh sách đợt quyết toán / sao kê sàn","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-scope":"settlement:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/SettlementPlatform"},"required":false,"description":"Sàn thương mại điện tử: `shopee` · `tiktok` · `lazada`.","name":"platform","in":"query"},{"schema":{"$ref":"#/components/schemas/PayoutState"},"required":false,"description":"`matched` khớp tuyệt đối · `variance` lệch N đ · `awaiting_payout` chờ tiền về · `provisional` tạm tính (chỉ SMS/email) · `orphan_credit` thừa/thiếu statement.","name":"state","in":"query"}],"responses":{"200":{"description":"Danh sách đợt quyết toán.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/payouts/{id}":{"get":{"operationId":"getPayout","summary":"Chi tiết đợt quyết toán","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-scope":"settlement:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PayoutId"},"required":true,"description":"Mã đợt quyết toán sàn (`pay_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Chi tiết đợt quyết toán.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PayoutId"},"platform":{"$ref":"#/components/schemas/SettlementPlatform"},"shop_id":{"type":"string","minLength":1,"maxLength":64},"period":{"type":"string","description":"Kỳ quyết toán (vd: 2026-10-A, 2026-W42)"},"statement_ref":{"type":"string","minLength":1,"maxLength":120},"statement_amount":{"$ref":"#/components/schemas/Vnd"},"state":{"$ref":"#/components/schemas/PayoutState"},"source":{"$ref":"#/components/schemas/PayoutSource"},"bank_tx_id":{"anyOf":[{"$ref":"#/components/schemas/TxId"},{"type":"null"}]},"diff":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"default":0,"description":"Chênh lệch: số tiền thực nhận tại bank - số tiền trên sao kê","example":4500000},"confidence":{"type":"integer","minimum":0,"maximum":100},"ai_cause":{"type":["object","null"],"additionalProperties":{}},"obligation_id":{"anyOf":[{"$ref":"#/components/schemas/ObligationId"},{"type":"null"}]},"lines_count":{"type":"integer","minimum":0},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/PayoutLine"}}},"required":["id","platform","shop_id","period","statement_ref","statement_amount","state","source","created_at","updated_at","lines"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/statements:import":{"post":{"operationId":"importSettlementStatement","summary":"Tải lên tệp sao kê sàn (Shopee, TikTok, Lazada)","description":"Tải tệp Excel/CSV sao kê sàn (`multipart/form-data`, tối đa 25 MB): niêm phong và lưu R2, tạo tác vụ `payout`, đọc 5.000 đơn/trang, xem trước rồi chờ lệnh `commit`, sau đó khớp với giao dịch ngân hàng đã xác thực. Nhập lại cùng `statement_ref` sẽ gộp, không trùng đơn/đợt. Không tính quota billing (D33). Quá 25 MB: `413`; tệp rỗng: `422`.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payout.import","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Tệp sao kê sàn (.xlsx hoặc .csv), tối đa 25 MB. Sàn, gian hàng và mã sao kê được nhận dạng từ nội dung tệp."}},"required":["file"]}}}},"responses":{"202":{"description":"Job import sao kê đã được tiếp nhận.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementImport"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/settlement/statements/{id}":{"get":{"operationId":"getSettlementImport","summary":"Trạng thái nhập sao kê sàn","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payout.import","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/StatementImportId"},"required":true,"description":"Mã lần nhập sao kê (`imp_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Trạng thái và bản xem trước.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementImport"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/statements/{id}:commit":{"post":{"operationId":"commitSettlementImport","summary":"Xác nhận nhập sao kê sàn","description":"Chỉ khi tác vụ ở `preview_ready`. Workflow ghi đơn và đợt payout theo từng trang rồi khớp với giao dịch ngân hàng.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payout.import","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/StatementImportId"},"required":true,"description":"Mã lần nhập sao kê (`imp_…`).","name":"id","in":"path"}],"responses":{"202":{"description":"Đã nhận lệnh nhập.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementImport"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/payouts/{id}:assign-statement":{"post":{"operationId":"assignPayoutStatement","summary":"Gán thủ công giao dịch ngân hàng vào đợt payout","description":"Dành cho trường hợp orphan_credit hoặc cần khớp thủ công, bắt buộc ghi rõ lý do để ghi nhận chuỗi audit.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payout.import","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PayoutId"},"required":true,"description":"Mã đợt quyết toán sàn (`pay_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"tx_id":"tx_0f5k2m9q4h7t3n8r6v1w0x5yz0","reason":"Khoản tiền về từ Shopee không kèm mã payout"},"schema":{"type":"object","properties":{"tx_id":{"$ref":"#/components/schemas/TxId"},"reason":{"type":"string","minLength":5,"maxLength":500}},"required":["tx_id","reason"]}}}},"responses":{"200":{"description":"Payout đã được gán giao dịch.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/payouts/{id}:variance-recognition":{"post":{"operationId":"proposeVarianceRecognition","summary":"Đề xuất ghi nhận chênh lệch payout","description":"Tạo yêu cầu phê duyệt ghi nhận chênh lệch. Khi được duyệt, hệ thống sẽ sinh nghĩa vụ phải thu bù từ sàn.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payout.variance.propose","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PayoutId"},"required":true,"description":"Mã đợt quyết toán sàn (`pay_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"reason":"Sàn trừ phí vận chuyển không có trong biểu phí","note":"Chênh lệch 45.000đ"},"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500},"note":{"type":"string","maxLength":500}},"required":["reason"]}}}},"responses":{"200":{"description":"Yêu cầu ghi nhận chênh lệch đã gửi duyệt.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"approval_request_id":{"type":"string"},"state":{"type":"string"}},"required":["approval_request_id","state"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/payouts/{id}:variance-approve":{"post":{"operationId":"approveVarianceRecognition","summary":"Duyệt ghi nhận chênh lệch payout","description":"Checker duyệt ghi nhận chênh lệch: sinh nghĩa vụ phải thu sàn tương ứng.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payout.variance.approve","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PayoutId"},"required":true,"description":"Mã đợt quyết toán sàn (`pay_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Đã duyệt chênh lệch.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/payouts/{id}:variance-claim-export":{"post":{"operationId":"exportVarianceClaim","summary":"Xuất tệp khiếu nại chênh lệch gửi sàn","description":"Xuất tệp Excel bảng kê khiếu nại (hệ thống không tự gửi ra ngoài, người dùng tự đính kèm khiếu nại sàn).","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payout.variance.propose","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PayoutId"},"required":true,"description":"Mã đợt quyết toán sàn (`pay_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Đường dẫn tải file khiếu nại.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"download_url":{"type":"string","format":"uri"},"expires_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["download_url","expires_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/payouts/{id}:reminder":{"post":{"operationId":"setPayoutReminder","summary":"Đặt hẹn nhắc tiền về cho đợt payout","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/PayoutId"},"required":true,"description":"Mã đợt quyết toán sàn (`pay_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"remind_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["remind_at"]}}}},"responses":{"200":{"description":"Đã đặt hẹn nhắc.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"scheduled":{"type":"boolean"}},"required":["scheduled"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/orders:import":{"post":{"operationId":"importSettlementOrders","summary":"Nhập danh sách đơn hàng xuất từ sàn","description":"Nhập danh sách đơn hàng (SKU, giá, phí, ngày giao) để phục vụ tính nghĩa vụ hãng/CTV theo `sku_brand_map`.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"payout.import","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"example":{"platform":"shopee","shop_id":"shopee_88123456","orders":[{"order_no":"2410215ABCD123","sku":"AO-THUN-DEN-L","revenue":350000,"platform_fee":38500,"voucher_seller":20000,"net_amount":291500,"delivered_at":"2026-10-18T09:30:00Z","ctv_code":"CTV-0123"}]},"schema":{"type":"object","properties":{"platform":{"$ref":"#/components/schemas/SettlementPlatform"},"shop_id":{"type":"string"},"orders":{"type":"array","items":{"type":"object","properties":{"order_no":{"type":"string"},"sku":{"type":"string"},"revenue":{"$ref":"#/components/schemas/Vnd"},"platform_fee":{"$ref":"#/components/schemas/Vnd"},"voucher_seller":{"$ref":"#/components/schemas/Vnd"},"net_amount":{"$ref":"#/components/schemas/Vnd"},"delivered_at":{"$ref":"#/components/schemas/Timestamp"},"ctv_code":{"type":"string"}},"required":["order_no","revenue","net_amount"]}}},"required":["platform","shop_id","orders"]}}}},"responses":{"200":{"description":"Kết quả nhập đơn hàng.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"processed":{"type":"integer"},"new_orders":{"type":"integer"},"exceptions_count":{"type":"integer"}},"required":["processed","new_orders","exceptions_count"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/settlement/sku-brand-map":{"get":{"operationId":"getSkuBrandMap","summary":"Lấy bảng ánh xạ SKU sang nhãn hàng / đối tác hãng","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-scope":"settlement:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Bảng ánh xạ SKU.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SkuBrandMap"}}},"required":["data"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"put":{"operationId":"putSkuBrandMap","summary":"Cập nhật bảng ánh xạ SKU sàn","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"partner.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","minLength":1,"maxLength":100},"brand":{"type":"string","minLength":1,"maxLength":100},"partner_id":{"$ref":"#/components/schemas/PartnerId"}},"required":["sku","brand"]}}},"required":["mappings"]}}}},"responses":{"200":{"description":"Đã lưu bảng ánh xạ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"saved_count":{"type":"integer"}},"required":["saved_count"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/settlement/reports/{kind}":{"get":{"operationId":"getSettlementReport","summary":"Báo cáo đối soát settlement (XLSX / PDF)","description":"Xuất báo cáo tuổi nợ, đối soát sàn, bảng kê đối tác kèm mã HMAC `statement_hash`, hoặc đối chiếu phí sàn thực tế với biểu phí.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-scope":"settlement:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/SettlementReportKind"},"required":true,"description":"Loại báo cáo đối soát: `receivable_payable_aging` tuổi nợ · `payout_reconciliation` đối soát sao kê sàn · `partner_statement` bảng kê đối tác/hãng · `platform_fee_actual` phí sàn thực trả vs biểu phí.","name":"kind","in":"path"},{"schema":{"type":"string","enum":["json","xlsx","pdf"],"default":"json"},"required":false,"name":"format","in":"query"},{"schema":{"$ref":"#/components/schemas/PartnerId"},"required":false,"description":"Mã đối tác sàn/hãng/CTV (`ptn_…`).","name":"partner_id","in":"query"},{"schema":{"$ref":"#/components/schemas/Date"},"required":false,"description":"Ngày lịch `YYYY-MM-DD` (giờ Việt Nam).","name":"from_date","in":"query"},{"schema":{"$ref":"#/components/schemas/Date"},"required":false,"description":"Ngày lịch `YYYY-MM-DD` (giờ Việt Nam).","name":"to_date","in":"query"}],"responses":{"200":{"description":"Dữ liệu báo cáo hoặc đường dẫn tải tệp.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/SettlementReportKind"},"as_of":{"$ref":"#/components/schemas/Timestamp"},"statement_hash":{"type":"string"},"summary":{"type":"object","additionalProperties":{}},"download_url":{"type":"string","format":"uri"}},"required":["kind","as_of","summary"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/report-files/{id}":{"get":{"operationId":"downloadSettlementReportFile","summary":"Tải tệp báo cáo đối soát (XLSX / PDF)","description":"Tệp do `GET /v1/settlement/reports/{kind}?format=xlsx|pdf` sinh ra, lưu bất biến trên R2 (PDF A4 ngang, phông Ferry VN Text nhúng). Cần phiên/khoá API có quyền `settlement.read` (không phải liên kết công khai); hết hạn sau 7 ngày trả `404`. Mỗi lần tải được ghi nhật ký kiểm toán.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-scope":"settlement:read","x-dt-rate-class":"export","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/SettlementReportId"},"required":true,"description":"Mã bản báo cáo đối soát (`srp_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Tệp XLSX hoặc PDF của báo cáo (theo `format` lúc sinh).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/report-schedules/{id}":{"put":{"operationId":"upsertReportSchedule","summary":"Cấu hình lịch tự động gửi báo cáo đối soát","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/SettlementReportScheduleId"},"required":true,"description":"Mã lịch báo cáo đối soát (`srs_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"kind":"partner_statement","cron":"0 8 5 * *","partner_id":"ptn_0f5k2m9q4h7t3n8r6v1w0x5yz0","recipients":["ketoan@congtyabc.vn"],"channel":"email","enabled":true},"schema":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/SettlementReportKind"},"cron":{"type":"string"},"partner_id":{"$ref":"#/components/schemas/PartnerId"},"recipients":{"type":"array","items":{"type":"string","format":"email"}},"channel":{"type":"string","enum":["email","in_app"],"default":"email"},"enabled":{"type":"boolean","default":true}},"required":["kind","cron","recipients"]}}}},"responses":{"200":{"description":"Lịch đã lưu thành công.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementReportSchedule"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/settlement/report-schedules":{"get":{"operationId":"listReportSchedules","summary":"Danh sách lịch tự động gửi báo cáo đối soát","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-scope":"settlement:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Các lịch báo cáo của tổ chức.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SettlementReportSchedule"}}},"required":["items"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/settlement/summary":{"get":{"operationId":"getSettlementSummary","summary":"Tổng quan đối soát","description":"Phải thu, phải trả (còn lại chưa gạch), hạn trả gần nhất, số đợt payout đã khớp và tổng chênh lệch.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-scope":"settlement:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Tổng quan đối soát của tổ chức.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementSummary"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/settlement/settings":{"get":{"operationId":"getSettlementSettings","summary":"Ngưỡng đối soát payout","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-scope":"settlement:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Ngưỡng hiện hành (mặc định 0 khi chưa lưu).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementSettings"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"put":{"operationId":"putSettlementSettings","summary":"Đặt ngưỡng đối soát payout","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"partner.approve","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"example":{"allowable_drift_vnd":5500,"variance_alert_threshold_vnd":50000},"schema":{"$ref":"#/components/schemas/SettlementSettings"}}}},"responses":{"200":{"description":"Đã lưu.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementSettings"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/settlement/upcoming-cash":{"get":{"operationId":"getUpcomingCash","summary":"Dòng tiền sắp về / sắp chi trong 7 ngày","description":"Feed dữ liệu nguồn `settlement` và `payout_lag` phục vụ biểu đồ và dự báo dòng tiền Phase 14.","tags":["Dòng tiền"],"security":[{"bearerAuth":[]}],"x-dt-permission":"settlement.read","x-dt-scope":"settlement:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách khoản tiền dự kiến trong 7 ngày tới.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UpcomingCashItem"}},"total_inflow":{"$ref":"#/components/schemas/PositiveVnd"},"total_outflow":{"$ref":"#/components/schemas/PositiveVnd"},"net_flow":{"$ref":"#/components/schemas/Vnd"}},"required":["items","total_inflow","total_outflow","net_flow"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/integrations/catalog":{"get":{"operationId":"getIntegrationCatalog","summary":"Danh mục 10 kênh tích hợp sẵn","description":"10 kind: Lark, Telegram, Slack, Discord, Custom Webhook, WooCommerce, Haravan, Shopify, Lark Base, Google Sheets kèm trạng thái cấu hình nền tảng.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.read","x-dt-scope":"integrations:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh mục các kênh tích hợp được hỗ trợ","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationCatalogItem"}}},"required":["items"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/integrations":{"get":{"operationId":"listIntegrations","summary":"Danh sách kết nối tích hợp","description":"Liệt kê các kênh tích hợp đã thiết lập trong công ty/tổ chức.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.read","x-dt-scope":"integrations:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"$ref":"#/components/schemas/IntegrationKind"},"required":false,"description":"Loại kênh / nền tảng tích hợp.","name":"kind","in":"query"},{"schema":{"$ref":"#/components/schemas/IntegrationState"},"required":false,"description":"Trạng thái tích hợp theo máy trạng thái state-machines.md §11.","name":"state","in":"query"}],"responses":{"200":{"description":"Danh sách tích hợp phân trang","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createIntegration","summary":"Tạo kết nối tích hợp mới","description":"Kết nối 1-2 bước: dán token/URL (draft -> connected), hoặc khởi tạo luồng OAuth (`oauth: true`, 202). Credential do adapter xác thực rồi được mã hoá niêm phong ngay; WooCommerce kết nối bằng mã từ plugin (`woocommerce:connect-code`), không dán credential.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.manage","x-dt-scope":"integrations:write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"example":{"kind":"telegram","name":"Telegram nhóm kế toán","credential":"7312456890:AAH_secret-token-from-BotFather"},"schema":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/IntegrationKind"},"name":{"type":"string","minLength":1,"maxLength":100},"credential":{"type":"string","description":"Token, Webhook URL, hoặc App Secret"},"external_ref":{"type":"string"},"settings":{"type":"object","additionalProperties":{}},"oauth":{"type":"boolean"}},"required":["kind","name"]}}}},"responses":{"201":{"description":"Kết nối đã tạo thành công","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Integration"}}}},"202":{"description":"Yêu cầu uỷ quyền OAuth","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/IntegrationId"},"authorize_url":{"type":"string","format":"uri"}},"required":["id","authorize_url"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integrations/{id}":{"get":{"operationId":"getIntegration","summary":"Chi tiết một kết nối tích hợp","description":"Xem cấu hình, trạng thái hoạt động và gợi nhớ credential (đã che).","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.read","x-dt-scope":"integrations:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationId"},"required":true,"description":"Mã tích hợp (`int_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Thông tin chi tiết kết nối tích hợp","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Integration"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"updateIntegration","summary":"Cập nhật thông tin kết nối tích hợp","description":"Cập nhật tên hoặc cấu hình `settings` (hợp nhất theo khoá, giá trị `null` xoá khoá). `external_ref` chỉ đặt được khi kết nối còn `draft`.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.manage","x-dt-scope":"integrations:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationId"},"required":true,"description":"Mã tích hợp (`int_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"name":"Telegram nhóm kế toán","settings":{"language":"vi"}},"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"settings":{"type":"object","additionalProperties":{}},"external_ref":{"type":"string"}}}}}},"responses":{"200":{"description":"Kết nối tích hợp sau cập nhật","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Integration"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteIntegration","summary":"Thu hồi / xoá kết nối tích hợp","description":"Chuyển trạng thái sang `revoked`, xoá vĩnh viễn credential niêm phong và huỷ webhook nền tảng.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.manage","x-dt-scope":"integrations:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationId"},"required":true,"description":"Mã tích hợp (`int_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Kết nối đã được thu hồi","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"state":{"type":"string","enum":["revoked"]}},"required":["ok","state"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integrations/{id}:test":{"post":{"operationId":"testIntegration","summary":"Gửi tin thử nghiệm [TEST]","description":"Gửi 1 tin mẫu đánh dấu [TEST] ra kênh để kiểm tra kết nối. Không kích hoạt nghiệp vụ, trả kết quả ngay kèm `idl_…`.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.test","x-dt-scope":"integrations:write","x-dt-rate-class":"replay","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationId"},"required":true,"description":"Mã tích hợp (`int_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Kết quả gửi thử","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResult"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integrations/{id}:pause":{"post":{"operationId":"pauseIntegration","summary":"Tạm dừng gửi thông báo","description":"Tạm ngưng phân phối sự kiện ra kênh ngoài.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.manage","x-dt-scope":"integrations:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationId"},"required":true,"description":"Mã tích hợp (`int_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Kết nối đã tạm dừng","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Integration"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integrations/{id}:resume":{"post":{"operationId":"resumeIntegration","summary":"Tiếp tục gửi thông báo","description":"Kích hoạt lại kết nối đang tạm dừng.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.manage","x-dt-scope":"integrations:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationId"},"required":true,"description":"Mã tích hợp (`int_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Kết nối đã tiếp tục hoạt động","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Integration"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integrations/{id}:rotate-credential":{"post":{"operationId":"rotateIntegrationCredential","summary":"Xoay / đổi credential kết nối","description":"Đổi token / webhook URL mới. Yêu cầu xác thực bảo mật nâng cao (step-up ≤15′).","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.credential.rotate","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationId"},"required":true,"description":"Mã tích hợp (`int_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"credential":"7312456890:AAH_new-token-from-BotFather"},"schema":{"type":"object","properties":{"credential":{"type":"string","minLength":1},"settings":{"type":"object","additionalProperties":{}}},"required":["credential"]}}}},"responses":{"200":{"description":"Credential đã được xoay thành công","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Integration"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integrations/{id}/rules":{"get":{"operationId":"listIntegrationRules","summary":"Danh sách quy tắc lọc sự kiện","description":"Lấy các quy tắc định tuyến, lọc tiền, MST, mã đơn riêng (D51) và số dư (D49).","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.read","x-dt-scope":"integrations:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationId"},"required":true,"description":"Mã tích hợp (`int_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Danh sách quy tắc của kết nối","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationRule"}}},"required":["items"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createIntegrationRule","summary":"Tạo quy tắc gửi thông báo","description":"Cấu hình sự kiện, bộ lọc (tài khoản, chiều, số tiền, memo_pattern_id D51, show_balance D49) và mẫu tin.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.manage","x-dt-scope":"integrations:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationId"},"required":true,"description":"Mã tích hợp (`int_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"name":"Báo tiền về trên 5 triệu","events":["transaction.confirmed"],"filters":{"direction":"in","min_amount":5000000},"show_balance":false,"enabled":true},"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"events":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationEventType"},"minItems":1},"filters":{"$ref":"#/components/schemas/IntegrationRuleFilters"},"template_id":{"type":"string","format":"uuid"},"target":{"type":"object","additionalProperties":{}},"quiet_hours":{"type":"object","properties":{"enabled":{"type":"boolean"},"start":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"end":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"timezone":{"type":"string","default":"Asia/Ho_Chi_Minh"}},"required":["enabled","start","end"]},"show_balance":{"type":"boolean","default":false},"enabled":{"type":"boolean","default":true}},"required":["name","events","filters"]}}}},"responses":{"201":{"description":"Quy tắc được tạo thành công","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationRule"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integrations/{id}/rules/{rid}":{"patch":{"operationId":"updateIntegrationRule","summary":"Cập nhật quy tắc gửi","description":"Chỉnh sửa bộ lọc hoặc bật/tắt quy tắc.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.manage","x-dt-scope":"integrations:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationId"},"required":true,"description":"Mã tích hợp (`int_…`).","name":"id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Mã quy tắc (`rule_id`)"},"required":true,"description":"Mã quy tắc (`rule_id`)","name":"rid","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"events":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationEventType"},"minItems":1},"filters":{"$ref":"#/components/schemas/IntegrationRuleFilters"},"template_id":{"type":["string","null"],"format":"uuid"},"target":{"type":"object","additionalProperties":{}},"quiet_hours":{"type":"object","properties":{"enabled":{"type":"boolean"},"start":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"end":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"timezone":{"type":"string","default":"Asia/Ho_Chi_Minh"}},"required":["enabled","start","end"]},"show_balance":{"type":"boolean"},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Quy tắc sau cập nhật","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationRule"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteIntegrationRule","summary":"Xoá quy tắc gửi","description":"Xoá một quy tắc lọc sự kiện.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.manage","x-dt-scope":"integrations:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationId"},"required":true,"description":"Mã tích hợp (`int_…`).","name":"id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Mã quy tắc (`rule_id`)"},"required":true,"description":"Mã quy tắc (`rule_id`)","name":"rid","in":"path"}],"responses":{"200":{"description":"Xoá quy tắc thành công","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integrations/{id}/rules/{rid}:preview":{"post":{"operationId":"previewIntegrationRule","summary":"Xem trước kết quả khớp và nội dung tin","description":"Thử nghiệm quy tắc với giao dịch thực tế gần nhất (đã che) hoặc giao dịch mẫu để kiểm tra bộ lọc.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.read","x-dt-scope":"integrations:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationId"},"required":true,"description":"Mã tích hợp (`int_…`).","name":"id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Mã quy tắc (`rule_id`)"},"required":true,"description":"Mã quy tắc (`rule_id`)","name":"rid","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"sample_tx_id":"tx_0f5k2m9q4h7t3n8r6v1w0x5yz0"},"schema":{"type":"object","properties":{"sample_tx_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Kết quả xem trước bộ lọc và bản tin","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"matched":{"type":"boolean"},"skip_reason":{"type":"string"},"rendered_preview":{"type":"string"}},"required":["matched"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integration-templates":{"get":{"operationId":"listIntegrationTemplates","summary":"Danh sách mẫu tin tiếng Việt","description":"Lấy các mẫu tin mặc định của hệ thống và mẫu ghi đè theo công ty.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.read","x-dt-scope":"integrations:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationKind"},"required":false,"description":"Loại kênh / nền tảng tích hợp.","name":"kind","in":"query"},{"schema":{"type":"string"},"required":false,"name":"event","in":"query"}],"responses":{"200":{"description":"Danh sách mẫu tin","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationTemplate"}}},"required":["items"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createIntegrationTemplate","summary":"Tạo mẫu tin nhắn tuỳ chỉnh","description":"Tạo bản mẫu tin ghi đè cho tổ chức.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.manage","x-dt-scope":"integrations:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"example":{"kind":"telegram","event":"transaction.confirmed","body":"Đã nhận {amount} từ {counterparty_name}. Nội dung: {memo}","locale":"vi"},"schema":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/IntegrationKind"},"event":{"$ref":"#/components/schemas/IntegrationEventType"},"body":{"type":"string","minLength":1},"locale":{"type":"string","enum":["vi"],"default":"vi"}},"required":["kind","event","body"]}}}},"responses":{"201":{"description":"Mẫu tin được tạo","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationTemplate"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/integration-templates/{id}":{"patch":{"operationId":"updateIntegrationTemplate","summary":"Cập nhật mẫu tin tuỳ chỉnh","description":"Sửa đổi nội dung mẫu tin của tổ chức.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.manage","x-dt-scope":"integrations:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"body":"Đã nhận {amount} từ {counterparty_name}. Nội dung: {memo}"},"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1}},"required":["body"]}}}},"responses":{"200":{"description":"Mẫu tin sau khi cập nhật","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationTemplate"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integrations/{id}/deliveries":{"get":{"operationId":"listIntegrationDeliveries","summary":"Nhật ký gửi tin tích hợp (30 ngày)","description":"Xem lịch sử phân phối sự kiện, mã trạng thái HTTP, độ trễ và bản xem trước đã che.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.read","x-dt-scope":"integrations:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationId"},"required":true,"description":"Mã tích hợp (`int_…`).","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"`true`: chỉ lượt gửi thử; `false`: chỉ lượt gửi thật."},"required":false,"description":"`true`: chỉ lượt gửi thử; `false`: chỉ lượt gửi thật.","name":"is_test","in":"query"}],"responses":{"200":{"description":"Danh sách lịch sử gửi tin","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationDeliveryList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integration-deliveries/{idl}":{"get":{"operationId":"getIntegrationDelivery","summary":"Chi tiết một lần gửi tin","description":"Xem chi tiết lỗi, phản hồi và thời gian thử lại.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.read","x-dt-scope":"integrations:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationDeliveryId"},"required":true,"description":"Mã lượt gửi tin tích hợp (`idl_…`).","name":"idl","in":"path"}],"responses":{"200":{"description":"Chi tiết lượt gửi tin","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationDelivery"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integration-deliveries/{idl}:replay":{"post":{"operationId":"replayIntegrationDelivery","summary":"Gửi lại một lượt tin thất bại","description":"Đưa bản tin thất bại vào hàng đợi gửi lại.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.replay","x-dt-scope":"integrations:write","x-dt-rate-class":"replay","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationDeliveryId"},"required":true,"description":"Mã lượt gửi tin tích hợp (`idl_…`).","name":"idl","in":"path"}],"responses":{"200":{"description":"Bản tin đã được đưa vào hàng đợi gửi lại","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"delivery_id":{"$ref":"#/components/schemas/IntegrationDeliveryId"},"state":{"type":"string","enum":["queued"]}},"required":["ok","delivery_id","state"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integrations/{id}/deliveries:replay-failed":{"post":{"operationId":"replayFailedIntegrationDeliveries","summary":"Gửi lại hàng loạt tin thất bại","description":"Gửi lại theo 3 nhóm (Chặn | Chờ | Sẵn sàng). Hỗ trợ dry_run kiểm tra số lượng trước.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.replay","x-dt-scope":"integrations:write","x-dt-rate-class":"replay","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationId"},"required":true,"description":"Mã tích hợp (`int_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"group":{"type":"string","enum":["blocked","waiting","ready"]},"dry_run":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Kết quả gửi lại hàng loạt","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"replayed_count":{"type":"integer","minimum":0},"dry_run":{"type":"boolean"},"groups":{"type":"object","additionalProperties":{"type":"number"}}},"required":["replayed_count","dry_run"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integrations/oauth/{kind}/start":{"get":{"operationId":"startIntegrationOAuth","summary":"Khởi tạo kết nối OAuth cho kênh ngoài","description":"Hỗ trợ Slack, Shopify, Haravan, Google Sheets (D49). Người dùng đã đăng nhập sinh `state` dùng một lần (10 phút; Google Sheets và Haravan kèm PKCE S256) và nhận URL cấp quyền của nền tảng.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.manage","x-dt-scope":"integrations:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","enum":["slack","shopify","haravan","google_sheets"]},"required":true,"name":"kind","in":"path"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"type":"string","description":"Tên miền shop Shopify/Haravan"},"required":false,"description":"Tên miền shop Shopify/Haravan","name":"shop","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Tên hiển thị của kết nối sẽ tạo"},"required":false,"description":"Tên hiển thị của kết nối sẽ tạo","name":"name","in":"query"},{"schema":{"type":"string","format":"uri","description":"Địa chỉ cùng origin với ứng dụng web để chuyển trình duyệt về sau khi uỷ quyền xong"},"required":false,"description":"Địa chỉ cùng origin với ứng dụng web để chuyển trình duyệt về sau khi uỷ quyền xong","name":"redirect_url","in":"query"}],"responses":{"200":{"description":"URL chuyển hướng cấp quyền","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"authorize_url":{"type":"string","format":"uri"},"state":{"type":"string"}},"required":["authorize_url","state"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integrations/oauth/{kind}/callback":{"get":{"operationId":"callbackIntegrationOAuth","summary":"Callback hoàn tất OAuth từ nền tảng ngoài","description":"Nền tảng chuyển trình duyệt về đây. Quyền duy nhất là `state` 256 bit dùng một lần (không cần phiên): route xác thực HMAC/PKCE, đổi mã lấy token, niêm phong và kích hoạt tích hợp. Khi lúc bắt đầu có `redirect_url` thì trả `302` về địa chỉ đó kèm `result=ok&integration=int_…`, ngược lại trả JSON. Mọi lỗi là problem+json.","tags":["Tích hợp"],"security":[],"x-dt-permission":"public","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","enum":["slack","shopify","haravan","google_sheets"]},"required":true,"name":"kind","in":"path"},{"schema":{"type":"string"},"required":false,"name":"code","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":512},"required":true,"name":"state","in":"query"},{"schema":{"type":"string"},"required":false,"name":"shop","in":"query"},{"schema":{"type":"string"},"required":false,"name":"hmac","in":"query"},{"schema":{"type":"string","maxLength":128},"required":false,"name":"error","in":"query"}],"responses":{"200":{"description":"Uỷ quyền thành công","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"integration_id":{"$ref":"#/components/schemas/IntegrationId"}},"required":["ok","integration_id"]}}}},"302":{"description":"Chuyển về `redirect_url` đã khai báo lúc bắt đầu."},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integrations/telegram:link-code":{"post":{"operationId":"telegramLinkCode","summary":"Tạo mã kết nối Telegram 1 bước","description":"Sinh mã kết nối 10 phút. Khách chỉ cần mở bot @DongTienProBot và bấm Start để tự động điền chat_id.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.manage","x-dt-scope":"integrations:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"example":{"name":"Nhóm kế toán Công ty ABC"},"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100}}}}}},"responses":{"200":{"description":"Mã kết nối và đường dẫn bot","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"bot_username":{"type":"string"},"deep_link":{"type":"string","format":"uri"},"expires_at":{"type":"string"}},"required":["code","bot_username","deep_link","expires_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/integrations/telegram:resolve-chat":{"get":{"operationId":"telegramResolveChat","summary":"Tìm chat_id cho bot riêng Telegram","description":"Gọi getUpdates để tự động tìm chat_id cho khách dùng bot riêng (không lưu token khi chưa tạo).","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.manage","x-dt-scope":"integrations:write","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","pattern":"^\\d{8,10}:[A-Za-z0-9_-]{35}$"},"required":true,"name":"token","in":"query"}],"responses":{"200":{"description":"Thông tin chat tìm được","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"chat_id":{"type":"string"},"chat_title":{"type":"string"},"chat_type":{"type":"string"}},"required":["chat_id","chat_type"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integrations/woocommerce:connect-code":{"post":{"operationId":"woocommerceConnectCode","summary":"Tạo mã kết nối một lần cho plugin WooCommerce","description":"Người dùng đã đăng nhập khai báo địa chỉ website (https). Mã dùng một lần, hiệu lực 10 phút, gắn với công ty và website đó; plugin đổi mã ở `woocommerce:exchange`.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.manage","x-dt-scope":"integrations:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"example":{"site_url":"https://cuahang.example.vn"},"schema":{"type":"object","properties":{"site_url":{"type":"string","format":"uri"}},"required":["site_url"]}}}},"responses":{"200":{"description":"Mã kết nối và hạn dùng","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"expires_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["code","expires_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/integrations/woocommerce:exchange":{"post":{"operationId":"woocommerceExchange","summary":"Đổi mã kết nối 1 bước từ WooCommerce","description":"Plugin WooCommerce (không có phiên đăng nhập) đổi mã kết nối lấy API key `dt_live_…` và signing secret. Quyền duy nhất là mã: dùng một lần, 10 phút, chỉ hợp lệ cho website đã khai báo. Hai giá trị bí mật chỉ xuất hiện trong phản hồi này (`Cache-Control: no-store`).","tags":["Tích hợp"],"security":[],"x-dt-permission":"public","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"example":{"code":"WC-4F7K9Q2M","site_url":"https://cuahang.example.vn","store_name":"Cửa hàng Hoa Sen"},"schema":{"type":"object","properties":{"code":{"type":"string","minLength":8,"maxLength":64},"site_url":{"type":"string","format":"uri"},"store_name":{"type":"string","minLength":1,"maxLength":100}},"required":["code","site_url"]}}}},"responses":{"200":{"description":"Thông tin kết nối cho plugin","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"integration_id":{"$ref":"#/components/schemas/IntegrationId"},"api_key":{"type":"string"},"signing_secret":{"type":"string"}},"required":["ok","integration_id","api_key","signing_secret"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/integrations/{id}/orders":{"get":{"operationId":"listCommerceOrders","summary":"Danh sách đơn hàng thương mại","description":"Xem các đơn hàng đã đồng bộ và trạng thái ghi nhận thanh toán ngược lại shop.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.read","x-dt-scope":"integrations:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationId"},"required":true,"description":"Mã tích hợp (`int_…`).","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"$ref":"#/components/schemas/CommerceOrderWritebackState"},"required":false,"description":"Trạng thái ghi nhận ngược lại đơn hàng ở cửa hàng (Woo/Shopify/Haravan).","name":"writeback_state","in":"query"}],"responses":{"200":{"description":"Danh sách đơn hàng","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommerceOrderList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integrations/{id}/orders/{oid}:retry-writeback":{"post":{"operationId":"retryCommerceOrderWriteback","summary":"Thử lại ghi ngược trạng thái đơn hàng","description":"Thử ghi nhận thanh toán lại cho đơn hàng bị lỗi writeback_state='failed'. Chỉ áp dụng cho giao dịch verified.","tags":["Tích hợp"],"security":[{"bearerAuth":[]}],"x-dt-permission":"integration.manage","x-dt-scope":"integrations:write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/IntegrationId"},"required":true,"description":"Mã tích hợp (`int_…`).","name":"id","in":"path"},{"schema":{"type":"string","description":"Mã đơn hàng nội bộ hoặc external_order_id"},"required":true,"description":"Mã đơn hàng nội bộ hoặc external_order_id","name":"oid","in":"path"}],"responses":{"200":{"description":"Kết quả thử ghi lại","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"writeback_state":{"$ref":"#/components/schemas/CommerceOrderWritebackState"}},"required":["ok","writeback_state"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/notification-prefs":{"get":{"operationId":"getNotificationPrefs","summary":"Cài đặt thông báo của cá nhân","description":"Lấy tuỳ chọn kênh, ngưỡng tiền vào, giờ yên lặng theo từng loại sự kiện của người dùng đang đăng nhập.","tags":["Thông báo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.pref.self","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách thiết lập thông báo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["notification_prefs"]},"prefs":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string","description":"Loại sự kiện (tx.in, tx.out, reconcile.proposed, device.offline, ...)"},"zalo":{"type":"boolean","default":false},"email":{"type":"boolean","default":true},"push":{"type":"boolean","default":true},"min_amount":{"type":"string","default":"10000000","description":"Ngưỡng tiền vào tối thiểu (VND safe bigint string)"},"include_provisional":{"type":"boolean","default":true,"description":"Có nhận tiền vào tạm tính không"},"quiet_start":{"type":"string","default":"22:00","description":"Giờ bắt đầu yên lặng (HH:mm)"},"quiet_end":{"type":"string","default":"06:00","description":"Giờ kết thúc yên lặng (HH:mm)"},"timezone":{"type":"string","default":"Asia/Ho_Chi_Minh"},"params":{"type":"object","additionalProperties":{},"default":{}}},"required":["event"]}}},"required":["object","prefs"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"put":{"operationId":"putNotificationPrefs","summary":"Cập nhật cài đặt thông báo của cá nhân","description":"Lưu tuỳ chọn kênh, ngưỡng số tiền, giờ yên lặng của người dùng.","tags":["Thông báo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.pref.self","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prefs":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string","description":"Loại sự kiện (tx.in, tx.out, reconcile.proposed, device.offline, ...)"},"zalo":{"type":"boolean","default":false},"email":{"type":"boolean","default":true},"push":{"type":"boolean","default":true},"min_amount":{"type":"string","default":"10000000","description":"Ngưỡng tiền vào tối thiểu (VND safe bigint string)"},"include_provisional":{"type":"boolean","default":true,"description":"Có nhận tiền vào tạm tính không"},"quiet_start":{"type":"string","default":"22:00","description":"Giờ bắt đầu yên lặng (HH:mm)"},"quiet_end":{"type":"string","default":"06:00","description":"Giờ kết thúc yên lặng (HH:mm)"},"timezone":{"type":"string","default":"Asia/Ho_Chi_Minh"},"params":{"type":"object","additionalProperties":{},"default":{}}},"required":["event"]}}},"required":["prefs"]}}}},"responses":{"200":{"description":"Thiết lập sau khi lưu.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["notification_prefs"]},"prefs":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string","description":"Loại sự kiện (tx.in, tx.out, reconcile.proposed, device.offline, ...)"},"zalo":{"type":"boolean","default":false},"email":{"type":"boolean","default":true},"push":{"type":"boolean","default":true},"min_amount":{"type":"string","default":"10000000","description":"Ngưỡng tiền vào tối thiểu (VND safe bigint string)"},"include_provisional":{"type":"boolean","default":true,"description":"Có nhận tiền vào tạm tính không"},"quiet_start":{"type":"string","default":"22:00","description":"Giờ bắt đầu yên lặng (HH:mm)"},"quiet_end":{"type":"string","default":"06:00","description":"Giờ kết thúc yên lặng (HH:mm)"},"timezone":{"type":"string","default":"Asia/Ho_Chi_Minh"},"params":{"type":"object","additionalProperties":{},"default":{}}},"required":["event"]}}},"required":["object","prefs"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/notification-rules":{"get":{"operationId":"getNotificationRules","summary":"Quy tắc định tuyến thông báo của tổ chức","description":"Lấy người nhận thông báo theo loại sự kiện và quyền của tổ chức.","tags":["Thông báo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.org_rule.manage","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":true,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"}],"responses":{"200":{"description":"Danh sách quy tắc.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["notification_rules"]},"company_id":{"$ref":"#/components/schemas/OrgId"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","description":"Loại sự kiện (tx.in, tx.out, reconcile.proposed, quota.threshold, ...)"},"recipients":{"type":"array","items":{"type":"object","properties":{"user_id":{"$ref":"#/components/schemas/UserId"},"role":{"type":"string"},"email":{"type":"string","format":"email"}}}},"enabled":{"type":"boolean","default":true}},"required":["kind","recipients"]}}},"required":["object","company_id","rules"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"operationId":"putNotificationRules","summary":"Cập nhật quy tắc định tuyến thông báo của tổ chức","description":"Chỉ Admin và Owner có quyền thay đổi danh sách người nhận thông báo theo sự kiện.","tags":["Thông báo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.org_rule.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company_id":{"$ref":"#/components/schemas/OrgId"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","description":"Loại sự kiện (tx.in, tx.out, reconcile.proposed, quota.threshold, ...)"},"recipients":{"type":"array","items":{"type":"object","properties":{"user_id":{"$ref":"#/components/schemas/UserId"},"role":{"type":"string"},"email":{"type":"string","format":"email"}}}},"enabled":{"type":"boolean","default":true}},"required":["kind","recipients"]}}},"required":["company_id","rules"]}}}},"responses":{"200":{"description":"Quy tắc sau khi cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["notification_rules"]},"company_id":{"$ref":"#/components/schemas/OrgId"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","description":"Loại sự kiện (tx.in, tx.out, reconcile.proposed, quota.threshold, ...)"},"recipients":{"type":"array","items":{"type":"object","properties":{"user_id":{"$ref":"#/components/schemas/UserId"},"role":{"type":"string"},"email":{"type":"string","format":"email"}}}},"enabled":{"type":"boolean","default":true}},"required":["kind","recipients"]}}},"required":["object","company_id","rules"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/me/push-tokens":{"post":{"operationId":"registerPushToken","summary":"Đăng ký push token thiết bị","description":"Lưu token APNs, FCM hoặc WebPush cho tài khoản người dùng hiện tại (token được mã hoá trên server).","tags":["Thông báo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.pref.self","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"device_install_id":{"type":"string","description":"ID cài đặt của thiết bị (UUID hoặc chuỗi ngẫu nhiên duy nhất cho máy)","example":"7b1f3c52-9d4e-4a6b-8e21-5c0f9a3d7e44"},"platform":{"type":"string","enum":["apns","fcm","webpush"]},"environment":{"type":"string","enum":["sandbox","production"],"default":"production"},"token":{"type":"string","description":"Device token APNs, FCM registration token, hoặc WebPush subscription JSON","example":"fcm:APA91bHun4MxP5kXz0sT3yQeLrVn8wAd2c"},"app_version":{"type":"string"},"locale":{"type":"string","default":"vi"}},"required":["device_install_id","platform","token"]}}}},"responses":{"200":{"description":"Kết quả đăng ký token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["push_token"]},"id":{"type":"string"},"device_install_id":{"type":"string"},"platform":{"type":"string","enum":["apns","fcm","webpush"]},"environment":{"type":"string","enum":["sandbox","production"]},"created_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["object","id","device_install_id","platform","environment","created_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"get":{"operationId":"listPushTokens","summary":"Danh sách thiết bị nhận push của tôi","description":"Các cài đặt đang đăng ký push của chính người dùng (APNs, FCM, Web Push), chưa bị thu hồi. Token không bao giờ được trả lại: `device_install_id` là mã dùng cho `DELETE /v1/me/push-tokens/{install_id}`.","tags":["Thông báo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.pref.self","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách push token của người dùng.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["push_tokens"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["push_token"]},"id":{"type":"string"},"device_install_id":{"type":"string"},"platform":{"type":"string","enum":["apns","fcm","webpush"]},"environment":{"type":"string","enum":["sandbox","production"]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"app_version":{"type":["string","null"]},"locale":{"type":"string"},"last_seen_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["object","id","device_install_id","platform","environment","created_at","app_version","locale","last_seen_at"]}}},"required":["object","data"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/me/push-tokens/{install_id}":{"delete":{"operationId":"deletePushToken","summary":"Thu hồi push token thiết bị","description":"Huỷ đăng ký push token của thiết bị khi đăng xuất.","tags":["Thông báo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.pref.self","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string"},"required":true,"name":"install_id","in":"path"}],"responses":{"200":{"description":"Đã thu hồi token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webpush/vapid-key":{"get":{"operationId":"getWebPushVapidKey","summary":"Lấy VAPID public key cho Web Push","description":"Client web dùng public key này để đăng ký pushManager subscription.","tags":["Thông báo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.pref.self","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"VAPID key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["webpush_vapid_key"]},"public_key":{"type":"string","description":"VAPID public key base64url"}},"required":["object","public_key"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/webpush/subscriptions":{"post":{"operationId":"registerWebPushSubscription","summary":"Đăng ký Web Push subscription","description":"Lưu thông tin PushSubscription từ trình duyệt web.","tags":["Thông báo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.pref.self","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"type":"string","format":"uri","example":"https://fcm.googleapis.com/fcm/send/dQw4w9WgXcQ:APA91bHun4MxP5"},"keys":{"type":"object","properties":{"p256dh":{"type":"string","example":"BNcRdreALRFXTkOOUHK1EtK2wtaz5Ry4YfYCA_0QTpQtUbVlUls0VJXg7A8u-Ts1XbjhazAkj7I99e8QcYP7DkM"},"auth":{"type":"string","example":"tBHItJI5svbpez7KI4CCXg"}},"required":["p256dh","auth"]}},"required":["endpoint","keys"]}}}},"responses":{"200":{"description":"Đã đăng ký Web Push.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"install_id":{"type":"string","description":"Mã cài đặt của trình duyệt này, dùng cho `DELETE /v1/me/push-tokens/{install_id}`.","example":"web_9f2c41d07b3e58a6c1d4e7f0a2b39c85"}},"required":["ok","install_id"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/me/zalo:link":{"post":{"operationId":"linkZalo","summary":"Liên kết tài khoản Zalo OA","description":"Tạo liên kết với Zalo ID để nhận thông báo ZBS.","tags":["Thông báo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.pref.self","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zalo_user_id":{"type":"string","example":"2512345678901234567"},"phone_hash":{"type":"string"}},"required":["zalo_user_id"]}}}},"responses":{"200":{"description":"Đã tạo liên kết Zalo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"verified":{"type":"boolean"}},"required":["ok","verified"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/me/zalo:verify":{"post":{"operationId":"verifyZalo","summary":"Xác thực liên kết Zalo","description":"Xác nhận mã OTP hoặc callback xác thực Zalo OA.","tags":["Thông báo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.pref.self","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"482913"}},"required":["code"]}}}},"responses":{"200":{"description":"Xác thực hoàn tất.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/me/zalo-link":{"get":{"operationId":"getZaloLink","summary":"Trạng thái liên kết Zalo","description":"Trạng thái liên kết Zalo của người dùng hiện tại: chưa liên kết, đang chờ mã hay đã xác thực.","tags":["Thông báo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.pref.self","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Trạng thái liên kết Zalo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["zalo_link"]},"enabled":{"type":"boolean","description":"Cờ `notify.zalo` đang bật cho tổ chức của người dùng; tắt thì không thể liên kết."},"linked":{"type":"boolean"},"verified":{"type":"boolean"},"zalo_user_id_hint":{"type":["string","null"],"description":"Zalo ID đã che, chỉ giữ 4 ký tự cuối.","example":"••••4567"},"verified_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"code_expires_at":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Có giá trị khi một mã xác thực còn hiệu lực (đang chờ nhập).","example":"2026-10-19T01:30:15Z"}},"required":["object","enabled","linked","verified","zalo_user_id_hint","verified_at","code_expires_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/notifications":{"get":{"operationId":"listNotifications","summary":"Hộp thư thông báo trong app","description":"Lấy danh sách thông báo in-app của người dùng, hỗ trợ lọc chưa đọc và phân trang cursor.","tags":["Thông báo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.pref.self","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"unread","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Danh sách thông báo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["notifications"]},"notifications":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"channel":{"type":"string","enum":["apns","fcm","webpush","email","inapp","zalo"]},"kind":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"},"data":{"type":"object","additionalProperties":{}},"state":{"type":"string"},"collapse_key":{"type":["string","null"]},"read_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"created_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","channel","kind","title","body","data","state","collapse_key","read_at","created_at"]}},"unread_count":{"type":"integer","minimum":0}},"required":["object","notifications","unread_count"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/notifications:mark-read":{"post":{"operationId":"markNotificationsRead","summary":"Đánh dấu đã đọc thông báo","description":"Đánh dấu một số ID hoặc tất cả thông báo của người dùng là đã đọc.","tags":["Thông báo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.pref.self","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":false,"content":{"application/json":{"example":{"ids":["0199f564-b530-734b-834b-cd5cb38fe3f7","0199f564-b531-7a2c-9f10-2d6e8a41b3c5"]},"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Số lượng thông báo đã cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"marked_count":{"type":"integer"}},"required":["marked_count"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/me/widget-summary":{"get":{"operationId":"getWidgetSummary","summary":"Tóm tắt dữ liệu cho Widget màn hình khoá / Home","description":"Cung cấp số dư tài khoản (tách xác thực và tạm tính), thu/chi hôm nay và số việc chờ duyệt mà không lộ STK hay PII.","tags":["Thông báo"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.pref.self","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Dữ liệu tóm tắt widget.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["widget_summary"]},"as_of":{"$ref":"#/components/schemas/Timestamp"},"accounts":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"last4":{"type":"string"},"verified":{"type":"string","description":"Tổng tiền đã xác thực (VND safe bigint string)"},"provisional":{"type":"string","description":"Tổng tiền tạm tính (VND safe bigint string)"}},"required":["label","last4","verified","provisional"]}},"today_in":{"type":"string","description":"Tổng thu hôm nay (VND safe bigint string)"},"today_out":{"type":"string","description":"Tổng chi hôm nay (VND safe bigint string)"},"pending_approvals":{"type":"integer","minimum":0,"description":"Số lượng phân bổ/đối soát đang chờ duyệt"}},"required":["object","as_of","accounts","today_in","today_out","pending_approvals"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/me/approval-keys":{"post":{"operationId":"registerApprovalKey","summary":"Đăng ký khoá sinh trắc duyệt lệnh","description":"Đăng ký khoá EC P-256 từ Secure Enclave (iOS) hoặc Android Keystore với chữ ký xác minh sở hữu. Cần step-up còn hiệu lực (passkey/TOTP). Chỉ phiên người dùng (session) được đăng ký, cấm OAuth. Một key_id đã tồn tại (khác khoá công khai hoặc đã thu hồi) bị từ chối 409, không bao giờ được ghi đè.","tags":["Bảo mật sinh trắc"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.pref.self","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key_id":{"type":"string","description":"ID định danh khoá (alias hoặc fingerprint từ Secure Enclave / Keystore)","example":"ios-se-key-01"},"pubkey":{"type":"string","description":"P-256 public key (SPKI hoặc 65-byte uncompressed point dạng hex hoặc base64)","example":"BEl62iUYgUivxIkv69yViEuiBIa40HI0DLLuxazjqAKVXTJtkTXH3gZLBgYfG0k8BMVdRsaRzxkeSyQY4Mb5Zg4"},"platform":{"type":"string","enum":["ios","android","web"]},"attestation":{"type":"string","description":"Chứng chỉ phần cứng Key Attestation (tuỳ chọn)"},"signature":{"type":"string","description":"Chữ ký chứng minh sở hữu khoá ký trên 'register:<user_id>:<key_id>'","example":"MEUCIQDk3Zl1h0m0n9yq6c0d8v2a7Qx5r1sWJp4uT8bN3eYkGgIgS2fA9vLw1xQeR7tZc0pHnUo5dYjB6mK8iVaXl4cE3sM="}},"required":["key_id","pubkey","platform","signature"]}}}},"responses":{"200":{"description":"Khoá đã đăng ký.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["approval_device_key"]},"id":{"type":"string"},"key_id":{"type":"string"},"platform":{"type":"string","enum":["ios","android","web"]},"created_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["object","id","key_id","platform","created_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"get":{"operationId":"listApprovalKeys","summary":"Danh sách khoá sinh trắc đã đăng ký","description":"Liệt kê các thiết bị và khoá sinh trắc đang có hiệu lực của người dùng.","tags":["Bảo mật sinh trắc"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.pref.self","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách khoá.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["approval_device_keys"]},"keys":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["approval_device_key"]},"id":{"type":"string"},"key_id":{"type":"string"},"platform":{"type":"string","enum":["ios","android","web"]},"created_at":{"$ref":"#/components/schemas/Timestamp"}},"required":["object","id","key_id","platform","created_at"]}}},"required":["object","keys"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/me/approval-keys/{key_id}":{"delete":{"operationId":"deleteApprovalKey","summary":"Thu hồi khoá sinh trắc","description":"Huỷ kích hoạt khoá sinh trắc khi xoá máy hoặc mất thiết bị.","tags":["Bảo mật sinh trắc"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.pref.self","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string"},"required":true,"name":"key_id","in":"path"}],"responses":{"200":{"description":"Đã thu hồi khoá.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/approvals/{id}/challenge":{"get":{"operationId":"getApprovalChallenge","summary":"Lấy challenge ký sinh trắc duyệt lệnh","description":"Tạo nonce dùng một lần (hết hạn 60s) gắn chặt với approval_id và payload_hash để ứng dụng di động ký sinh trắc.","tags":["Bảo mật sinh trắc"],"security":[{"bearerAuth":[]}],"x-dt-permission":"notify.pref.self","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Challenge ký sinh trắc.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["approval_challenge"]},"approval_id":{"type":"string"},"nonce":{"type":"string","description":"Nonce ngẫu nhiên 32 bytes hex dùng 1 lần"},"payload_hash":{"type":"string","description":"SHA-256 hex của canonical payload cần duyệt"},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$","description":"Hạn dùng 60 giây","example":"2026-10-19T01:30:15Z"}},"required":["object","approval_id","nonce","payload_hash","expires_at"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/billing/meter":{"get":{"operationId":"getBillingMeter","summary":"Thanh đo hạn mức sử dụng kỳ hiện tại","description":"Đo lường số giao dịch đã xác thực trong tháng theo giờ VN, hạn mức miễn phí, dự kiến cuối tháng và trần chi tiêu.","tags":["Gói & sử dụng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"billing.read","x-dt-scope":"billing:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Thông số đo lường hiện tại.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingMeter"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/billing/usage":{"get":{"operationId":"getBillingUsage","summary":"Chi tiết số lượng giao dịch sử dụng","description":"Phân bổ số giao dịch đã xác thực theo ngày, kênh nguồn hoặc theo từng công ty.","tags":["Gói & sử dụng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"billing.read","x-dt-scope":"billing:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Từ ngày YYYY-MM-DD.","example":"2026-10-19"},"required":false,"description":"Từ ngày YYYY-MM-DD.","name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Đến ngày YYYY-MM-DD.","example":"2026-10-19"},"required":false,"description":"Đến ngày YYYY-MM-DD.","name":"to","in":"query"},{"schema":{"type":"string","enum":["day","source","company"],"default":"day","description":"Nhóm theo ngày, nguồn dữ liệu hoặc công ty thành viên."},"required":false,"description":"Nhóm theo ngày, nguồn dữ liệu hoặc công ty thành viên.","name":"group_by","in":"query"}],"responses":{"200":{"description":"Thống kê chi tiết lượng giao dịch.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageBreakdownResponse"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/billing/plan":{"get":{"operationId":"getBillingPlan","summary":"Thông tin gói cước và hạn mức hiện tại","description":"Chi tiết gói cước đang áp dụng, bảng giá bậc luỹ tiến và các quyền hạn mức.","tags":["Gói & sử dụng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"billing.read","x-dt-scope":"billing:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Thông tin gói cước.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentPlanResponse"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/billing/spend-cap":{"get":{"operationId":"getBillingSpendCap","summary":"Xem trần chi tiêu tự đặt","description":"Hạn mức trần do khách tự đặt để tự bảo vệ chi phí, tránh vượt dự toán ngoài ý muốn.","tags":["Gói & sử dụng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"billing.read","x-dt-scope":"billing:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Hạn mức trần chi tiêu hiện tại.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpendCap"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"put":{"operationId":"updateBillingSpendCap","summary":"Cập nhật trần chi tiêu tự đặt","description":"Cập nhật mức trần chi tiêu. Chạm trần không chặn nhận giao dịch và webhook, chỉ tạm dừng AI nền tảng và lệnh xuất mới.","tags":["Gói & sử dụng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"billing.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSpendCap"}}}},"responses":{"200":{"description":"Trần chi tiêu đã lưu.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpendCap"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/billing/invoices":{"get":{"operationId":"listBillingInvoices","summary":"Danh sách hoá đơn gói dịch vụ","description":"Danh sách hoá đơn hàng tháng của tổ chức (mã DTP-INV-YYMM), trạng thái thanh toán và mã nội dung.","tags":["Gói & sử dụng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"billing.read","x-dt-scope":"billing:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["accruing","open","paid","overdue","void","free_tier"],"description":"Lọc theo trạng thái hoá đơn."},"required":false,"description":"Lọc theo trạng thái hoá đơn.","name":"state","in":"query"}],"responses":{"200":{"description":"Danh sách hoá đơn.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingInvoiceList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/billing/invoices/{id}:pay-qr":{"post":{"operationId":"payInvoiceQr","summary":"Tạo mã VietQR thanh toán hoá đơn gói","description":"Tạo mã chuyển khoản VietQR chuẩn EMVCo có gắn mã nội dung DTP… độc nhất. Hiệu lực 15 phút, tự gạch nợ sau khi tiền về.","tags":["Gói & sử dụng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"billing.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/BillingInvoiceId"},"required":true,"description":"Mã hoá đơn thanh toán (`bin_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Thông tin mã VietQR thanh toán hoá đơn.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayQrResponse"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/billing/credit:topup-qr":{"post":{"operationId":"topupCreditQr","summary":"Tạo mã VietQR nạp credit dịch vụ","description":"Tạo mã VietQR nạp trước credit dịch vụ để tự động trừ vào các kỳ hoá đơn tiếp theo. Lưu ý: credit không phải ví tiền, không thể rút.","tags":["Gói & sử dụng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"billing.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupQrRequest"}}}},"responses":{"200":{"description":"Thông tin mã VietQR nạp credit.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupQrResponse"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/billing/credit":{"get":{"operationId":"getBillingCredit","summary":"Số dư credit dịch vụ và lịch sử biến động","description":"Tra cứu số dư credit dịch vụ hiện tại và sổ cái biến động (nạp tiền, trừ hoá đơn, hoàn trả).","tags":["Gói & sử dụng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"billing.read","x-dt-scope":"billing:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Số dư credit dịch vụ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCreditBalanceResponse"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/billing/info":{"get":{"operationId":"getBillingInfo","summary":"Thông tin xuất hoá đơn tài chính","description":"Thông tin doanh nghiệp (MST, tên công ty, địa chỉ, email nhận hoá đơn GTGT) để xuất hoá đơn điện tử.","tags":["Gói & sử dụng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"billing.read","x-dt-scope":"billing:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Thông tin hoá đơn tài chính.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingInfo"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"put":{"operationId":"updateBillingInfo","summary":"Cập nhật thông tin xuất hoá đơn tài chính","description":"Cập nhật mã số thuế, tên công ty và email để nhận hoá đơn điện tử GTGT hợp lệ.","tags":["Gói & sử dụng"],"security":[{"bearerAuth":[]}],"x-dt-permission":"billing.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"example":{"tax_id":"0312345678","company_name":"Công ty TNHH Thương mại Sao Việt","invoice_address":"25 Nguyễn Huệ, Phường Bến Nghé, Quận 1, TP. Hồ Chí Minh","invoice_email":"ketoan@saoviet.vn","contact_name":"Nguyễn Thị Lan","contact_email":"lan.nguyen@saoviet.vn"},"schema":{"$ref":"#/components/schemas/UpdateBillingInfo"}}}},"responses":{"200":{"description":"Thông tin hoá đơn tài chính đã cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingInfo"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/public/plans":{"get":{"operationId":"getPublicPlans","summary":"Bảng giá và tính năng các gói công khai","description":"Danh sách các gói dịch vụ, hạn mức quota miễn phí, đơn giá luỹ tiến theo giao dịch và các quyền hạn mức công khai. Không yêu cầu đăng nhập, cache 5 phút.","tags":["Gói & sử dụng"],"security":[],"x-dt-permission":"public","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-cors":"marketing","x-dt-service":"api","responses":{"200":{"description":"Bảng giá công khai các gói cước.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPlansResponse"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/accounting/periods":{"get":{"operationId":"listAccountingPeriods","summary":"Danh sách kỳ kế toán","description":"Lấy danh sách các kỳ kế toán và trạng thái khoá/mở.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"export.dry_run","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách các kỳ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AccountingPeriod"}}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/accounting/periods/{ym}/lock-requests":{"post":{"operationId":"requestPeriodLock","summary":"Yêu cầu khoá kỳ kế toán","description":"Gửi yêu cầu khoá kỳ qua quy trình maker-checker. Cần nêu rõ lý do khoá.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"period.lock_request","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","pattern":"^[0-9]{6}$"},"required":true,"name":"ym","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"reason":"Đã hoàn tất đối soát và chốt sổ tháng 09/2026."},"schema":{"$ref":"#/components/schemas/LockPeriodRequest"}}}},"responses":{"200":{"description":"Yêu cầu khoá kỳ đã gửi.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingPeriod"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/periods/{ym}/lock-requests/{id}:approve":{"post":{"operationId":"approvePeriodLock","summary":"Duyệt khoá kỳ kế toán","description":"Người kiểm tra (checker khác maker) duyệt khoá kỳ kế toán.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"period.lock_approve","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","pattern":"^[0-9]{6}$"},"required":true,"name":"ym","in":"path"},{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Kỳ kế toán đã được khoá.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingPeriod"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/periods/{ym}/lock-requests/{id}:reject":{"post":{"operationId":"rejectPeriodLock","summary":"Từ chối khoá kỳ kế toán","description":"Người kiểm tra (khác người yêu cầu) từ chối yêu cầu khoá kỳ; kỳ trở lại trạng thái mở.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"period.lock_approve","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","pattern":"^[0-9]{6}$"},"required":true,"name":"ym","in":"path"},{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectRequestBody"}}}},"responses":{"200":{"description":"Yêu cầu khoá đã bị từ chối.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingPeriod"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/periods/{ym}/unlock-requests":{"post":{"operationId":"requestPeriodUnlock","summary":"Yêu cầu mở khoá kỳ kế toán","description":"Gửi yêu cầu mở khoá kỳ đã khoá trước đó (yêu cầu step-up xác thực).","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"period.unlock_request","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","pattern":"^[0-9]{6}$"},"required":true,"name":"ym","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"reason":"Cần điều chỉnh bút toán phát hiện sai sót sau khi khoá kỳ."},"schema":{"$ref":"#/components/schemas/UnlockPeriodRequest"}}}},"responses":{"200":{"description":"Yêu cầu mở khoá đã gửi.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingPeriod"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/periods/{ym}/unlock-requests/{id}:approve":{"post":{"operationId":"approvePeriodUnlock","summary":"Duyệt mở khoá kỳ kế toán","description":"Duyệt mở lại kỳ kế toán (yêu cầu step-up xác thực).","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"period.unlock_approve","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","pattern":"^[0-9]{6}$"},"required":true,"name":"ym","in":"path"},{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Kỳ kế toán đã được mở khoá.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingPeriod"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/periods/{ym}/unlock-requests/{id}:reject":{"post":{"operationId":"rejectPeriodUnlock","summary":"Từ chối mở khoá kỳ kế toán","description":"Người kiểm tra từ chối yêu cầu mở khoá; kỳ vẫn khoá (yêu cầu step-up xác thực).","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"period.unlock_approve","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","pattern":"^[0-9]{6}$"},"required":true,"name":"ym","in":"path"},{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectRequestBody"}}}},"responses":{"200":{"description":"Yêu cầu mở khoá đã bị từ chối.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingPeriod"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/mapping/bank-accounts/{id}":{"get":{"operationId":"getBankAccountGlMap","summary":"Lấy ánh xạ tài khoản ngân hàng sang tài khoản kế toán","description":"Xem định khoản và mã tương ứng của tài khoản ngân hàng trong phần mềm đích.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"mapping.write","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AccountId"},"required":true,"description":"Mã tài khoản ngân hàng (`acc_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Thông tin ánh xạ tài khoản.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/BankAccountGlMap"},{"type":"null"}]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"operationId":"putBankAccountGlMap","summary":"Cập nhật ánh xạ tài khoản ngân hàng","description":"Thiết lập tài khoản kế toán (1121...) và mã tương ứng trong MISA/Fast.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"mapping.write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AccountId"},"required":true,"description":"Mã tài khoản ngân hàng (`acc_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PutBankAccountGlMapBody"}}}},"responses":{"200":{"description":"Đã cập nhật ánh xạ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankAccountGlMap"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/mapping/rules":{"get":{"operationId":"listMappingRules","summary":"Danh sách quy tắc định khoản","description":"Liệt kê các quy tắc định khoản tự động cho giao dịch.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"mapping.write","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"profile_id","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Danh sách quy tắc định khoản.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MappingRuleList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createMappingRule","summary":"Tạo quy tắc định khoản","description":"Thêm quy tắc ánh xạ phân loại sang định khoản Nợ/Có.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"mapping.write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMappingRuleBody"}}}},"responses":{"201":{"description":"Đã tạo quy tắc định khoản.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MappingRule"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/mapping/rules:propose":{"post":{"operationId":"proposeMappingRules","summary":"Đề xuất quy tắc định khoản (gói, maker-checker)","description":"Gói một hoặc nhiều quy tắc định khoản thành MỘT yêu cầu duyệt `mapping_change`; chỉ khi người duyệt (khác người đề xuất) chấp thuận các quy tắc mới có hiệu lực.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"mapping.write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposeMappingRulesBody"}}}},"responses":{"201":{"description":"Đã gửi đề xuất, chờ duyệt.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MappingProposalResult"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/mapping/rules/{id}":{"patch":{"operationId":"patchMappingRule","summary":"Cập nhật quy tắc định khoản","description":"Sửa đổi điều kiện hoặc tài khoản định khoản của quy tắc.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"mapping.write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/MappingRuleId"},"required":true,"description":"Mã quy tắc định khoản (`map_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Thu tiền khách hàng qua ngân hàng"},"profile_id":{"type":"string","format":"uuid","example":"0192f2f0-7c3e-7d3a-9b1a-3c5d6e7f8a90"},"conditions":{"type":"object","additionalProperties":{},"default":{}},"voucher_type":{"$ref":"#/components/schemas/VoucherType"},"debit_account":{"type":"string","minLength":3,"example":"1121"},"credit_account":{"type":"string","minLength":3,"example":"131"},"detail_account":{"type":"string"},"counterparty_rule":{"type":"object","additionalProperties":{}},"case_code_required":{"type":"boolean","default":false},"vat_rate":{"type":"number"},"revenue_account":{"type":"string"},"vat_account":{"type":"string"},"priority":{"type":"integer","default":100},"effective_from":{"$ref":"#/components/schemas/Date"}}}}}},"responses":{"200":{"description":"Đã cập nhật quy tắc.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MappingRule"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/mapping/templates":{"get":{"operationId":"listMappingTemplates","summary":"Danh sách bộ mẫu quy tắc định khoản","description":"Các bộ mẫu quy tắc có thể áp dụng cho hồ sơ hệ thống tài khoản của công ty (chỉ bộ mẫu cùng hệ thống TK).","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"mapping.write","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Bộ mẫu áp dụng được.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MappingTemplateList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/accounting/mapping:apply-template":{"post":{"operationId":"applyMappingTemplate","summary":"Áp dụng bộ mẫu quy tắc định khoản","description":"Tạo toàn bộ quy tắc của bộ mẫu thành MỘT yêu cầu duyệt `mapping_change` (maker-checker). Từ chối nếu hệ thống TK của hồ sơ khác bộ mẫu hoặc thiếu tài khoản mà bộ mẫu cần.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"mapping.write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplyMappingTemplateBody"}}}},"responses":{"201":{"description":"Đã gửi bộ mẫu để duyệt.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplyMappingTemplateResult"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/coa-profiles/{id}:duplicate":{"post":{"operationId":"duplicateCoaProfile","summary":"Nhân bản hồ sơ hệ thống tài khoản","description":"Nhân bản hồ sơ hệ thống tài khoản và danh mục tài khoản mà không sửa lịch sử.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"mapping.write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuplicateCoaProfileBody"}}}},"responses":{"201":{"description":"Đã nhân bản hồ sơ thành công.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuplicateCoaProfileResult"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/mapping/counterparty-codes":{"get":{"operationId":"listCounterpartyCodes","summary":"Mã đối tượng theo phần mềm đích","description":"Mã đối tượng (khách hàng/nhà cung cấp) sẽ xuất cho một đích: mã kế toán đã lưu hoặc mã suy ra (đánh dấu `derived` = sẽ tạo mới trên đích).","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"mapping.write","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/CounterpartyCodeTarget"},"required":true,"description":"Phần mềm kế toán đích của mã đối tượng.","name":"target","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Mã đối tượng.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CounterpartyCodeList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"operationId":"putCounterpartyCode","summary":"Đặt mã đối tượng","description":"Lưu mã đối tượng cho một đối tác trên một đích. Mã trùng với mã của đối tác khác trên cùng đích bị từ chối (409).","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"mapping.write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PutCounterpartyCodeBody"}}}},"responses":{"200":{"description":"Đã lưu mã đối tượng.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CounterpartyCodeEntry"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/mapping/counterparty-codes:import":{"post":{"operationId":"importCounterpartyCodes","summary":"Nhập danh mục mã đối tượng từ phần mềm đích","description":"Dùng lại mã đã có trong MISA/Fast: khớp đối tác theo MST rồi theo tên đã chuẩn hoá và lưu mã.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"mapping.write","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportCounterpartyCodesBody"}}}},"responses":{"200":{"description":"Kết quả nhập.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportCounterpartyCodesResult"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/mapping/changes":{"get":{"operationId":"listMappingChanges","summary":"Danh sách thay đổi ánh xạ chờ duyệt","description":"Các thay đổi ánh xạ tài khoản ngân hàng và quy tắc định khoản đang chờ người kiểm tra duyệt.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"mapping.approve","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","enum":["pending","approved","rejected","withdrawn","expired"],"default":"pending"},"required":false,"name":"state","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Danh sách thay đổi ánh xạ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MappingChangeList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/mapping/changes/{id}:approve":{"post":{"operationId":"approveMappingChange","summary":"Duyệt thay đổi ánh xạ","description":"Người kiểm tra (khác người đề xuất) duyệt thay đổi ánh xạ; từ lúc duyệt, ánh xạ mới áp dụng cho các chứng từ chưa xuất.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"mapping.approve","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ApprovalRequestId"},"required":true,"description":"Mã yêu cầu duyệt (`apr_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Đã duyệt thay đổi ánh xạ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MappingChange"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/mapping/changes/{id}:reject":{"post":{"operationId":"rejectMappingChange","summary":"Từ chối thay đổi ánh xạ","description":"Người kiểm tra từ chối thay đổi ánh xạ; ánh xạ đang áp dụng không đổi.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"mapping.approve","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ApprovalRequestId"},"required":true,"description":"Mã yêu cầu duyệt (`apr_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectRequestBody"}}}},"responses":{"200":{"description":"Đã từ chối thay đổi ánh xạ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MappingChange"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/export-readiness":{"get":{"operationId":"getExportReadiness","summary":"Kiểm tra mức độ sẵn sàng xuất kế toán","description":"Kiểm tra tiền điều kiện trước khi tạo lô (giao dịch tạm tính, độ khớp số dư, ánh xạ thiếu).","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"export.dry_run","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","pattern":"^[0-9]{6}$"},"required":true,"name":"period","in":"query"},{"schema":{"$ref":"#/components/schemas/ExportTarget"},"required":true,"description":"Đích xuất kế toán: MISA AMIS, MISA SME, Fast, Excel TT133, Excel TT99 hoặc OpenAPI MISA AMIS.","name":"target","in":"query"}],"responses":{"200":{"description":"Mức độ sẵn sàng xuất kế toán.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportReadiness"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/exports/dry-run":{"post":{"operationId":"dryRunExport","summary":"Chạy thử kiểm tra xuất kế toán","description":"Kiểm tra điều kiện xuất chứng từ (cân đối Nợ-Có, tài khoản đã ánh xạ, kỳ khoá, mã đối tượng). Không lưu dữ liệu, không tiêu số chứng từ.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"export.dry_run","x-dt-idempotent":"optional","x-dt-rate-class":"export","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportDryRunBody"}}}},"responses":{"200":{"description":"Kết quả kiểm tra điều kiện xuất.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportDryRunResponse"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/exports":{"post":{"operationId":"createExportBatch","summary":"Tạo lô xuất kế toán (gửi duyệt)","description":"Tạo một lô xuất mới ở trạng thái chờ duyệt (pending_approval). Yêu cầu Idempotency-Key. Nếu còn lỗi chặn (blocking), lô chuyển sang failed_validation.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"export.create","x-dt-idempotent":"required","x-dt-rate-class":"export","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ. Bắt buộc ở máy chủ (thiếu → 400 idempotency_key_required); SDK tự sinh."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ. Bắt buộc ở máy chủ (thiếu → 400 idempotency_key_required); SDK tự sinh.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateExportBatchBody"}}}},"responses":{"201":{"description":"Đã tạo lô xuất kế toán.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportBatch"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `idempotency_key_required` — Thiếu header Idempotency-Key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"get":{"operationId":"listExportBatches","summary":"Danh sách các lô xuất kế toán","description":"Liệt kê lịch sử các lô xuất kế toán theo công ty.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"export.download","x-dt-scope":"export:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ExportTarget"},"required":false,"description":"Đích xuất kế toán: MISA AMIS, MISA SME, Fast, Excel TT133, Excel TT99 hoặc OpenAPI MISA AMIS.","name":"target","in":"query"},{"schema":{"type":"string"},"required":false,"name":"period","in":"query"},{"schema":{"$ref":"#/components/schemas/ExportBatchState"},"required":false,"description":"Trạng thái lô xuất: dry_run, pending_approval, approved, failed_validation, rejected, superseded.","name":"state","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Danh sách lô xuất.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportBatchList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/exports/{id}":{"get":{"operationId":"getExportBatch","summary":"Chi tiết một lô xuất kế toán","description":"Xem chi tiết lô xuất, danh sách kiểm tra và các tệp đính kèm.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"export.download","x-dt-scope":"export:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ExportBatchId"},"required":true,"description":"Mã lô xuất kế toán (`exb_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Chi tiết lô xuất.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportBatchDetail"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/exports/{id}:approve":{"post":{"operationId":"approveExportBatch","summary":"Duyệt lô xuất kế toán","description":"Người kiểm tra (checker khác maker) duyệt lô xuất. Cấp dải số chứng từ chính thức và khởi chạy sinh tệp.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"export.approve","x-dt-idempotent":"optional","x-dt-rate-class":"export","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ExportBatchId"},"required":true,"description":"Mã lô xuất kế toán (`exb_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Đã duyệt lô xuất.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportBatch"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/exports/{id}:reject":{"post":{"operationId":"rejectExportBatch","summary":"Từ chối lô xuất kế toán","description":"Người kiểm tra từ chối duyệt lô xuất và nêu rõ lý do.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"export.reject","x-dt-idempotent":"optional","x-dt-rate-class":"export","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ExportBatchId"},"required":true,"description":"Mã lô xuất kế toán (`exb_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectExportBatchBody"}}}},"responses":{"200":{"description":"Đã từ chối lô xuất.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportBatch"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/exports/{id}:rerun-checks":{"post":{"operationId":"rerunExportChecks","summary":"Chạy lại kiểm tra điều kiện xuất","description":"Chạy lại bộ kiểm tra khi giao dịch hoặc quy tắc ánh xạ đã được cập nhật.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"export.create","x-dt-idempotent":"optional","x-dt-rate-class":"export","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ExportBatchId"},"required":true,"description":"Mã lô xuất kế toán (`exb_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Kết quả kiểm tra mới.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportDryRunResponse"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/exports/{id}:re-export":{"post":{"operationId":"reExportBatch","summary":"Xuất lại lô chứng từ","description":"Tạo một lô xuất mới thay thế (supersedes) lô đã được duyệt trước đó.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"export.create","x-dt-idempotent":"required","x-dt-rate-class":"export","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ExportBatchId"},"required":true,"description":"Mã lô xuất kế toán (`exb_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ. Bắt buộc ở máy chủ (thiếu → 400 idempotency_key_required); SDK tự sinh."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ. Bắt buộc ở máy chủ (thiếu → 400 idempotency_key_required); SDK tự sinh.","name":"idempotency-key","in":"header"}],"responses":{"201":{"description":"Lô xuất thay thế đã được tạo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportBatch"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `idempotency_key_required` — Thiếu header Idempotency-Key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/exports/{id}/file":{"get":{"operationId":"getExportFile","summary":"Tải tệp chứng từ xuất","description":"Tải tệp của lô đã duyệt và sinh xong (`file_state = ready`). Tệp được phát qua Worker kèm `X-Content-SHA256` (sha256 lúc sinh tệp) và mỗi lượt tải được ghi nhật ký. Lô lớn được tách thành nhiều tệp (mỗi tệp tối đa 10.000 dòng, không cắt giữa chứng từ): `..._P001`, `..._P002`, ... kèm `..._MANIFEST.csv` ghi số dòng, số chứng từ và tổng tiền từng phần và tổng toàn lô. Lô có nhiều tệp: bỏ trống `name` để tải **một tệp ZIP** chứa tất cả (`X-Content-SHA256` là của tệp ZIP), hoặc chỉ định `name` để tải từng tệp (xem `files` trong chi tiết lô); ZIP quá lớn (> 40 MB) bị từ chối, hãy tải từng tệp.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"export.download","x-dt-scope":"export:read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ExportBatchId"},"required":true,"description":"Mã lô xuất kế toán (`exb_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Tên tệp trong lô; bỏ trống ở lô nhiều tệp để tải ZIP chứa tất cả."},"required":false,"description":"Tên tệp trong lô; bỏ trống ở lô nhiều tệp để tải ZIP chứa tất cả.","name":"name","in":"query"}],"responses":{"200":{"description":"Nội dung tệp xuất (xlsx hoặc csv), hoặc tệp ZIP khi lô có nhiều tệp.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}},"application/zip":{"schema":{"type":"string","format":"binary"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/exports/{id}/preview":{"get":{"operationId":"previewExportBatch","summary":"Xem trước các dòng chứng từ của lô xuất","description":"Xem danh sách các dòng chứng từ theo từng loại (BC, BN, PT, PC).","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"export.download","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/ExportBatchId"},"required":true,"description":"Mã lô xuất kế toán (`exb_…`).","name":"id","in":"path"},{"schema":{"$ref":"#/components/schemas/VoucherType"},"required":false,"description":"Loại chứng từ ngân hàng/tiền mặt: BC (Báo Có), BN (Báo Nợ), PT (Phiếu Thu), PC (Phiếu Chi).","name":"type","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Danh sách dòng chứng từ xem trước.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportPreviewLineList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/exports/golden":{"get":{"operationId":"getGoldenTemplates","summary":"Danh sách phiên bản golden templates","description":"Lấy cấu trúc mẫu xuất kế toán chuẩn của các phần mềm kế toán.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"export.dry_run","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Danh sách golden templates.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"target":{"$ref":"#/components/schemas/ExportTarget"},"version":{"type":"string"},"columns":{"type":"array","items":{"type":"string"}}},"required":["target","version","columns"]}}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/accounting/misa/connection":{"get":{"operationId":"getMisaConnection","summary":"Thông tin kết nối MISA AMIS","description":"Lấy trạng thái kết nối MISA AMIS của công ty hiện tại.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"accounting.misa.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","responses":{"200":{"description":"Thông tin kết nối.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/MisaConnection"},{"type":"null"}]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"put":{"operationId":"putMisaConnection","summary":"Thiết lập kết nối MISA AMIS","description":"Lưu mã kết nối AMIS (access_code) do khách hàng cung cấp và thử lấy token ngay.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"accounting.misa.manage","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"required":true,"content":{"application/json":{"example":{"access_code":"AMIS-7F3K9Q2XMD41"},"schema":{"$ref":"#/components/schemas/PutMisaConnectionBody"}}}},"responses":{"200":{"description":"Kết nối đã được cập nhật.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MisaConnection"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]},"delete":{"operationId":"deleteMisaConnection","summary":"Ngắt kết nối MISA AMIS","description":"Xoá mã kết nối MISA AMIS và ngừng đồng bộ chứng từ.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"accounting.misa.manage","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","responses":{"204":{"description":"Đã ngắt kết nối.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/accounting/misa/connection:test":{"post":{"operationId":"testMisaConnection","summary":"Kiểm tra kết nối và danh mục MISA","description":"Gọi thử các API danh mục của MISA AMIS để kiểm tra tính hợp lệ của mã kết nối và lấy danh sách chi nhánh, tài khoản ngân hàng.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"accounting.misa.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Kết quả kiểm tra kết nối.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MisaConnectionTestResult"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/misa/dictionary":{"get":{"operationId":"listMisaDictionary","summary":"Danh sách ánh xạ danh mục MISA","description":"Xem bảng ánh xạ tài khoản ngân hàng và đối tượng sang mã trong MISA AMIS.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"accounting.misa.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/MisaDictionaryKind"},"required":false,"description":"Loại danh mục MISA: bank_account (tài khoản ngân hàng) hoặc account_object (khách hàng/nhà cung cấp).","name":"kind","in":"query"}],"responses":{"200":{"description":"Danh sách danh mục MISA.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MisaDictionaryItem"}}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/misa/dictionary:sync":{"post":{"operationId":"syncMisaDictionary","summary":"Đồng bộ danh mục thiếu sang MISA AMIS","description":"Tạo các tài khoản ngân hàng hoặc đối tượng còn thiếu trong MISA bằng save_dictionary kèm ID và thăm dò (poll) kết quả.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"accounting.misa.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"202":{"description":"Đã tiếp nhận yêu cầu đồng bộ danh mục.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"queued":{"type":"boolean"},"message":{"type":"string"}},"required":["queued","message"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/misa/requests":{"get":{"operationId":"listMisaVoucherRequests","summary":"Danh sách đề nghị chứng từ MISA","description":"Liệt kê các đề nghị lập chứng từ đã gửi sang MISA AMIS.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"accounting.misa.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/MisaVoucherRequestState"},"required":false,"description":"Trạng thái đề nghị chứng từ MISA: queued, blocked, sent, generated, failed_generation, posted_inferred, unconfirmed, superseded, dead.","name":"state","in":"query"},{"schema":{"$ref":"#/components/schemas/ExportBatchId"},"required":false,"description":"Mã lô xuất kế toán (`exb_…`).","name":"batch_id","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Danh sách đề nghị chứng từ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MisaVoucherRequestList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/misa/requests/{id}":{"get":{"operationId":"getMisaVoucherRequest","summary":"Chi tiết đề nghị chứng từ MISA","description":"Xem chi tiết một đề nghị lập chứng từ và lịch sử gửi.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"accounting.misa.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/MisaVoucherRequestId"},"required":true,"description":"Mã đề nghị chứng từ MISA AMIS (`mvr_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Chi tiết đề nghị chứng từ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MisaVoucherRequest"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/misa/requests/{id}:resend":{"post":{"operationId":"resendMisaVoucherRequest","summary":"Gửi lại đề nghị chứng từ sang MISA","description":"Gửi lại đề nghị cùng org_refid (MISA sẽ cập nhật đè tại chỗ nếu kế toán chưa bấm Lập CT).","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"accounting.misa.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/MisaVoucherRequestId"},"required":true,"description":"Mã đề nghị chứng từ MISA AMIS (`mvr_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Đã đưa đề nghị vào hàng đợi gửi lại.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MisaVoucherRequest"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/misa/requests/{id}:cancel":{"post":{"operationId":"cancelMisaVoucherRequest","summary":"Huỷ đề nghị chứng từ trong MISA","description":"Huỷ đề nghị lập chứng từ (chỉ có tác dụng khi kế toán chưa bấm Lập CT trong AMIS).","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"accounting.misa.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/MisaVoucherRequestId"},"required":true,"description":"Mã đề nghị chứng từ MISA AMIS (`mvr_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Đã yêu cầu huỷ đề nghị.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MisaVoucherRequest"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/misa/requests/{id}:reverse":{"post":{"operationId":"reverseMisaVoucherRequest","summary":"Đảo đề nghị chứng từ MISA đã lập","description":"Ghi nhận chứng từ đã lập (hoặc đã ghi sổ) trong AMIS là bị đảo/huỷ: đề nghị chuyển sang `superseded` để không còn được tính là đã đẩy. MISA OpenAPI không có lệnh xoá, nên kế toán phải xoá hoặc đảo chứng từ trong AMIS; bút toán đảo tương ứng đi theo lô xuất kế tiếp. Chỉ áp dụng cho đề nghị `generated` hoặc `posted_inferred`.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"accounting.misa.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/MisaVoucherRequestId"},"required":true,"description":"Mã đề nghị chứng từ MISA AMIS (`mvr_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Đã ghi nhận đảo chứng từ.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MisaVoucherRequest"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/accounting/misa/requests/{id}:mark-generated":{"post":{"operationId":"markGeneratedMisaVoucherRequest","summary":"Xác nhận kế toán đã lập chứng từ thủ công","description":"Đánh dấu thủ công chứng từ đã được lập trong AMIS khi webhook callback chưa được kích hoạt.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"accounting.misa.manage","x-dt-idempotent":"optional","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/MisaVoucherRequestId"},"required":true,"description":"Mã đề nghị chứng từ MISA AMIS (`mvr_…`).","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Đã đánh dấu chứng từ đã lập.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MisaVoucherRequest"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/reconciliation/summary":{"get":{"operationId":"getReconSummary","summary":"Tổng quan đối soát","description":"KPI giao dịch chưa đối soát, gợi ý >= 90%, chờ duyệt và tỷ lệ đã đối soát.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"}],"responses":{"200":{"description":"KPI đối soát","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"unreconciled_count":{"type":"integer"},"unreconciled_amount":{"$ref":"#/components/schemas/Vnd"},"unreconciled_in_count":{"type":"integer"},"unreconciled_out_count":{"type":"integer"},"high_confidence_count":{"type":"integer"},"pending_approval_count":{"type":"integer"},"need_my_approval_count":{"type":"integer"},"my_created_count":{"type":"integer"},"reconciled_month_count":{"type":"integer"},"reconciled_month_pct":{"type":"number","minimum":0,"maximum":100},"last_synced_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"hoadon_connected":{"type":"boolean"}},"required":["unreconciled_count","unreconciled_amount","unreconciled_in_count","unreconciled_out_count","high_confidence_count","pending_approval_count","need_my_approval_count","my_created_count","reconciled_month_count","reconciled_month_pct","hoadon_connected"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/reconciliation/queue":{"get":{"operationId":"getReconQueue","summary":"Hàng chờ duyệt đối soát","description":"Danh sách phân bổ đang ở trạng thái pending_approval kèm checklist kiểm tra chính sách.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"type":"string","enum":["need_my_approval","my_created","all_company"],"default":"need_my_approval"},"required":false,"name":"filter","in":"query"},{"schema":{"type":"string"},"required":false,"name":"store_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"counter_id","in":"query"}],"responses":{"200":{"description":"Danh sách hàng chờ duyệt","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconQueueList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"enqueueReconQueue","summary":"Đưa giao dịch vào hàng chờ đối soát","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tx_ids":{"type":"array","items":{"$ref":"#/components/schemas/TxId"},"minItems":1,"maxItems":100}},"required":["tx_ids"]}}}},"responses":{"200":{"description":"Kết quả đưa vào hàng chờ","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"queued_count":{"type":"integer"}},"required":["queued_count"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/reconciliation/workspace":{"get":{"operationId":"getReconWorkspace","summary":"Dữ liệu màn làm việc đối soát","description":"Danh sách giao dịch chưa đối soát (vào/ra), gợi ý và trạng thái kết nối hoadon.pro.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"type":"string","enum":["in","out","all"],"default":"in"},"required":false,"name":"direction","in":"query"}],"responses":{"200":{"description":"Dữ liệu workspace","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","properties":{"unreconciled_count":{"type":"integer"},"unreconciled_amount":{"$ref":"#/components/schemas/Vnd"},"unreconciled_in_count":{"type":"integer"},"unreconciled_out_count":{"type":"integer"},"high_confidence_count":{"type":"integer"},"pending_approval_count":{"type":"integer"},"need_my_approval_count":{"type":"integer"},"my_created_count":{"type":"integer"},"reconciled_month_count":{"type":"integer"},"reconciled_month_pct":{"type":"number","minimum":0,"maximum":100},"last_synced_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"hoadon_connected":{"type":"boolean"}},"required":["unreconciled_count","unreconciled_amount","unreconciled_in_count","unreconciled_out_count","high_confidence_count","pending_approval_count","need_my_approval_count","my_created_count","reconciled_month_count","reconciled_month_pct","hoadon_connected"]},"items":{"type":"array","items":{"type":"object","properties":{"tx":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/TxId"},"amount":{"type":"integer"},"direction":{"type":"string","enum":["in","out"]},"description":{"type":"string"},"occurred_at":{"type":"string"},"source_channel":{"type":"string"},"bank_account":{"type":"string"},"company_name":{"type":"string"},"status":{"type":"string"}},"required":["id","amount","direction","description","occurred_at","source_channel","bank_account","company_name","status"]},"best_suggestion":{"type":"object","properties":{"id":{"type":"string"},"tx_id":{"$ref":"#/components/schemas/TxId"},"kind":{"type":"string","enum":["match"]},"rule_key":{"type":"string"},"rule_id":{"$ref":"#/components/schemas/MatchRuleId"},"confidence":{"type":"number","minimum":0,"maximum":100},"reasons":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"method":{"type":"string","enum":["exact","pattern","trgm","masothue","org_memo_regex","dsl"]},"label_vi":{"type":"string"},"delta":{"type":"number"},"ok":{"type":"boolean"},"captured":{"type":"string"},"pattern_id":{"type":"string"}},"required":["key","method","label_vi","delta","ok"]}},"lines":{"type":"array","items":{"type":"object","properties":{"target_type":{"type":"string","enum":["invoice","order","expected_payment"]},"target_id":{"type":"string"},"amount":{"$ref":"#/components/schemas/PositiveVnd"},"label":{"type":"string"},"outstanding":{"$ref":"#/components/schemas/Vnd"},"total":{"$ref":"#/components/schemas/Vnd"}},"required":["target_type","target_id","amount"]}},"overpay_amount":{"$ref":"#/components/schemas/Vnd"},"group_id":{"type":"string"},"payer_name":{"type":"string"},"payer_mst":{"type":"string"},"payer_source":{"type":"string"}},"required":["id","tx_id","kind","rule_key","confidence","reasons","lines"]},"suggestions_count":{"type":"integer"}},"required":["tx","suggestions_count"]}}},"required":["summary","items"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/reconciliation/suggestions:rerun":{"post":{"operationId":"rerunSuggestions","summary":"Chạy lại công cụ gợi ý đối soát","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tx_id":{"$ref":"#/components/schemas/TxId"},"company_id":{"$ref":"#/components/schemas/OrgId"}}}}}},"responses":{"200":{"description":"Gợi ý đã được tính lại","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"recomputed_count":{"type":"integer"},"skipped_count":{"type":"integer"},"skipped":{"type":"array","items":{"type":"object","properties":{"tx_id":{"$ref":"#/components/schemas/TxId"},"reason":{"type":"string","enum":["not_found","not_verified","not_reconcilable"]}},"required":["tx_id","reason"]}}},"required":["recomputed_count","skipped_count","skipped"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/transactions/{id}/suggestions":{"get":{"operationId":"getTxSuggestions","summary":"Gợi ý đối soát cho một giao dịch","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/TxId"},"required":true,"description":"Mã giao dịch (`tx_…`), ổn định vĩnh viễn kể cả khi bị gộp.","name":"id","in":"path"}],"responses":{"200":{"description":"Danh sách tối đa 3 phương án gợi ý","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"tx_id":{"$ref":"#/components/schemas/TxId"},"suggestions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tx_id":{"$ref":"#/components/schemas/TxId"},"kind":{"type":"string","enum":["match"]},"rule_key":{"type":"string"},"rule_id":{"$ref":"#/components/schemas/MatchRuleId"},"confidence":{"type":"number","minimum":0,"maximum":100},"reasons":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"method":{"type":"string","enum":["exact","pattern","trgm","masothue","org_memo_regex","dsl"]},"label_vi":{"type":"string"},"delta":{"type":"number"},"ok":{"type":"boolean"},"captured":{"type":"string"},"pattern_id":{"type":"string"}},"required":["key","method","label_vi","delta","ok"]}},"lines":{"type":"array","items":{"type":"object","properties":{"target_type":{"type":"string","enum":["invoice","order","expected_payment"]},"target_id":{"type":"string"},"amount":{"$ref":"#/components/schemas/PositiveVnd"},"label":{"type":"string"},"outstanding":{"$ref":"#/components/schemas/Vnd"},"total":{"$ref":"#/components/schemas/Vnd"}},"required":["target_type","target_id","amount"]}},"overpay_amount":{"$ref":"#/components/schemas/Vnd"},"group_id":{"type":"string"},"payer_name":{"type":"string"},"payer_mst":{"type":"string"},"payer_source":{"type":"string"}},"required":["id","tx_id","kind","rule_key","confidence","reasons","lines"]}}},"required":["tx_id","suggestions"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/transactions/{id}:ignore-recon":{"post":{"operationId":"ignoreReconTx","summary":"Đánh dấu giao dịch không cần đối soát","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/TxId"},"required":true,"description":"Mã giao dịch (`tx_…`), ổn định vĩnh viễn kể cả khi bị gộp.","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"reason":"Giao dịch chuyển khoản nội bộ giữa các tài khoản của công ty."},"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"Đã cập nhật trạng thái không cần đối soát","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"tx_id":{"$ref":"#/components/schemas/TxId"},"recon_status":{"type":"string","enum":["not_required"]}},"required":["tx_id","recon_status"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/transactions/{id}:route-settlement":{"post":{"operationId":"routeSettlementTx","summary":"Chuyển giao dịch payout sang đối soát sàn (Settlement)","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/TxId"},"required":true,"description":"Mã giao dịch (`tx_…`), ổn định vĩnh viễn kể cả khi bị gộp.","name":"id","in":"path"}],"responses":{"200":{"description":"Đã chuyển sang settlement","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"tx_id":{"$ref":"#/components/schemas/TxId"},"recon_status":{"type":"string","enum":["routed_settlement"]}},"required":["tx_id","recon_status"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/allocations":{"get":{"operationId":"listAllocations","summary":"Danh sách phân bổ đối soát","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-scope":"reconcile:propose","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"type":"string","enum":["draft","pending_approval","approved","rejected","withdrawn","reversed"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["me","any"]},"required":false,"name":"approver","in":"query"},{"schema":{"$ref":"#/components/schemas/TxId"},"required":false,"description":"Mã giao dịch (`tx_…`), ổn định vĩnh viễn kể cả khi bị gộp.","name":"tx_id","in":"query"}],"responses":{"200":{"description":"Danh sách phân bổ","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllocationList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createAllocation","summary":"Tạo bản nháp phân bổ đối soát","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-scope":"reconcile:propose","x-dt-idempotent":"required","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ. Bắt buộc ở máy chủ (thiếu → 400 idempotency_key_required); SDK tự sinh."},"required":false,"description":"Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ. Bắt buộc ở máy chủ (thiếu → 400 idempotency_key_required); SDK tự sinh.","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tx_id":{"$ref":"#/components/schemas/TxId"},"lines":{"type":"array","items":{"type":"object","properties":{"target_type":{"type":"string","enum":["invoice","order","expected_payment"]},"target_id":{"type":"string","minLength":1,"maxLength":128},"amount":{"$ref":"#/components/schemas/PositiveVnd"},"note":{"type":"string","maxLength":500}},"required":["target_type","target_id","amount"]},"minItems":1,"maxItems":20},"overpay_amount":{"$ref":"#/components/schemas/Vnd"},"overpay_handling":{"type":"string","enum":["customer_advance","refund_reminder","allocate_other"]},"rounding_diff":{"$ref":"#/components/schemas/Vnd"},"group_id":{"type":"string","maxLength":64},"note":{"type":"string","maxLength":500}},"required":["tx_id","lines"]}}}},"responses":{"201":{"description":"Phân bổ đã được tạo ở trạng thái draft","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Allocation"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `idempotency_key_required` — Thiếu header Idempotency-Key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái; `idempotency_in_flight` — Yêu cầu cùng Idempotency-Key đang xử lý.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ; `idempotency_key_reused` — Idempotency-Key đã dùng cho yêu cầu khác.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/allocations/{id}":{"get":{"operationId":"getAllocation","summary":"Chi tiết phân bổ đối soát","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AllocationId"},"required":true,"description":"Mã phân bổ đối soát (`alc_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Chi tiết phân bổ","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Allocation"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"updateAllocation","summary":"Cập nhật bản nháp phân bổ đối soát","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AllocationId"},"required":true,"description":"Mã phân bổ đối soát (`alc_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"target_type":{"type":"string","enum":["invoice","order","expected_payment"]},"target_id":{"type":"string","minLength":1,"maxLength":128},"amount":{"$ref":"#/components/schemas/PositiveVnd"},"note":{"type":"string","maxLength":500}},"required":["target_type","target_id","amount"]},"minItems":1,"maxItems":20},"overpay_amount":{"$ref":"#/components/schemas/Vnd"},"overpay_handling":{"type":"string","enum":["customer_advance","refund_reminder","allocate_other"]},"rounding_diff":{"$ref":"#/components/schemas/Vnd"},"note":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"Bản nháp đã cập nhật","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Allocation"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteAllocation","summary":"Xoá bản nháp phân bổ","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AllocationId"},"required":true,"description":"Mã phân bổ đối soát (`alc_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Đã xoá bản nháp","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/allocations/{id}:submit":{"post":{"operationId":"submitAllocation","summary":"Gửi phân bổ để phê duyệt (maker)","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-scope":"reconcile:propose","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AllocationId"},"required":true,"description":"Mã phân bổ đối soát (`alc_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Phân bổ đã chuyển sang pending_approval","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Allocation"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/allocations/{id}:withdraw":{"post":{"operationId":"withdrawAllocation","summary":"Rút lại phân bổ đang chờ duyệt (maker)","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.withdraw","x-dt-scope":"reconcile:propose","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AllocationId"},"required":true,"description":"Mã phân bổ đối soát (`alc_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Phân bổ đã rút về draft/withdrawn","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Allocation"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/allocations/{id}:approve":{"post":{"operationId":"approveAllocation","summary":"Duyệt phân bổ đối soát (checker)","description":"Checker phải khác maker trừ ngoại lệ D41 (org 1 người, khớp 100%, < 20M). Từ 100M cần accountant_chief.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.approve","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AllocationId"},"required":true,"description":"Mã phân bổ đối soát (`alc_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"example":{},"schema":{"type":"object","properties":{"biometric_assertion":{"type":"object","properties":{"key_id":{"type":"string","minLength":1,"maxLength":128},"nonce":{"type":"string","pattern":"^[0-9a-fA-F]+$"},"signature":{"type":"string","pattern":"^[0-9a-fA-F]+$"}},"required":["key_id","nonce","signature"]}}}}}},"responses":{"200":{"description":"Phân bổ đã được duyệt","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Allocation"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/allocations/{id}:reject":{"post":{"operationId":"rejectAllocation","summary":"Từ chối phân bổ đối soát","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.reject","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AllocationId"},"required":true,"description":"Mã phân bổ đối soát (`alc_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"reason":"wrong_amount","note":"Số tiền phân bổ không khớp với hoá đơn."},"schema":{"type":"object","properties":{"reason":{"type":"string","enum":["wrong_invoice","wrong_amount","need_documents","other"]},"note":{"type":"string","minLength":1,"maxLength":500}},"required":["reason","note"]}}}},"responses":{"200":{"description":"Phân bổ đã bị từ chối","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Allocation"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/allocations/{id}:reverse":{"post":{"operationId":"reverseAllocation","summary":"Đảo phân bổ đã duyệt","description":"Sinh dòng âm và đảo trạng thái ghi ngược hoadon.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.approve","x-dt-step-up":true,"x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AllocationId"},"required":true,"description":"Mã phân bổ đối soát (`alc_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"reason":"Phân bổ nhầm hoá đơn, cần đảo để phân bổ lại."},"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"]}}}},"responses":{"200":{"description":"Phân bổ đã được đảo","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Allocation"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này; `step_up_required` — Cần xác thực lại gần đây.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/allocations:approve-batch":{"post":{"operationId":"approveBatchAllocations","summary":"Duyệt hàng loạt phân bổ (tối đa 50 dòng)","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.approve","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"$ref":"#/components/schemas/AllocationId"},"minItems":1,"maxItems":50}},"required":["ids"]}}}},"responses":{"200":{"description":"Kết quả duyệt hàng loạt","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"approved":{"type":"array","items":{"$ref":"#/components/schemas/AllocationId"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AllocationId"},"error":{"type":"string"},"code":{"type":"string"}},"required":["id","error"]}}},"required":["approved","failed"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/allocations/{id}/writeback":{"get":{"operationId":"getAllocationWriteback","summary":"Trạng thái ghi ngược hoadon.pro của phân bổ","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AllocationId"},"required":true,"description":"Mã phân bổ đối soát (`alc_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Danh sách writeback","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"allocation_id":{"$ref":"#/components/schemas/AllocationId"},"writebacks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"line_id":{"type":"string"},"target_invoice_id":{"type":"string"},"state":{"type":"string"},"attempts":{"type":"integer"},"last_error":{"type":["string","null"]},"hoadon_payment_id":{"type":["string","null"]}},"required":["id","line_id","target_invoice_id","state","attempts","last_error","hoadon_payment_id"]}}},"required":["allocation_id","writebacks"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/allocations/{id}:retry-writeback":{"post":{"operationId":"retryAllocationWriteback","summary":"Thử lại ghi ngược thanh toán sang hoadon.pro","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"hoadon.writeback.retry","x-dt-rate-class":"replay","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/AllocationId"},"required":true,"description":"Mã phân bổ đối soát (`alc_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Đã đưa vào hàng đợi thử lại","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"retried_count":{"type":"integer"}},"required":["retried_count"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/recon-rules":{"get":{"operationId":"listReconRules","summary":"Danh sách quy tắc gợi ý đối soát","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"rule.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"}],"responses":{"200":{"description":"Danh sách quy tắc","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchRuleList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createReconRule","summary":"Tạo quy tắc gợi ý mới (không có auto_post)","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"rule.manage","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"}],"requestBody":{"content":{"application/json":{"example":{"name":"Khớp đúng số tiền và mã đơn hàng","direction":"in","strategy":"one_to_one","priority":50,"conds":[{"field":"tx.content","op":"contains","value":"DH"}],"tolerance_vnd":1000,"window_days":45,"mode":"suggest_only","is_enabled":true},"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"description":{"type":"string","maxLength":500},"kind_label":{"type":"string","maxLength":64},"direction":{"type":"string","enum":["in","out","both"]},"strategy":{"type":"string","enum":["one_to_one","one_to_many","many_to_one"]},"priority":{"type":"integer","minimum":1,"maximum":100,"default":50},"base_confidence":{"type":["number","null"],"minimum":0,"maximum":100},"conds":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string","enum":["=","exists","<",">","<=",">=","in","contains"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"required":["field","op","value"]}},"bonus":{"type":"array","items":{"type":"object","properties":{"tone":{"type":"string","enum":["y","w","n"]},"description":{"type":"string"},"delta":{"type":"number"}},"required":["tone","description"]}},"tolerance_vnd":{"type":"integer","minimum":0,"maximum":1000000,"default":1000},"window_days":{"type":"integer","minimum":1,"maximum":365,"default":45},"mode":{"type":"string","enum":["suggest_only","one_tap_ge_95"],"default":"suggest_only"},"is_enabled":{"type":"boolean","default":true}},"required":["name","direction","strategy","conds"]}}}},"responses":{"201":{"description":"Quy tắc mới đã tạo","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/MatchRuleId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"name":{"type":"string"},"description":{"type":"string"},"kind_label":{"type":"string"},"direction":{"type":"string","enum":["in","out","both"]},"strategy":{"type":"string","enum":["one_to_one","one_to_many","many_to_one"]},"priority":{"type":"integer"},"base_confidence":{"type":["number","null"]},"conds":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string","enum":["=","exists","<",">","<=",">=","in","contains"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"required":["field","op","value"]}},"bonus":{"type":"array","items":{"type":"object","properties":{"tone":{"type":"string","enum":["y","w","n"]},"description":{"type":"string"},"delta":{"type":"number"}},"required":["tone","description"]}},"tolerance_vnd":{"type":"integer","default":1000},"window_days":{"type":"integer","default":45},"mode":{"type":"string","enum":["suggest_only","one_tap_ge_95"]},"is_enabled":{"type":"boolean"},"is_locked":{"type":"boolean"},"version":{"type":"integer"},"eval_count_30d":{"type":"integer"},"accepted_count_30d":{"type":"integer"},"acceptance_rate_30d":{"type":"number"},"flagged_review":{"type":"boolean"}},"required":["id","org_id","name","description","kind_label","direction","strategy","priority","base_confidence","conds","mode","is_enabled","is_locked","version"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/recon-rules/{id}":{"get":{"operationId":"getReconRule","summary":"Chi tiết quy tắc đối soát","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"rule.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/MatchRuleId"},"required":true,"description":"Mã quy tắc đối soát (`rul_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Chi tiết quy tắc","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/MatchRuleId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"name":{"type":"string"},"description":{"type":"string"},"kind_label":{"type":"string"},"direction":{"type":"string","enum":["in","out","both"]},"strategy":{"type":"string","enum":["one_to_one","one_to_many","many_to_one"]},"priority":{"type":"integer"},"base_confidence":{"type":["number","null"]},"conds":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string","enum":["=","exists","<",">","<=",">=","in","contains"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"required":["field","op","value"]}},"bonus":{"type":"array","items":{"type":"object","properties":{"tone":{"type":"string","enum":["y","w","n"]},"description":{"type":"string"},"delta":{"type":"number"}},"required":["tone","description"]}},"tolerance_vnd":{"type":"integer","default":1000},"window_days":{"type":"integer","default":45},"mode":{"type":"string","enum":["suggest_only","one_tap_ge_95"]},"is_enabled":{"type":"boolean"},"is_locked":{"type":"boolean"},"version":{"type":"integer"},"eval_count_30d":{"type":"integer"},"accepted_count_30d":{"type":"integer"},"acceptance_rate_30d":{"type":"number"},"flagged_review":{"type":"boolean"}},"required":["id","org_id","name","description","kind_label","direction","strategy","priority","base_confidence","conds","mode","is_enabled","is_locked","version"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"operationId":"updateReconRule","summary":"Cập nhật quy tắc đối soát (tạo phiên bản mới)","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"rule.manage","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/MatchRuleId"},"required":true,"description":"Mã quy tắc đối soát (`rul_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"description":{"type":"string","maxLength":500},"kind_label":{"type":"string","maxLength":64},"direction":{"type":"string","enum":["in","out","both"]},"strategy":{"type":"string","enum":["one_to_one","one_to_many","many_to_one"]},"priority":{"type":"integer","minimum":1,"maximum":100},"base_confidence":{"type":["number","null"],"minimum":0,"maximum":100},"conds":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string","enum":["=","exists","<",">","<=",">=","in","contains"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"required":["field","op","value"]}},"bonus":{"type":"array","items":{"type":"object","properties":{"tone":{"type":"string","enum":["y","w","n"]},"description":{"type":"string"},"delta":{"type":"number"}},"required":["tone","description"]}},"tolerance_vnd":{"type":"integer","minimum":0,"maximum":1000000},"window_days":{"type":"integer","minimum":1,"maximum":365},"mode":{"type":"string","enum":["suggest_only","one_tap_ge_95"]},"is_enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Quy tắc đã được cập nhật phiên bản mới","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/MatchRuleId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"name":{"type":"string"},"description":{"type":"string"},"kind_label":{"type":"string"},"direction":{"type":"string","enum":["in","out","both"]},"strategy":{"type":"string","enum":["one_to_one","one_to_many","many_to_one"]},"priority":{"type":"integer"},"base_confidence":{"type":["number","null"]},"conds":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string","enum":["=","exists","<",">","<=",">=","in","contains"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"required":["field","op","value"]}},"bonus":{"type":"array","items":{"type":"object","properties":{"tone":{"type":"string","enum":["y","w","n"]},"description":{"type":"string"},"delta":{"type":"number"}},"required":["tone","description"]}},"tolerance_vnd":{"type":"integer","default":1000},"window_days":{"type":"integer","default":45},"mode":{"type":"string","enum":["suggest_only","one_tap_ge_95"]},"is_enabled":{"type":"boolean"},"is_locked":{"type":"boolean"},"version":{"type":"integer"},"eval_count_30d":{"type":"integer"},"accepted_count_30d":{"type":"integer"},"acceptance_rate_30d":{"type":"number"},"flagged_review":{"type":"boolean"}},"required":["id","org_id","name","description","kind_label","direction","strategy","priority","base_confidence","conds","mode","is_enabled","is_locked","version"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteReconRule","summary":"Xoá quy tắc đối soát","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"rule.manage","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/MatchRuleId"},"required":true,"description":"Mã quy tắc đối soát (`rul_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Đã xoá quy tắc","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/recon-rules/{id}:dry-run":{"post":{"operationId":"dryRunReconRule","summary":"Chạy thử quy tắc trên 30 ngày (không ghi sổ)","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"rule.read","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/MatchRuleId"},"required":true,"description":"Mã quy tắc đối soát (`rul_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"rule":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"description":{"type":"string","maxLength":500},"kind_label":{"type":"string","maxLength":64},"direction":{"type":"string","enum":["in","out","both"]},"strategy":{"type":"string","enum":["one_to_one","one_to_many","many_to_one"]},"priority":{"type":"integer","minimum":1,"maximum":100,"default":50},"base_confidence":{"type":["number","null"],"minimum":0,"maximum":100},"conds":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string","enum":["=","exists","<",">","<=",">=","in","contains"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"required":["field","op","value"]}},"bonus":{"type":"array","items":{"type":"object","properties":{"tone":{"type":"string","enum":["y","w","n"]},"description":{"type":"string"},"delta":{"type":"number"}},"required":["tone","description"]}},"tolerance_vnd":{"type":"integer","minimum":0,"maximum":1000000,"default":1000},"window_days":{"type":"integer","minimum":1,"maximum":365,"default":45},"mode":{"type":"string","enum":["suggest_only","one_tap_ge_95"],"default":"suggest_only"},"is_enabled":{"type":"boolean","default":true}},"required":["name","direction","strategy","conds"]},"window_days":{"type":"integer","minimum":1,"maximum":90,"default":30},"limit":{"type":"integer","minimum":1,"maximum":2000,"default":500}},"required":["rule"]}}}},"responses":{"200":{"description":"Kết quả chạy thử","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"matched_count":{"type":"integer"},"would_accept_count":{"type":"integer"},"sample_matches":{"type":"array","items":{"type":"object","properties":{"tx_id":{"$ref":"#/components/schemas/TxId"},"amount":{"$ref":"#/components/schemas/Vnd"},"confidence":{"type":"number"},"reasons":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"method":{"type":"string","enum":["exact","pattern","trgm","masothue","org_memo_regex","dsl"]},"label_vi":{"type":"string"},"delta":{"type":"number"},"ok":{"type":"boolean"},"captured":{"type":"string"},"pattern_id":{"type":"string"}},"required":["key","method","label_vi","delta","ok"]}},"candidate_lines":{"type":"array","items":{"type":"object","properties":{"target_id":{"type":"string"},"target_type":{"type":"string","enum":["invoice","order","expected_payment"]},"amount":{"$ref":"#/components/schemas/Vnd"}},"required":["target_id","target_type","amount"]}}},"required":["tx_id","amount","confidence","reasons","candidate_lines"]}}},"required":["matched_count","would_accept_count","sample_matches"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/recon-rules/{id}:enable":{"post":{"operationId":"enableReconRule","summary":"Bật quy tắc đối soát","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"rule.manage","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/MatchRuleId"},"required":true,"description":"Mã quy tắc đối soát (`rul_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Đã bật quy tắc","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/MatchRuleId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"name":{"type":"string"},"description":{"type":"string"},"kind_label":{"type":"string"},"direction":{"type":"string","enum":["in","out","both"]},"strategy":{"type":"string","enum":["one_to_one","one_to_many","many_to_one"]},"priority":{"type":"integer"},"base_confidence":{"type":["number","null"]},"conds":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string","enum":["=","exists","<",">","<=",">=","in","contains"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"required":["field","op","value"]}},"bonus":{"type":"array","items":{"type":"object","properties":{"tone":{"type":"string","enum":["y","w","n"]},"description":{"type":"string"},"delta":{"type":"number"}},"required":["tone","description"]}},"tolerance_vnd":{"type":"integer","default":1000},"window_days":{"type":"integer","default":45},"mode":{"type":"string","enum":["suggest_only","one_tap_ge_95"]},"is_enabled":{"type":"boolean"},"is_locked":{"type":"boolean"},"version":{"type":"integer"},"eval_count_30d":{"type":"integer"},"accepted_count_30d":{"type":"integer"},"acceptance_rate_30d":{"type":"number"},"flagged_review":{"type":"boolean"}},"required":["id","org_id","name","description","kind_label","direction","strategy","priority","base_confidence","conds","mode","is_enabled","is_locked","version"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/recon-rules/{id}:disable":{"post":{"operationId":"disableReconRule","summary":"Tắt quy tắc đối soát","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"rule.manage","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/MatchRuleId"},"required":true,"description":"Mã quy tắc đối soát (`rul_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Đã tắt quy tắc","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/MatchRuleId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"name":{"type":"string"},"description":{"type":"string"},"kind_label":{"type":"string"},"direction":{"type":"string","enum":["in","out","both"]},"strategy":{"type":"string","enum":["one_to_one","one_to_many","many_to_one"]},"priority":{"type":"integer"},"base_confidence":{"type":["number","null"]},"conds":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string","enum":["=","exists","<",">","<=",">=","in","contains"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"required":["field","op","value"]}},"bonus":{"type":"array","items":{"type":"object","properties":{"tone":{"type":"string","enum":["y","w","n"]},"description":{"type":"string"},"delta":{"type":"number"}},"required":["tone","description"]}},"tolerance_vnd":{"type":"integer","default":1000},"window_days":{"type":"integer","default":45},"mode":{"type":"string","enum":["suggest_only","one_tap_ge_95"]},"is_enabled":{"type":"boolean"},"is_locked":{"type":"boolean"},"version":{"type":"integer"},"eval_count_30d":{"type":"integer"},"accepted_count_30d":{"type":"integer"},"acceptance_rate_30d":{"type":"number"},"flagged_review":{"type":"boolean"}},"required":["id","org_id","name","description","kind_label","direction","strategy","priority","base_confidence","conds","mode","is_enabled","is_locked","version"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/recon-settings":{"get":{"operationId":"getReconSettings","summary":"Cài đặt dung sai & phạm vi đối soát","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"rule.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"}],"responses":{"200":{"description":"Cài đặt đối soát","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"tolerance_vnd":{"type":"integer","default":1000},"invoice_window_days":{"type":"integer","default":45},"suggest_on_provisional":{"type":"boolean","default":true},"issued_only":{"type":"boolean","default":true},"large_amount_threshold":{"$ref":"#/components/schemas/Vnd"},"solo_self_approve_limit":{"$ref":"#/components/schemas/Vnd"}}}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"operationId":"updateReconSettings","summary":"Cập nhật cài đặt dung sai & phạm vi đối soát","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"recon.settings.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tolerance_vnd":{"type":"integer","minimum":0,"maximum":1000000},"invoice_window_days":{"type":"integer","minimum":1,"maximum":365},"suggest_on_provisional":{"type":"boolean"},"issued_only":{"type":"boolean"},"large_amount_threshold":{"$ref":"#/components/schemas/Vnd"},"solo_self_approve_limit":{"$ref":"#/components/schemas/Vnd"}}}}}},"responses":{"200":{"description":"Cài đặt đã cập nhật","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"tolerance_vnd":{"type":"integer","default":1000},"invoice_window_days":{"type":"integer","default":45},"suggest_on_provisional":{"type":"boolean","default":true},"issued_only":{"type":"boolean","default":true},"large_amount_threshold":{"$ref":"#/components/schemas/Vnd"},"solo_self_approve_limit":{"$ref":"#/components/schemas/Vnd"}}}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/invoices":{"get":{"operationId":"listInvoices","summary":"Danh sách hoá đơn đồng bộ từ hoadon.pro","tags":["Hoá đơn"],"security":[{"bearerAuth":[]}],"x-dt-permission":"invoice.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"type":"string","enum":["in","out"]},"required":false,"name":"direction","in":"query"},{"schema":{"type":"string","enum":["unpaid","partially_paid","paid","overpaid"]},"required":false,"name":"payment_status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"buyer_tax_code","in":"query"},{"schema":{"type":"string"},"required":false,"name":"seller_tax_code","in":"query"}],"responses":{"200":{"description":"Danh sách hoá đơn","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceRefList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/invoices/{id}":{"get":{"operationId":"getInvoice","summary":"Chi tiết hoá đơn điện tử","tags":["Hoá đơn"],"security":[{"bearerAuth":[]}],"x-dt-permission":"invoice.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/InvoiceRefId"},"required":true,"description":"Mã tham chiếu hoá đơn (`inv_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Chi tiết hoá đơn","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/InvoiceRefId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"direction":{"type":"string","enum":["in","out"]},"seller_tax_code":{"type":"string"},"seller_name":{"type":"string"},"buyer_tax_code":{"type":["string","null"]},"buyer_name":{"type":["string","null"]},"template_code":{"type":"string"},"series":{"type":"string"},"number":{"type":"string"},"issue_date":{"$ref":"#/components/schemas/Timestamp"},"due_date":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"currency":{"$ref":"#/components/schemas/Currency"},"total_amount":{"$ref":"#/components/schemas/Vnd"},"external_paid":{"$ref":"#/components/schemas/Vnd"},"dtp_allocated":{"$ref":"#/components/schemas/Vnd"},"outstanding_amount":{"$ref":"#/components/schemas/Vnd"},"payment_status":{"type":"string","enum":["unpaid","partially_paid","paid","overpaid"]},"lookup_code":{"type":["string","null"]},"hoadon_id":{"type":["string","null"]}},"required":["id","org_id","direction","seller_tax_code","seller_name","template_code","series","number","issue_date","total_amount","outstanding_amount","payment_status"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/invoices/search":{"get":{"operationId":"searchInvoices","summary":"Tìm kiếm hoá đơn","tags":["Hoá đơn"],"security":[{"bearerAuth":[]}],"x-dt-permission":"invoice.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":true,"name":"q","in":"query"},{"schema":{"type":"string","enum":["in","out"]},"required":false,"name":"direction","in":"query"}],"responses":{"200":{"description":"Kết quả tìm kiếm","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/InvoiceRefId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"direction":{"type":"string","enum":["in","out"]},"seller_tax_code":{"type":"string"},"seller_name":{"type":"string"},"buyer_tax_code":{"type":["string","null"]},"buyer_name":{"type":["string","null"]},"template_code":{"type":"string"},"series":{"type":"string"},"number":{"type":"string"},"issue_date":{"$ref":"#/components/schemas/Timestamp"},"due_date":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"currency":{"$ref":"#/components/schemas/Currency"},"total_amount":{"$ref":"#/components/schemas/Vnd"},"external_paid":{"$ref":"#/components/schemas/Vnd"},"dtp_allocated":{"$ref":"#/components/schemas/Vnd"},"outstanding_amount":{"$ref":"#/components/schemas/Vnd"},"payment_status":{"type":"string","enum":["unpaid","partially_paid","paid","overpaid"]},"lookup_code":{"type":["string","null"]},"hoadon_id":{"type":["string","null"]}},"required":["id","org_id","direction","seller_tax_code","seller_name","template_code","series","number","issue_date","total_amount","outstanding_amount","payment_status"]}}},"required":["items"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integrations/hoadon-pro":{"get":{"operationId":"getHoadonConnection","summary":"Trạng thái kết nối hoadon.pro","tags":["Hoá đơn"],"security":[{"bearerAuth":[]}],"x-dt-permission":"invoice.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"}],"responses":{"200":{"description":"Trạng thái kết nối","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"connected":{"type":"boolean"},"connection":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/HoadonConnectionId"},"auth_mode":{"type":"string","enum":["api_key"]},"key_last4":{"type":"string"},"write_enabled":{"type":"boolean"},"webhooks_api":{"type":"boolean"},"sync_state":{"type":"string","enum":["idle","syncing","reauth_required","error"]},"last_synced_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"last_error":{"type":["string","null"]},"webhook_subscription_id":{"type":["string","null"]},"org_count":{"type":"integer"}},"required":["id","auth_mode","key_last4","write_enabled","webhooks_api","sync_state","last_synced_at","last_error","webhook_subscription_id","org_count"]},"org_map":{"type":"array","items":{"type":"object","properties":{"mst":{"type":"string"},"hoadon_org_id":{"type":"string"},"hoadon_org_name":{"type":["string","null"]}},"required":["mst","hoadon_org_id","hoadon_org_name"]}}},"required":["connected","org_map"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/integrations/hoadon-pro:connect":{"post":{"operationId":"connectHoadon","summary":"Kết nối hoadon.pro bằng API key (D37)","description":"Probe capabilities (invoices.read, invoice.payment.write, webhook.manage), seal key và đăng ký webhook tự động.","tags":["Hoá đơn"],"security":[{"bearerAuth":[]}],"x-dt-permission":"hoadon.connect","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"example":{"api_key":"hd_live_9f2c4a7e1b3d5f60","mst_map":[{"mst":"0312345678","hoadon_org_id":"hdorg_0001","hoadon_org_name":"Công ty TNHH Thương mại Sao Việt"}],"backfill_days":90},"schema":{"type":"object","properties":{"api_key":{"type":"string","pattern":"^hd_live_[A-Za-z0-9_-]+$"},"mst_map":{"type":"array","items":{"type":"object","properties":{"mst":{"type":"string","minLength":10,"maxLength":14},"hoadon_org_id":{"type":"string","minLength":1},"hoadon_org_name":{"type":"string"}},"required":["mst","hoadon_org_id"]},"minItems":1},"backfill_days":{"type":"integer","minimum":1,"maximum":365,"default":90},"company_id":{"$ref":"#/components/schemas/OrgId"}},"required":["api_key","mst_map"]}}}},"responses":{"200":{"description":"Kết nối thành công","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"connected":{"type":"boolean"},"connection":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/HoadonConnectionId"},"auth_mode":{"type":"string","enum":["api_key"]},"key_last4":{"type":"string"},"write_enabled":{"type":"boolean"},"webhooks_api":{"type":"boolean"},"sync_state":{"type":"string","enum":["idle","syncing","reauth_required","error"]},"last_synced_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"last_error":{"type":["string","null"]},"webhook_subscription_id":{"type":["string","null"]},"org_count":{"type":"integer"}},"required":["id","auth_mode","key_last4","write_enabled","webhooks_api","sync_state","last_synced_at","last_error","webhook_subscription_id","org_count"]},"org_map":{"type":"array","items":{"type":"object","properties":{"mst":{"type":"string"},"hoadon_org_id":{"type":"string"},"hoadon_org_name":{"type":["string","null"]}},"required":["mst","hoadon_org_id","hoadon_org_name"]}}},"required":["connected","org_map"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/integrations/hoadon-pro:disconnect":{"post":{"operationId":"disconnectHoadon","summary":"Ngắt kết nối hoadon.pro","tags":["Hoá đơn"],"security":[{"bearerAuth":[]}],"x-dt-permission":"hoadon.connect","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"company_id":{"$ref":"#/components/schemas/OrgId"}}}}}},"responses":{"200":{"description":"Đã ngắt kết nối","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/integrations/hoadon-pro:sync":{"post":{"operationId":"syncHoadon","summary":"Đồng bộ thủ công hoá đơn từ hoadon.pro","tags":["Hoá đơn"],"security":[{"bearerAuth":[]}],"x-dt-permission":"hoadon.connect","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"company_id":{"$ref":"#/components/schemas/OrgId"},"backfill_days":{"type":"integer","minimum":1,"maximum":365}}}}}},"responses":{"200":{"description":"Kết quả đồng bộ","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"synced_count":{"type":"integer"}},"required":["synced_count"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/counterparties":{"get":{"operationId":"listCounterparties","summary":"Danh sách đối tượng (khách hàng, nhà cung cấp)","tags":["Đối tác"],"security":[{"bearerAuth":[]}],"x-dt-permission":"counterparty.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"type":"string","enum":["customer","vendor","both","retail_customer","marketplace","other"]},"required":false,"name":"kind","in":"query"},{"schema":{"type":"string"},"required":false,"name":"q","in":"query"}],"responses":{"200":{"description":"Danh sách đối tác","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CounterpartyList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createCounterparty","summary":"Tạo đối tượng mới","tags":["Đối tác"],"security":[{"bearerAuth":[]}],"x-dt-permission":"counterparty.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"}],"requestBody":{"content":{"application/json":{"example":{"name":"Công ty TNHH Thương mại Sao Việt","kind":"customer","tax_code":"0312345678","address":"25 Nguyễn Huệ, Phường Bến Nghé, Quận 1, TP. Hồ Chí Minh","phone":"0901234567","email":"ketoan@saoviet.vn","bank_accounts":[{"bank_code":"VCB","account_number":"0011004567890","account_holder":"CONG TY TNHH THUONG MAI SAO VIET"}]},"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"kind":{"type":"string","enum":["customer","vendor","both","retail_customer","marketplace","other"],"default":"customer"},"tax_code":{"type":"string","maxLength":32},"address":{"type":"string","maxLength":500},"phone":{"type":"string","maxLength":32},"email":{"type":"string","format":"email"},"notes":{"type":"string","maxLength":1000},"bank_accounts":{"type":"array","items":{"type":"object","properties":{"bank_code":{"type":"string"},"account_number":{"type":"string"},"account_holder":{"type":"string"}},"required":["bank_code","account_number"]}}},"required":["name"]}}}},"responses":{"201":{"description":"Đối tác đã được tạo","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/CounterpartyId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"name":{"type":"string"},"name_norm":{"type":"string"},"kind":{"type":"string","enum":["customer","vendor","both","retail_customer","marketplace","other"]},"tax_code":{"type":["string","null"]},"tax_status":{"type":["string","null"]},"tax_status_checked_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"tax_status_stale":{"type":"boolean"},"address":{"type":["string","null"]},"phone":{"type":["string","null"]},"email":{"type":["string","null"]},"notes":{"type":["string","null"]},"bank_accounts":{"type":"array","items":{"type":"object","properties":{"bank_code":{"type":"string"},"account_number":{"type":"string"},"account_holder":{"type":"string"}},"required":["bank_code","account_number"]},"default":[]},"total_90d":{"$ref":"#/components/schemas/Vnd"},"tx_count_90d":{"type":"integer","default":0},"last_tx_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["id","org_id","name","name_norm","kind"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/counterparties/{id}":{"get":{"operationId":"getCounterparty","summary":"Chi tiết đối tượng","tags":["Đối tác"],"security":[{"bearerAuth":[]}],"x-dt-permission":"counterparty.read","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/CounterpartyId"},"required":true,"description":"Mã đối tác (`cpt_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Chi tiết đối tác","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/CounterpartyId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"name":{"type":"string"},"name_norm":{"type":"string"},"kind":{"type":"string","enum":["customer","vendor","both","retail_customer","marketplace","other"]},"tax_code":{"type":["string","null"]},"tax_status":{"type":["string","null"]},"tax_status_checked_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"tax_status_stale":{"type":"boolean"},"address":{"type":["string","null"]},"phone":{"type":["string","null"]},"email":{"type":["string","null"]},"notes":{"type":["string","null"]},"bank_accounts":{"type":"array","items":{"type":"object","properties":{"bank_code":{"type":"string"},"account_number":{"type":"string"},"account_holder":{"type":"string"}},"required":["bank_code","account_number"]},"default":[]},"total_90d":{"$ref":"#/components/schemas/Vnd"},"tx_count_90d":{"type":"integer","default":0},"last_tx_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["id","org_id","name","name_norm","kind"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"updateCounterparty","summary":"Cập nhật đối tượng","tags":["Đối tác"],"security":[{"bearerAuth":[]}],"x-dt-permission":"counterparty.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/CounterpartyId"},"required":true,"description":"Mã đối tác (`cpt_…`).","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"kind":{"type":"string","enum":["customer","vendor","both","retail_customer","marketplace","other"]},"tax_code":{"type":"string","maxLength":32},"address":{"type":"string","maxLength":500},"phone":{"type":"string","maxLength":32},"email":{"type":"string","format":"email"},"notes":{"type":"string","maxLength":1000},"bank_accounts":{"type":"array","items":{"type":"object","properties":{"bank_code":{"type":"string"},"account_number":{"type":"string"},"account_holder":{"type":"string"}},"required":["bank_code","account_number"]}}}}}}},"responses":{"200":{"description":"Đối tác đã cập nhật","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/CounterpartyId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"name":{"type":"string"},"name_norm":{"type":"string"},"kind":{"type":"string","enum":["customer","vendor","both","retail_customer","marketplace","other"]},"tax_code":{"type":["string","null"]},"tax_status":{"type":["string","null"]},"tax_status_checked_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"tax_status_stale":{"type":"boolean"},"address":{"type":["string","null"]},"phone":{"type":["string","null"]},"email":{"type":["string","null"]},"notes":{"type":["string","null"]},"bank_accounts":{"type":"array","items":{"type":"object","properties":{"bank_code":{"type":"string"},"account_number":{"type":"string"},"account_holder":{"type":"string"}},"required":["bank_code","account_number"]},"default":[]},"total_90d":{"$ref":"#/components/schemas/Vnd"},"tx_count_90d":{"type":"integer","default":0},"last_tx_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["id","org_id","name","name_norm","kind"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/counterparties/{id}:refresh-tax-status":{"post":{"operationId":"refreshCounterpartyTaxStatus","summary":"Làm mới trạng thái thuế từ masothue.pro","tags":["Đối tác"],"security":[{"bearerAuth":[]}],"x-dt-permission":"counterparty.write","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/CounterpartyId"},"required":true,"description":"Mã đối tác (`cpt_…`).","name":"id","in":"path"}],"responses":{"200":{"description":"Trạng thái thuế đã làm mới","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/CounterpartyId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"name":{"type":"string"},"name_norm":{"type":"string"},"kind":{"type":"string","enum":["customer","vendor","both","retail_customer","marketplace","other"]},"tax_code":{"type":["string","null"]},"tax_status":{"type":["string","null"]},"tax_status_checked_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"tax_status_stale":{"type":"boolean"},"address":{"type":["string","null"]},"phone":{"type":["string","null"]},"email":{"type":["string","null"]},"notes":{"type":["string","null"]},"bank_accounts":{"type":"array","items":{"type":"object","properties":{"bank_code":{"type":"string"},"account_number":{"type":"string"},"account_holder":{"type":"string"}},"required":["bank_code","account_number"]},"default":[]},"total_90d":{"$ref":"#/components/schemas/Vnd"},"tx_count_90d":{"type":"integer","default":0},"last_tx_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["id","org_id","name","name_norm","kind"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Mã `code` có thể gặp: `resource_not_found` — Không tìm thấy.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/counterparties:merge":{"post":{"operationId":"mergeCounterparties","summary":"Gộp 2 đối tượng trong cùng công ty","tags":["Đối tác"],"security":[{"bearerAuth":[]}],"x-dt-permission":"counterparty.merge","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_id":{"$ref":"#/components/schemas/CounterpartyId"},"target_id":{"$ref":"#/components/schemas/CounterpartyId"}},"required":["source_id","target_id"]}}}},"responses":{"200":{"description":"Gộp thành công","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/CounterpartyId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"name":{"type":"string"},"name_norm":{"type":"string"},"kind":{"type":"string","enum":["customer","vendor","both","retail_customer","marketplace","other"]},"tax_code":{"type":["string","null"]},"tax_status":{"type":["string","null"]},"tax_status_checked_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"tax_status_stale":{"type":"boolean"},"address":{"type":["string","null"]},"phone":{"type":["string","null"]},"email":{"type":["string","null"]},"notes":{"type":["string","null"]},"bank_accounts":{"type":"array","items":{"type":"object","properties":{"bank_code":{"type":"string"},"account_number":{"type":"string"},"account_holder":{"type":"string"}},"required":["bank_code","account_number"]},"default":[]},"total_90d":{"$ref":"#/components/schemas/Vnd"},"tx_count_90d":{"type":"integer","default":0},"last_tx_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]}},"required":["id","org_id","name","name_norm","kind"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/DongTienVersion"}]}},"/v1/expected-payments":{"get":{"operationId":"listExpectedPayments","summary":"Danh sách khoản dự thu/chi","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"type":"string","enum":["open","partial","paid","cancelled","expired"]},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","enum":["order","cod","pr","obligation","other"]},"required":false,"name":"kind","in":"query"}],"responses":{"200":{"description":"Danh sách dự thu/chi","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpectedPaymentList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createExpectedPayment","summary":"Tạo khoản dự thu/chi","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"}],"requestBody":{"content":{"application/json":{"example":{"kind":"order","ref":"DH-2026-001234","counterparty_name":"Công ty TNHH Thương mại Sao Việt","counterparty_tax_code":"0312345678","amount":12500000,"due_date":"2026-11-05T00:00:00Z","description":"Thanh toán đơn hàng DH-2026-001234"},"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["order","cod","pr","obligation","other"],"default":"order"},"ref":{"type":"string","minLength":1,"maxLength":128},"counterparty_id":{"$ref":"#/components/schemas/CounterpartyId"},"counterparty_name":{"type":"string","maxLength":255},"counterparty_tax_code":{"type":"string","maxLength":32},"amount":{"$ref":"#/components/schemas/PositiveVnd"},"due_date":{"$ref":"#/components/schemas/Timestamp"},"expires_at":{"$ref":"#/components/schemas/Timestamp"},"description":{"type":"string","maxLength":500},"memo_code":{"type":"string","maxLength":32}},"required":["ref","amount"]}}}},"responses":{"201":{"description":"Khoản dự thu/chi đã tạo","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ExpectedPaymentId"},"org_id":{"$ref":"#/components/schemas/OrgId"},"kind":{"type":"string","enum":["order","cod","pr","obligation","other"]},"ref":{"type":"string"},"counterparty_id":{"anyOf":[{"$ref":"#/components/schemas/CounterpartyId"},{"type":"null"}]},"counterparty_name":{"type":["string","null"]},"counterparty_tax_code":{"type":["string","null"]},"amount":{"$ref":"#/components/schemas/PositiveVnd"},"paid_amount":{"$ref":"#/components/schemas/Vnd"},"state":{"type":"string","enum":["open","partial","paid","cancelled","expired"]},"due_date":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"expires_at":{"anyOf":[{"$ref":"#/components/schemas/Timestamp"},{"type":"null"}]},"description":{"type":["string","null"]},"memo_code":{"type":["string","null"]}},"required":["id","org_id","kind","ref","amount","state"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/expected-payments:import":{"post":{"operationId":"importExpectedPayments","summary":"Nhập hàng loạt dự thu/chi (tối đa 500 dòng)","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-rate-class":"write","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["order","cod","pr","obligation","other"],"default":"order"},"ref":{"type":"string","minLength":1,"maxLength":128},"counterparty_id":{"$ref":"#/components/schemas/CounterpartyId"},"counterparty_name":{"type":"string","maxLength":255},"counterparty_tax_code":{"type":"string","maxLength":32},"amount":{"$ref":"#/components/schemas/PositiveVnd"},"due_date":{"$ref":"#/components/schemas/Timestamp"},"expires_at":{"$ref":"#/components/schemas/Timestamp"},"description":{"type":"string","maxLength":500},"memo_code":{"type":"string","maxLength":32}},"required":["ref","amount"]},"minItems":1,"maxItems":500}},"required":["items"]}}}},"responses":{"200":{"description":"Kết quả nhập hàng loạt","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"imported_count":{"type":"integer"}},"required":["imported_count"]}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Mã `code` có thể gặp: `conflict` — Xung đột trạng thái.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/recon-followups":{"get":{"operationId":"listReconFollowups","summary":"Danh sách việc cần xử lý đối soát","description":"Nhắc thu phần còn lại, nhắc hoàn tiền trả thừa, hoá đơn quá hạn.","tags":["Đối soát"],"security":[{"bearerAuth":[]}],"x-dt-permission":"allocation.create","x-dt-rate-class":"read","x-dt-visibility":"public","x-dt-service":"api","parameters":[{"$ref":"#/components/parameters/DongTienVersion"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Số phần tử mỗi trang (1–100, mặc định 20)."},"required":false,"description":"Số phần tử mỗi trang (1–100, mặc định 20).","name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/Cursor"},"required":false,"description":"Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.","name":"cursor","in":"query"},{"schema":{"$ref":"#/components/schemas/OrgId"},"required":false,"description":"Mã công ty / tổ chức (`org_…`).","name":"company_id","in":"query"},{"schema":{"type":"string","enum":["open","resolved","dismissed"],"default":"open"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Danh sách followups","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"DongTien-Version":{"$ref":"#/components/headers/DongTienVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconFollowupList"}}}},"400":{"description":"Mã `code` có thể gặp: `bad_request` — Yêu cầu không hợp lệ; `invalid_json` — Nội dung JSON sai cú pháp; `unsupported_version` — Phiên bản API không được hỗ trợ; `invalid_cursor` — Con trỏ phân trang không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Mã `code` có thể gặp: `unauthenticated` — Cần đăng nhập; `invalid_api_key` — Khoá API không hợp lệ; `api_key_expired` — Khoá API đã hết hạn; `api_key_revoked` — Khoá API đã bị thu hồi.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Mã `code` có thể gặp: `permission_denied` — Không đủ quyền; `scope_not_allowed` — Phạm vi khoá không cho phép route này; `account_scope_denied` — Tài khoản ngân hàng nằm ngoài phạm vi khoá; `ip_not_allowed` — Địa chỉ IP không được phép với khoá này.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Mã `code` có thể gặp: `validation_failed` — Dữ liệu không hợp lệ.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Mã `code` có thể gặp: `rate_limited` — Gọi quá nhanh.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Mã `code` có thể gặp: `internal_error` — Lỗi hệ thống.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Mã `code` có thể gặp: `service_unavailable` — Dịch vụ tạm thời không khả dụng.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"schema":{"type":"string"},"required":true}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"tags":[{"name":"Tài khoản ngân hàng","description":"Tài khoản ngân hàng của công ty: danh sách, tạo, cập nhật, lưu trữ, xem số tài khoản (có xác thực lại)."},{"name":"Số dư","description":"Số dư báo cáo (từ ngân hàng/sao kê) tách khỏi số dư tính toán (từ giao dịch)."},{"name":"Giao dịch","description":"Giao dịch ngân hàng: danh sách, chi tiết, nguồn gốc, nhật ký, đồng bộ theo con trỏ và tổng hợp."},{"name":"Tác vụ","description":"Tác vụ bất đồng bộ (nhập, xuất, đồng bộ): theo dõi tiến độ và kết quả."},{"name":"Chế độ xem","description":"Bộ lọc giao dịch đã lưu (riêng tôi, cả công ty, cả firm) và ghim lên bảng điều khiển."},{"name":"Bảng điều khiển","description":"Số liệu tổng quan từ sổ giao dịch: số dư, vào/ra hôm nay, việc cần xử lý."},{"name":"Thời gian thực","description":"Vé một lần và luồng sự kiện (WebSocket/SSE) cho giao diện: giao dịch mới, nâng cấp, gộp, cách ly."},{"name":"Hệ thống","description":"Thông tin phiên bản và tài liệu API."},{"name":"Danh tính","description":"Người gọi là ai, đang làm việc ở tổ chức nào, tra cứu MST, tiến độ làm quen và phiên đăng nhập."},{"name":"Tổ chức","description":"Gốc tổ chức và công ty (MST), mẫu công ty mới, bàn giao, xoá công ty có hai người duyệt, đồng bộ hồ sơ từ nguồn MST."},{"name":"Thành viên","description":"Thành viên, vai trò, lời mời và quyền truy cập chéo giữa hãng kế toán và khách hàng (access grants)."},{"name":"Bảo mật","description":"Chính sách bảo mật của tổ chức: 2FA, dải IP quản trị, thời lượng phiên, tự duyệt."},{"name":"Khoá API","description":"Khoá API: tạo, xoay, thu hồi, gia hạn và xem các lần gọi gần đây (không bao giờ hiện lại khoá)."},{"name":"Nhật ký kiểm toán","description":"Chuỗi nhật ký kiểm toán chỉ-thêm, tra cứu và xuất CSV."},{"name":"Phê duyệt","description":"Hàng chờ duyệt hai người (maker–checker) và độ sẵn sàng người duyệt của công ty."},{"name":"Thiết bị","description":"Thiết bị chuyển tiếp tin (Android, iOS Shortcuts): mã ghép, trạng thái, lệnh kiểm tra, nhật ký, quy tắc cảnh báo và bản phát hành ứng dụng."},{"name":"Thu tiền","description":"Yêu cầu thanh toán VietQR, bill POS, việc cần xử lý của thu tiền và mẫu mã đơn riêng của công ty. Không giữ tiền: `paid` chỉ khi giao dịch đã xác thực."},{"name":"Nhập sao kê","description":"Tải sao kê ngân hàng (Excel, CSV, MT940, CAMT.053): xem trước, kiểm tra số dư đầu/cuối, ánh xạ cột, lịch nhận sao kê. Không có nhập ép: số dư lệch thì dừng."},{"name":"Dòng tiền","description":"Dòng tiền hợp nhất, dự báo 13 tuần, danh mục thu chi, quy tắc phân loại và cảnh báo."},{"name":"Trí tuệ nhân tạo","description":"Cài đặt AI tự chủ theo tổ chức, kết nối BYOK, mô hình, ngân sách và phân loại giao dịch."},{"name":"Tích hợp","description":"Tích hợp kênh ngoài (Lark, Telegram, Slack, Discord, Google Sheets, Lark Base, WooCommerce, Haravan, Shopify) và quy tắc định tuyến sự kiện."},{"name":"Gói & sử dụng","description":"Gói dịch vụ, đo lường giao dịch, thanh quota, trần chi tiêu, hoá đơn và nạp credit dịch vụ."},{"name":"Đối soát","description":"Đề nghị phân bổ giao dịch vào công nợ, gợi ý khớp và quy tắc đối soát; duyệt theo chính sách người lập và người duyệt."},{"name":"Hoá đơn","description":"Kết nối hoá đơn, đồng bộ công nợ và theo dõi ghi ngược các phân bổ đã duyệt."},{"name":"Đối tác","description":"Đối tác thanh toán, khoản thu dự kiến và công việc theo dõi công nợ."},{"name":"Thông báo","description":"Cài đặt thông báo cá nhân và quy tắc định tuyến của tổ chức, push token, Web Push, liên kết Zalo, hộp thư trong app và widget."},{"name":"Bảo mật sinh trắc","description":"Khoá sinh trắc trên thiết bị (Secure Enclave, Android Keystore) và challenge ký để duyệt lệnh trên ứng dụng di động."}],"externalDocs":{"description":"Hướng dẫn và mã lỗi","url":"https://docs.dongtien.pro"}}