API Shadow Ledger
Bản đồ endpoint lõi; hợp đồng đầy đủ nằm trong OpenAPI của monorepo.
Trong trang này
Quy ước tích hợp
Prefix API là /api/v1. Endpoint riêng yêu cầu phiên xác thực và tổ chức được xác định từ phiên, không lấy orgId do client tự gửi.
Dùng Idempotency-Key cho các thao tác được hỗ trợ. Cùng key với body khác trả IDEMPOTENCY_KEY_REUSE; kết quả được phát lại khi request trùng. Hợp đồng Zod và OpenAPI là nguồn chính thức cho body, response và lỗi.
Endpoint thường dùng
| Method / path sau /api/v1 | Mục đích |
|---|---|
| POST /shadow-ledger/ingest | Multipart: file JSON, plantId, recordType. |
| POST /shadow-ledger/commit-offchain | Xác nhận recordIds, ghi seal và log. |
| GET /shadow-ledger/records/:id/evidence | Tải bằng chứng theo quyền nhà máy. |
| POST /shadow-ledger/records/:id/verify | Yêu cầu xác minh lại. |
| GET /shadow-ledger/anchor-plan | Xem record đủ điều kiện neo. |
| POST /shadow-ledger/anchor-batches | Tạo batch (IssuerAdmin). |
| POST /shadow-ledger/anchor-batches/:id/signature | Gửi chữ ký; 202 Accepted. |
| GET /public/verifier-keys | Khóa công khai và trust metadata. |
Thao tác bất đồng bộ
202 Accepted là đã tiếp nhận yêu cầu, chưa phải giao dịch finalized. Theo dõi batch và trạng thái bản ghi trước khi thông báo neo thành công.
Bảng này là chỉ dẫn tìm endpoint, chưa thay thế API reference đầy đủ. Không tự suy đoán payload ký, các header xác thực hoặc response từ tên endpoint.
Nguồn đối chiếu trong monorepo
Nội dung dựa trên mã nguồn; trạng thái live được ghi riêng.
apps/api/src/modules/shadow-ledger/api/shadow-ledger.controller.tsapps/api/src/modules/shadow-ledger/api/anchor-batches.controller.tspackages/contracts/src/shadow-ledger.tsdocs/api/openapi.yaml
