Đến nội dung
Tài liệu/Tham chiếu kỹ thuật

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/v1Mục đích
POST /shadow-ledger/ingestMultipart: file JSON, plantId, recordType.
POST /shadow-ledger/commit-offchainXác nhận recordIds, ghi seal và log.
GET /shadow-ledger/records/:id/evidenceTải bằng chứng theo quyền nhà máy.
POST /shadow-ledger/records/:id/verifyYêu cầu xác minh lại.
GET /shadow-ledger/anchor-planXem record đủ điều kiện neo.
POST /shadow-ledger/anchor-batchesTạo batch (IssuerAdmin).
POST /shadow-ledger/anchor-batches/:id/signatureGửi chữ ký; 202 Accepted.
GET /public/verifier-keysKhó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.ts
  • apps/api/src/modules/shadow-ledger/api/anchor-batches.controller.ts
  • packages/contracts/src/shadow-ledger.ts
  • docs/api/openapi.yaml