HƯỚNG DẪN NHÀ PHÁT TRIỂNHợp đồng tham chiếu

API Vòng đời

Áp dụng chuyển trạng thái vật liệu có quy trách nhiệm, gắn phiên bản chính sách, kèm điều kiện tiên quyết và bằng chứng.

Hướng dẫn tích hợp Trung tâm dành cho Nhà phát triển Xem Trung tâm API

NGUYÊN TẮC HỢP ĐỒNG

Giao thức phải giữ nguyên ngữ nghĩa nghiệp vụ.

Mỗi tích hợp phải giữ nguyên ngữ cảnh thẩm quyền, chính sách, bằng chứng và cơ chế khôi phục.

Ranh giới phiên bản

Khóa cứng phiên bản API, lược đồ và hồ sơ trong bằng chứng kiểm thử.

Tương quan

Mang mã tương quan xuyên suốt yêu cầu, sự kiện, bộ kết nối và bản ghi bằng chứng.

Idempotency

Bảo vệ các thao tác ghi quan trọng khỏi bị phát lại ngoài ý muốn.

Ngữ cảnh thẩm quyền

Không suy luận thẩm quyền pháp lý chỉ từ việc truyền dữ liệu thành công.

ĐIỂM KẾT NỐI THAM CHIẾU

Khám phá đầy đủ hợp đồng OpenAPI.

Đặc tả tải xuống bao gồm mô hình yêu cầu/phản hồi, phạm vi OAuth, cơ chế chống trùng lặp và các mã lỗi tiêu biểu.

Bề mặt API tham chiếu
Nhóm API	Hợp đồng kỹ thuật	Ý nghĩa nghiệp vụ
Phân giải	`GET /v1/resolve/{identifier}`	Phân giải định danh chính thức hoặc bí danh được quản trị.
DPP	`GET /v1/dpp/{identifier}`	Đọc DPP theo chính sách và quyền truy cập.
Tuyên bố	`POST /v1/claims`	Gửi tuyên bố có bằng chứng hỗ trợ.
Bằng chứng	`POST /v1/evidence`	Đăng ký tham chiếu bằng chứng và nguồn gốc dữ liệu.
Ủy quyền	`POST /v1/mandates`	Gửi hoặc phát hành hồ sơ ủy quyền.
Vòng đời	`POST /v1/things/{thingId}/transitions`	Yêu cầu chuyển trạng thái nghiệp vụ quan trọng.
Tra cứu	`GET /v1/search`	Tra cứu trên mô hình đọc dẫn xuất.
Bộ kết nối	`POST /v1/connectors/{connectorId}/reconcile`	Yêu cầu đối soát trạng thái nghiệp vụ/hệ thống.

POST/v1/things/{thingId}/transitions

Yêu cầu chuyển trạng thái vòng đời quan trọng

Yêu cầu các chuyển trạng thái vòng đời quan trọng như sửa chữa, chuyển giao, áp hạn chế hay kết thúc — dưới sự kiểm soát của chính sách và bằng chứng.

OAuth: lifecycle.write
Trạng thái: Trạng thái hiện tại, ủy quyền của chủ thể và các điều kiện trước đã được xác định. → Yêu cầu chuyển trạng thái được tiếp nhận để đánh giá; trạng thái mới chỉ được ghi nhận sau khi các điều kiện chính sách và bằng chứng đạt yêu cầu.
Bằng chứng: Điều kiện tiên quyết, evidenceRefs, trustedTimeRef và policyVersion.
Lỗi: 409 trạng thái hiện tại không hợp lệ · 422 điều kiện/bằng chứng không đạt · 403 bị từ chối theo ủy quyền
Thử lại: Sử dụng Idempotency-Key và đối soát các kết quả không xác định.

{"event":"repair.completed","actor":"repairer:456","preconditions":["mandate-valid"],"evidenceRefs":["evidence:repair:01"],"policyVersion":"repair-policy-2026.1"}

{"transitionId":"transition:01...","status":"accepted-for-evaluation"}

Mở Trung tâm API Tải OpenAPI YAML ↓

HỘI THẢO KIẾN TRÚC

Từ tích hợp tới phê duyệt có bằng chứng.

Căn chỉnh phạm vi nhóm sản phẩm, ranh giới thẩm quyền, hành trình cổng nghiệp vụ, hợp đồng tích hợp và bằng chứng trước khi tuyên bố sẵn sàng vận hành.

Đăng ký hội thảo Xem kiến trúc