{ "openapi": "3.1.0", "info": { "title": "RSS source-derived integration subset", "version": "1.11.260911-documentary", "description": "RSS 1.11.260911 documentary subset: 7 REST operations with selected fields. All 18 source REST functions remain catalogued separately; callback and Kafka are distinct scopes. Source inconsistencies and deployment configuration remain unresolved." }, "servers": [], "paths": { "/v1/create/credential": { "post": { "operationId": "rssCreateCredential", "tags": [ "RSS" ], "summary": "Register a credential", "x-summary-vi": "Đăng ký credential", "description": "Register a credential. Documentary extraction; not a validated production contract.", "x-source": { "document": "RSS 1.11.260911", "physicalPages": [ 15, 16, 17, 18, 19 ] }, "x-status": "source-derived-deployment-unconfirmed", "x-issues": [ "RSS-01", "RSS-03" ], "x-next-vi": "Lưu x-billcode-id, chờ người dùng và tra cứu trạng thái; không tạo lại khi kết quả chưa rõ.", "x-next-en": "Persist x-billcode-id, await user action and reconcile status before creating another request.", "responses": { "200": { "description": "Response described by the source; inspect business outcome separately.", "content": { "application/json": { "schema": { "type": "object", "description": "", "x-description-vi": "", "properties": { "status": { "type": "string", "description": "Credential registration processing status.", "x-description-vi": "Trạng thái xử lý đăng ký." } }, "required": [] }, "example": { "status": "PROCESSING" } } }, "headers": { "x-billcode-id": { "description": "Service-generated tracking reference; persist with the local request.", "schema": { "type": "string" } } } }, "default": { "description": "Service error fields. Exact status/code mapping requires the operation-specific deployment contract.", "content": { "application/json": { "schema": { "type": "object", "description": "Error fields are conditional on the operation.", "x-description-vi": "Đối tượng lỗi; trường xuất hiện theo operation.", "properties": { "code": { "type": "string", "description": "Service error code, distinct from HTTP status.", "x-description-vi": "Mã lỗi theo dịch vụ; không phải HTTP status." }, "message": { "type": "string", "description": "Short error message.", "x-description-vi": "Thông báo lỗi ngắn." }, "description": { "type": "string", "description": "Detailed explanation when present.", "x-description-vi": "Mô tả chi tiết nếu có." } }, "required": [] } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request fields transcribed from source tables.", "x-description-vi": "Cấu trúc request được biên tập từ bảng nguồn.", "properties": { "provider": { "type": "string", "description": "RSS provider identifier; confirm deployment configuration.", "x-description-vi": "Identifier nhà cung cấp trong RSS; xác nhận cấu hình triển khai." }, "service_package_code": { "type": "string", "description": "Provider service package code.", "x-description-vi": "Mã gói của nhà cung cấp." }, "partner_code": { "type": "string", "description": "Code of the partner submitting the request.", "x-description-vi": "Mã đối tác gửi yêu cầu." }, "originator_id": { "type": "string", "description": "Identifier of the originating application.", "x-description-vi": "Identifier ứng dụng gửi yêu cầu." }, "platform": { "type": "string", "description": "Originating channel: WEB or APP.", "x-description-vi": "Kênh khởi tạo; WEB hoặc APP.", "enum": [ "WEB", "APP" ], "default": "WEB" }, "operation_mode": { "type": "string", "description": "S: synchronous; A: asynchronous, default A in the RSS table.", "x-description-vi": "S: đồng bộ; A: bất đồng bộ, mặc định A theo bảng RSS.", "enum": [ "S", "A" ], "default": "A" }, "postback_url": { "type": "string", "description": "RP result receiver; confirm registration and sender verification.", "x-description-vi": "Địa chỉ nhận kết quả phía RP; xác nhận đăng ký và kiểm tra nguồn gửi.", "format": "uri" }, "user_info": { "type": "object", "description": "", "x-description-vi": "", "properties": { "citizen_pid": { "type": "string", "description": "Citizen personal identifier; never enter real data in the demo.", "x-description-vi": "Số định danh cá nhân; không nhập dữ liệu thật vào demo." }, "full_name": { "type": "string", "description": "Full name when supplied.", "x-description-vi": "Họ tên nếu gửi." }, "birth_date": { "type": "string", "description": "Birth date in the deployment format.", "x-description-vi": "Ngày sinh theo contract triển khai." }, "phone": { "type": "string", "description": "Phone number when needed.", "x-description-vi": "Số điện thoại nếu cần." }, "email": { "type": "string", "description": "Email when needed.", "x-description-vi": "Email nếu cần." }, "issuing_authority": { "type": "string", "description": "Citizen-ID issuing authority; optional. Format follows the deployment contract.", "x-description-vi": "Cơ quan cấp căn cước; tùy chọn. Định dạng theo contract triển khai." }, "date_of_issue": { "type": "string", "description": "Citizen-ID issue date; optional. Format follows the deployment contract.", "x-description-vi": "Ngày cấp căn cước; tùy chọn. Định dạng theo contract triển khai." }, "gender": { "type": "string", "description": "Gender; optional. Format follows the deployment contract.", "x-description-vi": "Giới tính; tùy chọn. Định dạng theo contract triển khai." }, "nationality_code": { "type": "string", "description": "Nationality code; optional. Format follows the deployment contract.", "x-description-vi": "Mã quốc tịch; tùy chọn. Định dạng theo contract triển khai." }, "permanent_address": { "type": "string", "description": "Permanent address; optional. Format follows the deployment contract.", "x-description-vi": "Địa chỉ thường trú; tùy chọn. Định dạng theo contract triển khai." }, "permanent_village_text": { "type": "string", "description": "Permanent locality name; optional. Format follows the deployment contract.", "x-description-vi": "Tên đơn vị địa phương thường trú; tùy chọn. Định dạng theo contract triển khai." }, "permanent_city_text": { "type": "string", "description": "Permanent city/province name; optional. Format follows the deployment contract.", "x-description-vi": "Tên tỉnh/thành thường trú; tùy chọn. Định dạng theo contract triển khai." }, "living_place_address": { "type": "string", "description": "Current address; optional. Format follows the deployment contract.", "x-description-vi": "Địa chỉ nơi ở; tùy chọn. Định dạng theo contract triển khai." }, "living_place_village_text": { "type": "string", "description": "Current locality name; optional. Format follows the deployment contract.", "x-description-vi": "Tên đơn vị địa phương nơi ở; tùy chọn. Định dạng theo contract triển khai." }, "living_place_city_code": { "type": "string", "description": "Current city/province code; optional. Format follows the deployment contract.", "x-description-vi": "Mã tỉnh/thành nơi ở; tùy chọn. Định dạng theo contract triển khai." }, "living_place_city_text": { "type": "string", "description": "Current city/province name; optional. Format follows the deployment contract.", "x-description-vi": "Tên tỉnh/thành nơi ở; tùy chọn. Định dạng theo contract triển khai." }, "id_card_expire_date": { "type": "string", "description": "Citizen-ID expiry date; optional. Format follows the deployment contract.", "x-description-vi": "Ngày hết hạn căn cước; tùy chọn. Định dạng theo contract triển khai." } }, "required": [ "citizen_pid" ] } }, "required": [ "provider", "service_package_code", "partner_code", "originator_id", "user_info" ] }, "example": { "provider": "HUD-FPT-CA", "service_package_code": "DEMO_PACKAGE", "partner_code": "DEMO_PARTNER", "originator_id": "DEMO_APP", "user_info": { "citizen_pid": "DEMO_CITIZEN_ONLY" }, "operation_mode": "A" } } } }, "parameters": [ { "name": "x-language", "in": "header", "required": false, "description": "Response language.", "schema": { "type": "string", "enum": [ "vi", "en" ], "default": "en" } }, { "name": "x-rp-id", "in": "header", "required": false, "description": "RP-generated reference, distinct from service-generated x-billcode-id.", "schema": { "type": "string" } } ], "x-readiness": { "documented": true, "contract_confirmed": false, "sandbox_tested": false, "production_accepted": false, "request_model": "wire-schema-selected-fields", "source": { "document": "RSS 1.11.260911", "physicalPages": [ 15, 16, 17, 18, 19 ] }, "blocking_issues": [ "RSS-01", "RSS-03" ], "response_model": "selected-fields" }, "x-coverage": "selected-fields" } }, "/v1/get/credential/status": { "get": { "operationId": "rssGetCredentialStatus", "tags": [ "RSS" ], "summary": "Read credential registration status", "x-summary-vi": "Tra cứu đăng ký credential", "description": "Read credential registration status. Documentary extraction; not a validated production contract.", "x-source": { "document": "RSS 1.11.260911", "physicalPages": [ 20, 21 ] }, "x-status": "source-derived-deployment-unconfirmed", "x-issues": [ "RSS-01", "RSS-05" ], "x-next-vi": "Đối chiếu kết quả đăng ký trước khi lấy chứng thư.", "x-next-en": "Reconcile registration outcome before retrieving certificates.", "responses": { "200": { "description": "Response described by the source; inspect business outcome separately.", "content": { "application/json": { "schema": { "type": "object", "description": "", "x-description-vi": "", "properties": { "status": { "type": "string", "description": "Business status described by the source.", "x-description-vi": "Trạng thái nghiệp vụ trong nguồn." }, "data": { "type": "object", "description": "Object from source tables.", "x-description-vi": "Đối tượng theo bảng nguồn.", "properties": { "citizen_pid": { "type": "string", "description": "Citizen ID; read presence conditions alongside the status.", "x-description-vi": "Số định danh; điều kiện xuất hiện cần đọc cùng trạng thái." }, "description": { "type": "string", "description": "Status-dependent outcome explanation.", "x-description-vi": "Mô tả kết quả theo trạng thái." }, "credential_id": { "type": "string", "description": "Credential identifier when returned.", "x-description-vi": "Mã credential khi được trả về." }, "serial_number": { "type": "string", "description": "Certificate serial number.", "x-description-vi": "Số sê-ri chứng thư." }, "certificate_data": { "type": "string", "description": "Base64 certificate data in the source.", "x-description-vi": "Chứng thư Base64 theo nguồn." } }, "required": [] } }, "required": [], "x-presence-note": "Source marks citizen_pid and description mandatory in 2xx table, while PROCESSING examples omit data. Conditional branches require confirmation." } } } }, "default": { "description": "Service error fields. Exact status/code mapping requires the operation-specific deployment contract.", "content": { "application/json": { "schema": { "type": "object", "description": "Error fields are conditional on the operation.", "x-description-vi": "Đối tượng lỗi; trường xuất hiện theo operation.", "properties": { "code": { "type": "string", "description": "Service error code, distinct from HTTP status.", "x-description-vi": "Mã lỗi theo dịch vụ; không phải HTTP status." }, "message": { "type": "string", "description": "Short error message.", "x-description-vi": "Thông báo lỗi ngắn." }, "description": { "type": "string", "description": "Detailed explanation when present.", "x-description-vi": "Mô tả chi tiết nếu có." } }, "required": [] } } } } }, "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "x-billcode-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Reference from credential creation." }, { "name": "x-language", "in": "header", "required": false, "description": "Response language.", "schema": { "type": "string", "enum": [ "vi", "en" ], "default": "en" } }, { "name": "x-rp-id", "in": "header", "required": false, "description": "RP-generated reference, distinct from service-generated x-billcode-id.", "schema": { "type": "string" } } ], "x-readiness": { "documented": true, "contract_confirmed": false, "sandbox_tested": false, "production_accepted": false, "request_model": "parameters-or-catalogue", "source": { "document": "RSS 1.11.260911", "physicalPages": [ 20, 21 ] }, "blocking_issues": [ "RSS-01", "RSS-05" ], "response_model": "selected-fields" }, "x-coverage": "selected-fields" } }, "/v1/sign/hash": { "post": { "operationId": "rssSignHash", "tags": [ "RSS" ], "summary": "Sign document digests", "x-summary-vi": "Ký digest tài liệu", "description": "Sign document digests. Documentary extraction; not a validated production contract.", "x-source": { "document": "RSS 1.11.260911", "physicalPages": [ 27, 28, 29, 30 ] }, "x-status": "source-derived-deployment-unconfirmed", "x-issues": [ "RSS-01", "RSS-02", "RSS-04" ], "x-next-vi": "Lưu mã tham chiếu; đối soát qua callback hoặc tra cứu. Chưa coi PROCESSING là ký hoàn tất.", "x-next-en": "Persist the reference and reconcile via callback or status lookup; PROCESSING is not completion.", "responses": { "200": { "description": "Response described by the source; inspect business outcome separately.", "content": { "application/json": { "schema": { "type": "object", "description": "", "x-description-vi": "", "properties": { "data": { "type": "object", "description": "", "x-description-vi": "", "properties": { "status": { "type": "string", "description": "Status in the response table.", "x-description-vi": "Trạng thái theo bảng." }, "signatures": { "type": "array", "description": "Base64 signatures according to the table; confirm envelope.", "x-description-vi": "Chữ ký Base64 theo bảng; envelope cần xác nhận.", "items": { "type": "string", "description": "Value returned by the service.", "x-description-vi": "Giá trị trong kết quả." } } }, "required": [] }, "status": { "type": "string", "description": "Top-level status in the source example; relationship with data.status unconfirmed.", "x-description-vi": "Trường top-level trong ví dụ nguồn; chưa xác nhận quan hệ với data.status." } }, "required": [] } } }, "headers": { "x-billcode-id": { "description": "Service-generated tracking reference; persist with the local request.", "schema": { "type": "string" } } } }, "default": { "description": "Service error fields. Exact status/code mapping requires the operation-specific deployment contract.", "content": { "application/json": { "schema": { "type": "object", "description": "Error fields are conditional on the operation.", "x-description-vi": "Đối tượng lỗi; trường xuất hiện theo operation.", "properties": { "code": { "type": "string", "description": "Service error code, distinct from HTTP status.", "x-description-vi": "Mã lỗi theo dịch vụ; không phải HTTP status." }, "message": { "type": "string", "description": "Short error message.", "x-description-vi": "Thông báo lỗi ngắn." }, "description": { "type": "string", "description": "Detailed explanation when present.", "x-description-vi": "Mô tả chi tiết nếu có." } }, "required": [] } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request fields transcribed from source tables.", "x-description-vi": "Cấu trúc request được biên tập từ bảng nguồn.", "properties": { "credential_id": { "type": "string", "description": "Identifier associated with the selected key and certificate.", "x-description-vi": "Identifier khóa/chứng thư được lựa chọn." }, "citizen_pid": { "type": "string", "description": "Citizen personal identifier; never enter real data in the demo.", "x-description-vi": "Số định danh cá nhân; không nhập dữ liệu thật vào demo." }, "partner_code": { "type": "string", "description": "Code of the partner submitting the request.", "x-description-vi": "Mã đối tác gửi yêu cầu." }, "originator_id": { "type": "string", "description": "Identifier of the originating application.", "x-description-vi": "Identifier ứng dụng gửi yêu cầu." }, "operation_mode": { "type": "string", "description": "S: synchronous; A: asynchronous, default A in the RSS table.", "x-description-vi": "S: đồng bộ; A: bất đồng bộ, mặc định A theo bảng RSS.", "enum": [ "S", "A" ], "default": "A" }, "platform": { "type": "string", "description": "Originating channel: WEB or APP.", "x-description-vi": "Kênh khởi tạo; WEB hoặc APP.", "enum": [ "WEB", "APP" ], "default": "WEB" }, "postback_url": { "type": "string", "description": "RP result receiver; confirm registration and sender verification.", "x-description-vi": "Địa chỉ nhận kết quả phía RP; xác nhận đăng ký và kiểm tra nguồn gửi.", "format": "uri" }, "documents": { "type": "array", "description": "Document names and digests; confirm the digest encoding.", "x-description-vi": "Danh sách tài liệu và digest; định dạng digest cần xác nhận.", "items": { "type": "object", "description": "", "x-description-vi": "", "properties": { "document_name": { "type": "string", "description": "Document name.", "x-description-vi": "Tên tài liệu." }, "digest_value": { "type": "string", "description": "Document digest; no real document in the demo.", "x-description-vi": "Digest tài liệu; không dùng tài liệu thật trong demo." } }, "required": [ "document_name", "digest_value" ] } } }, "required": [ "credential_id", "citizen_pid", "partner_code", "originator_id", "documents" ] }, "example": { "credential_id": "DEMO_RSS_CREDENTIAL", "citizen_pid": "DEMO_CITIZEN_ONLY", "partner_code": "DEMO_PARTNER", "originator_id": "DEMO_APP", "documents": [ { "document_name": "DEMO_DOCUMENT", "digest_value": "ypeBEsobvcr6wjGzmiPcTaeG7/gUfE5yuYB3ha/uSLs=" } ], "operation_mode": "A" } } } }, "parameters": [ { "name": "x-language", "in": "header", "required": false, "description": "Response language.", "schema": { "type": "string", "enum": [ "vi", "en" ], "default": "en" } }, { "name": "x-rp-id", "in": "header", "required": false, "description": "RP-generated reference, distinct from service-generated x-billcode-id.", "schema": { "type": "string" } } ], "x-readiness": { "documented": true, "contract_confirmed": false, "sandbox_tested": false, "production_accepted": false, "request_model": "wire-schema-selected-fields", "source": { "document": "RSS 1.11.260911", "physicalPages": [ 27, 28, 29, 30 ] }, "blocking_issues": [ "RSS-01", "RSS-02", "RSS-04" ], "response_model": "selected-fields" }, "x-coverage": "selected-fields" } }, "/v1/get/signing/status": { "get": { "operationId": "rssGetSigningStatus", "tags": [ "RSS" ], "summary": "Read signing outcome", "x-summary-vi": "Tra cứu kết quả ký", "description": "Read signing outcome. Documentary extraction; not a validated production contract.", "x-source": { "document": "RSS 1.11.260911", "physicalPages": [ 31, 32 ] }, "x-status": "source-derived-deployment-unconfirmed", "x-issues": [ "RSS-01", "RSS-02" ], "x-next-vi": "Liên kết kết quả với phiên bản tài liệu; hoàn thiện và kiểm chứng theo contract.", "x-next-en": "Bind the outcome to the document version; assemble and validate under the contract.", "responses": { "200": { "description": "Response described by the source; inspect business outcome separately.", "content": { "application/json": { "schema": { "type": "object", "description": "", "x-description-vi": "", "properties": { "status": { "type": "string", "description": "Signing request state.", "x-description-vi": "Trạng thái yêu cầu ký." }, "data": { "type": "object", "description": "", "x-description-vi": "", "properties": { "signatures": { "type": "array", "description": "Inconsistent source description; not sufficient to interpret cryptographic output.", "x-description-vi": "Nguồn mô tả chưa nhất quán; chưa dùng để diễn giải kết quả mật mã.", "items": { "type": "string", "description": "Value returned by the service.", "x-description-vi": "Giá trị trong kết quả." } }, "description": { "type": "string", "description": "Outcome explanation.", "x-description-vi": "Thông tin giải thích trong kết quả." } }, "required": [] } }, "required": [] }, "example": { "status": "PROCESSING" } } } }, "default": { "description": "Service error fields. Exact status/code mapping requires the operation-specific deployment contract.", "content": { "application/json": { "schema": { "type": "object", "description": "Error fields are conditional on the operation.", "x-description-vi": "Đối tượng lỗi; trường xuất hiện theo operation.", "properties": { "code": { "type": "string", "description": "Service error code, distinct from HTTP status.", "x-description-vi": "Mã lỗi theo dịch vụ; không phải HTTP status." }, "message": { "type": "string", "description": "Short error message.", "x-description-vi": "Thông báo lỗi ngắn." }, "description": { "type": "string", "description": "Detailed explanation when present.", "x-description-vi": "Mô tả chi tiết nếu có." } }, "required": [] } } } } }, "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "x-billcode-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Reference returned by sign/hash." }, { "name": "x-language", "in": "header", "required": false, "description": "Response language.", "schema": { "type": "string", "enum": [ "vi", "en" ], "default": "en" } }, { "name": "x-rp-id", "in": "header", "required": false, "description": "RP-generated reference, distinct from service-generated x-billcode-id.", "schema": { "type": "string" } } ], "x-readiness": { "documented": true, "contract_confirmed": false, "sandbox_tested": false, "production_accepted": false, "request_model": "parameters-or-catalogue", "source": { "document": "RSS 1.11.260911", "physicalPages": [ 31, 32 ] }, "blocking_issues": [ "RSS-01", "RSS-02" ], "response_model": "selected-fields" }, "x-coverage": "selected-fields" } }, "/v1/get/certificates": { "get": { "operationId": "rssCertificates", "tags": [ "RSS" ], "summary": "Read certificates for the citizen", "x-summary-vi": "Tra cứu chứng thư theo chủ thể", "description": "Read certificates for the citizen. Selected field schema; not a production contract.", "x-source": { "document": "RSS 1.11.260911", "physicalPages": [ 23, 24, 25, 26 ] }, "x-status": "source-derived-deployment-unconfirmed", "x-coverage": "selected-fields", "x-issues": [ "RSS13-CERT-HEADER" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "x-language", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "en", "vi" ] }, "description": "Response language.", "x-description-vi": "Ngôn ngữ kết quả." }, { "name": "x-rp-id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation identifier.", "x-description-vi": "Mã tham chiếu phía gọi." }, { "name": "x-citizen-pid", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Citizen identifier; never put real identity data in the demo.", "x-description-vi": "Mã định danh; không dùng người thật trong demo." }, { "name": "x-certificate-info-enabled", "in": "header", "required": false, "schema": { "type": "boolean" }, "description": "Include certificate details.", "x-description-vi": "Kèm thông tin chứng thư." }, { "name": "x-certificates", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "none", "single", "chain" ] }, "description": "Certificate selection.", "x-description-vi": "Lựa chọn chứng thư." } ], "responses": { "200": { "description": "Certificate and key metadata from source PDF pages 24–26; not document signature validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "certificates": { "type": "array", "x-description-vi": "Danh sách chứng thư từ dịch vụ.", "description": "Service certificate list.", "x-presence": "O", "items": { "type": "object", "properties": { "status": { "type": "string", "x-description-vi": "Trạng thái chứng thư trong RSS: 0 khóa, 1 hoạt động, 2 hết hạn; không phải kết quả kiểm chứng tài liệu.", "description": "RSS certificate status: 0 locked, 1 active, 2 expired; not a document validation result.", "x-presence": "O", "enum": [ "0", "1", "2" ] }, "cert_chains": { "type": "array", "x-description-vi": "Chuỗi chứng thư X.509 Base64; chứng thư người ký đứng đầu theo nguồn.", "description": "Base64 X.509 chain; signer certificate first in the source.", "x-presence": "M", "items": { "type": "string" } }, "credential_id": { "type": "string", "x-description-vi": "Mã credential gắn khóa và chứng thư.", "description": "Credential identifier associated with key and certificate.", "x-presence": "M" }, "serial_number": { "type": "string", "x-description-vi": "Số sê-ri; trả khi bật thông tin chứng thư.", "description": "Serial number, returned when certificate information is enabled.", "x-presence": "RC" }, "issuer_dn": { "type": "string", "x-description-vi": "Tên phân biệt của bên phát hành; có điều kiện.", "description": "Issuer distinguished name; conditional.", "x-presence": "RC" }, "subject_dn": { "type": "string", "x-description-vi": "Tên phân biệt chủ thể; không dùng dữ liệu thật trong ví dụ.", "description": "Subject distinguished name; no real data in fixtures.", "x-presence": "RC" }, "valid_from": { "type": "string", "x-description-vi": "Bắt đầu hiệu lực ISO 8601 UTC khi bật thông tin chứng thư.", "description": "Validity start in ISO 8601 UTC when certificate information is enabled.", "x-presence": "RC" }, "valid_to": { "type": "string", "x-description-vi": "Kết thúc hiệu lực ISO 8601 UTC; không thay kiểm tra thu hồi.", "description": "Validity end in ISO 8601 UTC; not a revocation check.", "x-presence": "RC" } }, "required": [ "cert_chains", "credential_id" ], "description": "Source certificate entry; metadata fields are conditional, not universally required.", "x-description-vi": "Mục chứng thư từ nguồn; metadata có điều kiện, không bắt buộc cho mọi phản hồi." } }, "key": { "type": "object", "properties": { "status": { "type": "string", "x-description-vi": "Trạng thái khóa theo nguồn; không tự tạo enum.", "description": "Source key status; no invented enum.", "x-presence": "O" }, "algos": { "type": "array", "x-description-vi": "OID thuật toán khóa được trả về.", "description": "Returned key algorithm OIDs.", "x-presence": "O", "items": { "type": "string" } }, "len": { "type": "integer", "x-description-vi": "Độ dài khóa theo bit.", "description": "Key length in bits.", "x-presence": "O" }, "curve": { "type": "string", "x-description-vi": "Đường cong khi áp dụng.", "description": "Curve when applicable.", "x-presence": "O" } } } }, "description": "Certificate response fields from source pages 24–26.", "x-description-vi": "Trường phản hồi chứng thư từ trang PDF 24–26." } } } }, "400": { "description": "Source parameter error; reconcile table and examples." }, "401": { "description": "Authentication failure." } }, "x-next-vi": "Lưu mã theo dõi và đối chiếu kết quả đúng hành trình; không suy thành ký hoàn tất.", "x-next-en": "Keep tracking identifiers and reconcile the correct journey; do not infer completed signing.", "x-readiness": { "documented": true, "contract_confirmed": false, "sandbox_tested": false, "production_accepted": false, "request_model": "parameters-or-catalogue", "source": { "document": "RSS 1.11.260911", "physicalPages": [ 23, 24, 25, 26 ] }, "blocking_issues": [ "RSS13-CERT-HEADER" ], "response_model": "selected-fields" } } }, "/v1/request/citizen/identity-sharing": { "post": { "operationId": "rssIdentitySharingRequest", "tags": [ "RSS" ], "summary": "Request VNeID data-sharing consent", "x-summary-vi": "Yêu cầu đồng ý chia sẻ dữ liệu VNeID", "description": "Request VNeID data-sharing consent. Selected field schema; not a production contract.", "x-source": { "document": "RSS 1.11.260911", "physicalPages": [ 33, 34, 35 ] }, "x-status": "source-derived-deployment-unconfirmed", "x-coverage": "selected-fields", "x-issues": [ "RSS12-SHARE-TYPE" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "x-language", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "en", "vi" ] }, "description": "Response language.", "x-description-vi": "Ngôn ngữ kết quả." }, { "name": "x-rp-id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation identifier.", "x-description-vi": "Mã tham chiếu phía gọi." } ], "responses": { "200": { "description": "Read status and conditionally returned fields; success at data sharing is not a signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Business outcome; not an HTTP status or signature validation result.", "x-description-vi": "Kết quả nghiệp vụ; không phải HTTP status hoặc kết quả kiểm chứng chữ ký.", "x-presence": "M" }, "code": { "type": "string", "description": "Source error identifier; do not translate.", "x-description-vi": "Mã lỗi nguồn; không dịch.", "x-presence": "O" }, "message": { "type": "string", "description": "Error summary.", "x-description-vi": "Tóm tắt lỗi.", "x-presence": "O" }, "description": { "type": "string", "description": "Error explanation.", "x-description-vi": "Giải thích lỗi.", "x-presence": "O" }, "data": { "type": "object", "properties": { "transaction_code": { "type": "string", "description": "VNeID transaction code returned after initialization.", "x-description-vi": "Mã giao dịch VNeID trả về sau khởi tạo.", "x-presence": "M" }, "response_time": { "type": "string", "description": "Source table says String[] while its example is String; unresolved.", "x-description-vi": "Bảng ghi String[] nhưng ví dụ là String; chưa xác nhận.", "x-presence": "O" } }, "required": [ "transaction_code" ], "x-presence": "RC", "description": "Initialization result, not shared data or a signature.", "x-description-vi": "Kết quả khởi tạo, chưa phải dữ liệu chia sẻ hoặc chữ ký." } }, "required": [ "status" ] } } }, "headers": { "x-billcode-id": { "schema": { "type": "string" }, "description": "RSS-generated tracking identifier; retain with the caller correlation." } } }, "400": { "description": "Source parameter error; reconcile table and examples." }, "401": { "description": "Authentication failure." } }, "x-next-vi": "Lưu mã theo dõi và đối chiếu kết quả đúng hành trình; không suy thành ký hoàn tất.", "x-next-en": "Keep tracking identifiers and reconcile the correct journey; do not infer completed signing.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "citizen_pid": { "type": "string", "description": "Citizen identifier.", "x-description-vi": "Mã định danh công dân.", "x-presence": "M" }, "request_time": { "type": "string", "description": "Source format ddMMyyyyHHmmss.", "x-description-vi": "Format nguồn ddMMyyyyHHmmss.", "x-presence": "O" }, "target_code": { "type": "string", "description": "Sharing target.", "x-description-vi": "Mục đích chia sẻ.", "x-presence": "M", "enum": [ "update-info-web", "update-info-app" ] }, "postback_url": { "type": "string", "description": "Backend postback URL.", "x-description-vi": "URL nhận postback phía máy chủ.", "x-presence": "O" } }, "required": [ "citizen_pid", "target_code" ] } } } }, "x-readiness": { "documented": true, "contract_confirmed": false, "sandbox_tested": false, "production_accepted": false, "request_model": "wire-schema-selected-fields", "source": { "document": "RSS 1.11.260911", "physicalPages": [ 33, 34, 35 ] }, "blocking_issues": [ "RSS12-SHARE-TYPE" ], "response_model": "selected-fields" } } }, "/v1/get/citizen/identity-sharing": { "get": { "operationId": "rssIdentitySharingResult", "tags": [ "RSS" ], "summary": "Read the data-sharing result", "x-summary-vi": "Đọc kết quả chia sẻ dữ liệu", "description": "Read the data-sharing result. Selected field schema; not a production contract.", "x-source": { "document": "RSS 1.11.260911", "physicalPages": [ 36, 37, 38 ] }, "x-status": "source-derived-deployment-unconfirmed", "x-coverage": "selected-fields", "x-issues": [ "RSS12-SHARE-HEADER" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "x-language", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "en", "vi" ] }, "description": "Response language.", "x-description-vi": "Ngôn ngữ kết quả." }, { "name": "x-rp-id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation identifier.", "x-description-vi": "Mã tham chiếu phía gọi." }, { "name": "x-transaction-code", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Transaction code from initialization; source example uses another header.", "x-description-vi": "Mã giao dịch khởi tạo; ví dụ nguồn dùng header khác." }, { "name": "x-request-time", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Source format ddMMyyyyHHmmss.", "x-description-vi": "Format nguồn ddMMyyyyHHmmss." }, { "name": "x-target-code", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "update-info-web", "update-info-app" ] }, "description": "Sharing target.", "x-description-vi": "Mục đích chia sẻ." } ], "responses": { "200": { "description": "Read status and conditionally returned fields; success at data sharing is not a signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Business outcome; not an HTTP status or signature validation result.", "x-description-vi": "Kết quả nghiệp vụ; không phải HTTP status hoặc kết quả kiểm chứng chữ ký.", "x-presence": "M" }, "code": { "type": "string", "description": "Source error identifier; do not translate.", "x-description-vi": "Mã lỗi nguồn; không dịch.", "x-presence": "O" }, "message": { "type": "string", "description": "Error summary.", "x-description-vi": "Tóm tắt lỗi.", "x-presence": "O" }, "description": { "type": "string", "description": "Error explanation.", "x-description-vi": "Giải thích lỗi.", "x-presence": "O" }, "data": { "type": "object", "properties": { "user_info_token": { "type": "string", "description": "JWS-formatted sharing token; check under the agreed trust contract.", "x-description-vi": "Token chia sẻ theo JWS; kiểm tra theo contract tin cậy đã thống nhất.", "x-presence": "RC" }, "response_time": { "type": "string", "description": "Response time in source format.", "x-description-vi": "Thời điểm kết quả theo format nguồn.", "x-presence": "O" }, "description": { "type": "string", "description": "Outcome explanation.", "x-description-vi": "Giải thích kết quả.", "x-presence": "O" } }, "required": [], "x-presence": "RC", "description": "Sharing outcome; full citizen fields intentionally not used in demo fixtures.", "x-description-vi": "Kết quả chia sẻ; không dùng các trường công dân đầy đủ trong fixture demo." } }, "required": [ "status" ] } } } }, "400": { "description": "Source parameter error; reconcile table and examples." }, "401": { "description": "Authentication failure." } }, "x-next-vi": "Lưu mã theo dõi và đối chiếu kết quả đúng hành trình; không suy thành ký hoàn tất.", "x-next-en": "Keep tracking identifiers and reconcile the correct journey; do not infer completed signing.", "x-readiness": { "documented": true, "contract_confirmed": false, "sandbox_tested": false, "production_accepted": false, "request_model": "parameters-or-catalogue", "source": { "document": "RSS 1.11.260911", "physicalPages": [ 36, 37, 38 ] }, "blocking_issues": [ "RSS12-SHARE-HEADER" ], "response_model": "selected-fields" } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "RssCertificate": { "type": "object", "properties": { "status": { "type": "string", "x-description-vi": "Trạng thái chứng thư trong RSS: 0 khóa, 1 hoạt động, 2 hết hạn; không phải kết quả kiểm chứng tài liệu.", "description": "RSS certificate status: 0 locked, 1 active, 2 expired; not a document validation result.", "x-presence": "O", "enum": [ "0", "1", "2" ] }, "cert_chains": { "type": "array", "x-description-vi": "Chuỗi chứng thư X.509 Base64; chứng thư người ký đứng đầu theo nguồn.", "description": "Base64 X.509 chain; signer certificate first in the source.", "x-presence": "M", "items": { "type": "string" } }, "credential_id": { "type": "string", "x-description-vi": "Mã credential gắn khóa và chứng thư.", "description": "Credential identifier associated with key and certificate.", "x-presence": "M" }, "serial_number": { "type": "string", "x-description-vi": "Số sê-ri; trả khi bật thông tin chứng thư.", "description": "Serial number, returned when certificate information is enabled.", "x-presence": "RC" }, "issuer_dn": { "type": "string", "x-description-vi": "Tên phân biệt của bên phát hành; có điều kiện.", "description": "Issuer distinguished name; conditional.", "x-presence": "RC" }, "subject_dn": { "type": "string", "x-description-vi": "Tên phân biệt chủ thể; không dùng dữ liệu thật trong ví dụ.", "description": "Subject distinguished name; no real data in fixtures.", "x-presence": "RC" }, "valid_from": { "type": "string", "x-description-vi": "Bắt đầu hiệu lực ISO 8601 UTC khi bật thông tin chứng thư.", "description": "Validity start in ISO 8601 UTC when certificate information is enabled.", "x-presence": "RC" }, "valid_to": { "type": "string", "x-description-vi": "Kết thúc hiệu lực ISO 8601 UTC; không thay kiểm tra thu hồi.", "description": "Validity end in ISO 8601 UTC; not a revocation check.", "x-presence": "RC" } }, "required": [ "cert_chains", "credential_id" ], "description": "Source certificate entry; metadata fields are conditional, not universally required.", "x-description-vi": "Mục chứng thư từ nguồn; metadata có điều kiện, không bắt buộc cho mọi phản hồi." }, "RssCertificatesResult": { "type": "object", "properties": { "certificates": { "type": "array", "x-description-vi": "Danh sách chứng thư từ dịch vụ.", "description": "Service certificate list.", "x-presence": "O", "items": { "type": "object", "properties": { "status": { "type": "string", "x-description-vi": "Trạng thái chứng thư trong RSS: 0 khóa, 1 hoạt động, 2 hết hạn; không phải kết quả kiểm chứng tài liệu.", "description": "RSS certificate status: 0 locked, 1 active, 2 expired; not a document validation result.", "x-presence": "O", "enum": [ "0", "1", "2" ] }, "cert_chains": { "type": "array", "x-description-vi": "Chuỗi chứng thư X.509 Base64; chứng thư người ký đứng đầu theo nguồn.", "description": "Base64 X.509 chain; signer certificate first in the source.", "x-presence": "M", "items": { "type": "string" } }, "credential_id": { "type": "string", "x-description-vi": "Mã credential gắn khóa và chứng thư.", "description": "Credential identifier associated with key and certificate.", "x-presence": "M" }, "serial_number": { "type": "string", "x-description-vi": "Số sê-ri; trả khi bật thông tin chứng thư.", "description": "Serial number, returned when certificate information is enabled.", "x-presence": "RC" }, "issuer_dn": { "type": "string", "x-description-vi": "Tên phân biệt của bên phát hành; có điều kiện.", "description": "Issuer distinguished name; conditional.", "x-presence": "RC" }, "subject_dn": { "type": "string", "x-description-vi": "Tên phân biệt chủ thể; không dùng dữ liệu thật trong ví dụ.", "description": "Subject distinguished name; no real data in fixtures.", "x-presence": "RC" }, "valid_from": { "type": "string", "x-description-vi": "Bắt đầu hiệu lực ISO 8601 UTC khi bật thông tin chứng thư.", "description": "Validity start in ISO 8601 UTC when certificate information is enabled.", "x-presence": "RC" }, "valid_to": { "type": "string", "x-description-vi": "Kết thúc hiệu lực ISO 8601 UTC; không thay kiểm tra thu hồi.", "description": "Validity end in ISO 8601 UTC; not a revocation check.", "x-presence": "RC" } }, "required": [ "cert_chains", "credential_id" ], "description": "Source certificate entry; metadata fields are conditional, not universally required.", "x-description-vi": "Mục chứng thư từ nguồn; metadata có điều kiện, không bắt buộc cho mọi phản hồi." } }, "key": { "type": "object", "properties": { "status": { "type": "string", "x-description-vi": "Trạng thái khóa theo nguồn; không tự tạo enum.", "description": "Source key status; no invented enum.", "x-presence": "O" }, "algos": { "type": "array", "x-description-vi": "OID thuật toán khóa được trả về.", "description": "Returned key algorithm OIDs.", "x-presence": "O", "items": { "type": "string" } }, "len": { "type": "integer", "x-description-vi": "Độ dài khóa theo bit.", "description": "Key length in bits.", "x-presence": "O" }, "curve": { "type": "string", "x-description-vi": "Đường cong khi áp dụng.", "description": "Curve when applicable.", "x-presence": "O" } } } }, "description": "Certificate response fields from source pages 24–26.", "x-description-vi": "Trường phản hồi chứng thư từ trang PDF 24–26." } } }, "x-catalog": [ [ "Authentication", "POST", "{sso-url}/realms/{realm}/protocol/openid-connect/token", 8 ], [ "System info", "GET", "/v1/get/system/info", 9 ], [ "Register partner", "POST", "/v1/register/partner", 12 ], [ "Create credential", "POST", "/v1/create/credential", 15 ], [ "Credential status", "GET", "/v1/get/credential/status", 20 ], [ "Certificates", "GET", "/v1/get/certificates", 23 ], [ "Sign hash", "POST", "/v1/sign/hash", 27 ], [ "Signing status", "GET", "/v1/get/signing/status", 31 ], [ "Identity sharing request", "POST", "/v1/request/citizen/identity-sharing", 33 ], [ "Identity sharing result", "GET", "/v1/get/citizen/identity-sharing", 36 ], [ "Transactions", "GET", "/v1/get/transactions", 39 ], [ "RP universal link", "GET", "/v1/get/rp/universal-link", 42 ], [ "Tax information", "GET", "/v1/get/tax/information", 44 ], [ "Tax information result", "GET", "/v1/get/tax/information/result", 54 ], [ "Application type", "GET", "/v1/get/application/type", 62 ], [ "Partners", "GET", "/v1/get/partners", 65 ], [ "Verify citizen ID", "POST", "/v1/verify/eid", 67 ], [ "Reload system", "POST", "/v1/reload/system", 70 ] ] }