TRUNG TÂM API ƯU TIÊN HTMLTHAM CHIẾU CÓ QUẢN TRỊ

Trung tâm API Trusted ThingID

Tài liệu API dễ đọc cho lớp phân giải, DPP, tuyên bố, bằng chứng, ủy quyền, vòng đời, tra cứu, bộ kết nối và chứng thực thiết bị.

Đọc Hướng dẫn tích hợp Xem API tham chiếu

API vận hành

Ngữ nghĩa nghiệp vụ phải đi cùng giao thức tích hợp.

Mỗi thao tác đều nêu rõ mục đích, phạm vi, trạng thái, bằng chứng, các lỗi và cách khôi phục.

GET/v1/resolve/{identifier}Hợp đồng tham chiếu

Phân giải định danh chính thức hoặc bí danh được quản trị

Phân giải định danh chính thức hoặc bí danh được quản trị, đồng thời trả về ngữ cảnh thẩm quyền và mức bảo đảm.

Chủ thể: Người tiêu dùng app · Đơn vị vận hành Cổng nghiệp vụ · bên ngoài Đơn vị tích hợp
OAuth phạm vi: thing.read
Trạng thái trước: Định danh được cung cấp; không suy diễn bất kỳ thẩm quyền nào của nền tảng.
Trạng thái sau: Kết quả phân giải và ngữ cảnh nguồn – thẩm quyền được trả về; không làm thay đổi quan hệ pháp lý.

Bằng chứng: Ngữ cảnh kiểm toán cho việc phân giải và tương quan; không làm thay đổi trạng thái nghiệp vụ đáng kể.
Sự kiện: Không yêu cầu đối với thao tác đọc
Lỗi: 404 không nhận diện được định danh · 401/403 lỗi xác thực/phân quyền · 409 ngữ cảnh chưa rõ ràng hoặc trùng lặp, khi triển khai yêu cầu rà soát
Thử lại / phục hồi: Thử lại an toàn cho thao tác đọc, kèm mã tương quan.

Ví dụ yêu cầu / phản hồi

YÊU CẦU / Đầu vào

{"identifier":"0950600012345"}

PHẢN HỒI / KẾT QUẢ

{"officialIdentifier":"0950600012345","resolvedThingId":"ttid:thing:01HV...","aliases":["urn:epc:id:sgtin:..."],"authority":{"domain":"official-identifier","source":"issuing-scheme"},"assurance":{"level":"source-aware"}}

GET/v1/dpp/{identifier}Hợp đồng tham chiếu

Đọc chế độ xem DPP theo chính sách

Đọc chế độ xem DPP đủ điều kiện theo chính sách cho ngữ cảnh sản phẩm đã phân giải.

Chủ thể: Trình xem DPP · Người tiêu dùng · Bên liên quan được ủy quyền
OAuth phạm vi: dpp.read
Trạng thái trước: Định danh, mục đích, ủy quyền và ngữ cảnh công bố dữ liệu đều được đánh giá.
Trạng thái sau: Một chế độ xem công khai/hạn chế được tổng hợp và trả về; bản ghi nguồn vẫn giữ thẩm quyền.

Bằng chứng: Quyết định chính sách/công bố dữ liệu có thể được kiểm toán theo chính sách của từng triển khai.
Sự kiện: Không yêu cầu đối với thao tác đọc
Lỗi: 404 không có chế độ xem · 401/403 bị từ chối · 424 nguồn có thẩm quyền không khả dụng, khi áp dụng
Thử lại / phục hồi: Thử lại an toàn cho thao tác đọc; hành vi ở chế độ suy giảm phải được nêu rõ.

Ví dụ yêu cầu / phản hồi

YÊU CẦU / Đầu vào

{"identifier":"0950600012345","purpose":"consumer-view"}

PHẢN HỒI / KẾT QUẢ

{"identifier":"0950600012345","view":"public","profileVersion":"example-2026.1","fields":{"model":"Example Product"},"authority":{"registryStatus":"external-source"}}

POST/v1/claimsHợp đồng tham chiếu

Gửi tuyên bố có bằng chứng hỗ trợ

Gửi tuyên bố kèm bằng chứng hỗ trợ để được đánh giá và quản lý vòng đời theo quy trình quản trị.

Chủ thể: Chủ thể phát hành được ủy quyền · Chủ thể Kinh tế · luồng nghiệp vụ dịch vụ
OAuth phạm vi: claim.write
Trạng thái trước: Bằng chứng và ngữ cảnh chủ thể phát hành đã tồn tại; tuyên bố chưa được chấp nhận.
Trạng thái sau: Tuyên bố bước vào quy trình xử lý được quản trị; việc chấp nhận không đồng nghĩa với thẩm quyền pháp lý.

Bằng chứng: Tham chiếu bằng chứng, ngữ cảnh chủ thể phát hành, phiên bản chính sách và bản ghi kiểm toán.
Sự kiện: claim.status.changed
Lỗi: 400 sai lược đồ · 401/403 sai phạm vi/ủy quyền · 409 trùng lặp · 422 lỗi chính sách/bằng chứng
Thử lại / phục hồi: Dùng Idempotency-Key khi thử lại thao tác ghi.

Ví dụ yêu cầu / phản hồi

YÊU CẦU / Đầu vào

{"subject":"ttid:thing:01HV...","claimType":"ownership","issuer":"org:example","evidenceRefs":["evidence:transfer:123"]}

PHẢN HỒI / KẾT QUẢ

{"claimId":"claim:01...","status":"pending-governed-evaluation","correlationId":"corr-..."}

GET/v1/claims/{claimId}Hợp đồng tham chiếu

Đọc tuyên bố cùng ngữ cảnh nguồn gốc và trạng thái

Đọc một tuyên bố cùng với nguồn gốc dữ liệu và ngữ cảnh trạng thái.

Chủ thể: Cổng nghiệp vụ · bên xác minh · quản trị viên
OAuth phạm vi: claim.read
Trạng thái trước: Đã biết định danh của tuyên bố.
Trạng thái sau: Ngữ cảnh tuyên bố và trạng thái được quản trị hiện tại sẽ được trả về.

Bằng chứng: Thao tác đọc được kiểm toán theo chính sách; các liên kết nguồn gốc dữ liệu được giữ nguyên.
Sự kiện: claim.status.changed (liên quan)
Lỗi: 404 không tìm thấy tuyên bố · 403 bị từ chối công bố dữ liệu
Thử lại / phục hồi: Thử lại an toàn cho thao tác đọc.

Ví dụ yêu cầu / phản hồi

YÊU CẦU / Đầu vào

{"subject":"ttid:thing:01HV...","claimType":"ownership","issuer":"org:example","evidenceRefs":["evidence:transfer:123"]}

PHẢN HỒI / KẾT QUẢ

{"claimId":"claim:01...","status":"pending-governed-evaluation","correlationId":"corr-..."}

POST/v1/evidenceHợp đồng tham chiếu

Đăng ký tham chiếu bằng chứng

Đăng ký tham chiếu bằng chứng và siêu dữ liệu nguồn gốc, mà không chuyển khóa bí mật hay dữ liệu nguồn có thẩm quyền vào kho dữ liệu DPP.

Chủ thể: nghiệp vụ Dịch vụ · bộ kết nối · Cổng nghiệp vụ luồng nghiệp vụ
OAuth phạm vi: evidence.write
Trạng thái trước: Nguồn bằng chứng đã tồn tại và có ngữ cảnh lưu giữ, toàn vẹn được xác định rõ.
Trạng thái sau: Tham chiếu bằng chứng bước vào quy trình xử lý bằng chứng có quản trị.

Bằng chứng: Nguồn, loại, digest, dấu thời gian và siêu dữ liệu nguồn gốc.
Sự kiện: evidence.recorded
Lỗi: 400 sai lược đồ · 409 trùng lặp · 422 lỗi chính sách về tính toàn vẹn/nguồn gốc dữ liệu
Thử lại / phục hồi: Sử dụng Idempotency-Key khi gửi lại yêu cầu.

Ví dụ yêu cầu / phản hồi

YÊU CẦU / Đầu vào

{"source":"repair-order:7781","type":"repair-record","digest":"sha256:...","timestamp":"2026-09-02T00:00:00Z"}

PHẢN HỒI / KẾT QUẢ

{"evidenceId":"evidence:01...","status":"accepted-for-processing"}

POST/v1/mandatesHợp đồng tham chiếu

Phát hành hoặc gửi hồ sơ ủy quyền

Phát hành hoặc gửi hồ sơ ủy quyền với phạm vi và thời hạn rõ ràng.

Chủ thể: Chủ sở hữu · Tổ chức · Quản trị viên
OAuth phạm vi: mandate.write
Trạng thái trước: Chủ thể phát hành đã được xác thực và có quyền ủy quyền phạm vi được yêu cầu.
Trạng thái sau: Ủy quyền bước vào vòng đời được quản trị; điều này không đồng nhất ý nghĩa nghiệp vụ của quyền sở hữu và ủy quyền.

Bằng chứng: Chủ thể phát hành, chủ thể nhận ủy quyền, phạm vi, hiệu lực và bằng chứng hỗ trợ.
Sự kiện: claim.status.changed hoặc sự kiện vòng đời gửi hồ sơ ủy quyền, tùy theo hồ sơ triển khai
Lỗi: 403 chủ thể phát hành không đủ thẩm quyền · 409 trùng lặp · 422 phạm vi hoặc thời hạn không hợp lệ
Thử lại / phục hồi: Sử dụng Idempotency-Key khi gửi lại yêu cầu.

Ví dụ yêu cầu / phản hồi

YÊU CẦU / Đầu vào

{"issuer":"owner:123","subject":"repairer:456","scope":["repair.write"],"validUntil":"2026-12-31T23:59:59Z"}

PHẢN HỒI / KẾT QUẢ

{"mandateId":"mandate:01...","status":"active-after-policy-evaluation"}

POST/v1/things/{thingId}/transitionsHợp đồng tham chiếu

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.

Chủ thể: Chủ thể Kinh tế · vận hành hiện trường · luồng nghiệp vụ của cơ quan quản lý
OAuth phạm vi: lifecycle.write
Trạng thái trước: 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.
Trạng thái sau: 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.
Sự kiện: thing.lifecycle.changed
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 / phục hồi: Sử dụng Idempotency-Key và đối soát các kết quả không xác định.

Ví dụ yêu cầu / phản hồi

YÊU CẦU / Đầu vào

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

PHẢN HỒI / KẾT QUẢ

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

GET/v1/searchHợp đồng tham chiếu

Tra cứu mô hình đọc dẫn xuất

Tra cứu trên mô hình đọc dẫn xuất mà không coi chỉ mục tra cứu là hệ thống nguồn.

Chủ thể: Cổng nghiệp vụ · vận hành · người dùng được ủy quyền
OAuth phạm vi: thing.read
Trạng thái trước: Truy vấn tra cứu và ngữ cảnh công bố dữ liệu đã được cung cấp.
Trạng thái sau: Kết quả dẫn xuất được trả về và có thể phân giải ngược về các bản ghi có thẩm quyền/nhận biết nguồn dữ liệu.

Bằng chứng: Việc truy cập tra cứu có thể được kiểm toán theo chính sách của từng triển khai.
Sự kiện: Không có
Lỗi: 400 truy vấn không hợp lệ · 403 bị từ chối công bố dữ liệu · 503 chỉ mục không khả dụng
Thử lại / phục hồi: Thử lại an toàn cho thao tác đọc.

Ví dụ yêu cầu / phản hồi

YÊU CẦU / Đầu vào

{"q":"battery model X"}

PHẢN HỒI / KẾT QUẢ

{"results":[{"thingId":"ttid:thing:01...","officialIdentifier":"...","source":"derived-index"}],"authoritative":false}

GET/v1/connectors/{connectorId}/healthHợp đồng tham chiếu

Đọc trạng thái vận hành của bộ kết nối

Đọc trạng thái vận hành của bộ kết nối mà không đánh đồng tình trạng kênh truyền với trạng thái nghiệp vụ có thẩm quyền.

Chủ thể: Quản trị viên vận hành · kỹ sư tích hợp
OAuth phạm vi: connector.read
Trạng thái trước: Bộ kết nối đã tồn tại.
Trạng thái sau: Tình trạng hoạt động được trả về.

Bằng chứng: Số liệu giám sát vận hành và bằng chứng trạng thái bộ kết nối.
Sự kiện: connector.status.changed
Lỗi: 404 bộ kết nối · 403 vận hành phạm vi
Thử lại / phục hồi: Thử lại an toàn cho thao tác đọc.

Ví dụ yêu cầu / phản hồi

YÊU CẦU / Đầu vào

{"connectorId":"eu-dpp-registry"}

PHẢN HỒI / KẾT QUẢ

{"connectorId":"eu-dpp-registry","transport":"healthy","businessReconciliation":"required","authority":"external"}

POST/v1/connectors/{connectorId}/reconcileHợp đồng tham chiếu

Yêu cầu đối soát nghiệp vụ/hệ thống

Yêu cầu đối soát nghiệp vụ/hệ thống sau khi thử lại, sau gián đoạn hoặc khi kết quả từ bên ngoài chưa rõ ràng.

Chủ thể: Quản trị viên vận hành · luồng nghiệp vụ khôi phục tự động
OAuth phạm vi: connector.operate
Trạng thái trước: Đã phát hiện sai lệch hoặc kết quả từ bên ngoài chưa rõ ràng.
Trạng thái sau: Luồng đối soát được đưa vào hàng đợi; thẩm quyền bên ngoài vẫn thuộc về bên ngoài.

Bằng chứng: Lý do kích hoạt, trạng thái nguồn/đích, lịch sử thử lại và kết quả đối soát.
Sự kiện: connector.status.changed và sự kiện kết quả theo từng miền dữ liệu
Lỗi: 409 đối soát đang chạy · 422 sai lệch không được hỗ trợ · 503 hệ thống bên ngoài không khả dụng
Thử lại / phục hồi: Yêu cầu idempotent; đối soát khác với thử lại ở tầng truyền tải.

Ví dụ yêu cầu / phản hồi

YÊU CẦU / Đầu vào

{"connectorId":"eu-dpp-registry"}

PHẢN HỒI / KẾT QUẢ

{"connectorId":"eu-dpp-registry","transport":"healthy","businessReconciliation":"required","authority":"external"}

POST/v1/devices/{deviceId}/attestHợp đồng tham chiếu

Gửi bằng chứng attestation thiết bị để đánh giá

Gửi bằng chứng chứng thực thiết bị để được đánh giá theo một chính sách vận hành có gắn phiên bản.

Chủ thể: Tác tử vật thể · vận hành thiết bị
OAuth phạm vi: device.attested
Trạng thái trước: Đã biết định danh thiết bị, trạng thái chứng thư và ngữ cảnh thử thách.
Trạng thái sau: Bằng chứng được tiếp nhận để đánh giá; riêng hiệu lực chứng thư không tạo thành tin cậy khi vận hành.

Bằng chứng: Bằng chứng chứng thực, chính sách và phiên bản đánh giá, ngữ cảnh về độ mới và thử thách.
Sự kiện: Sự kiện đánh giá thiết bị theo từng triển khai
Lỗi: 401/403 sai định danh thiết bị hoặc phạm vi · 409 phát lại hoặc dữ liệu không đủ mới · 422 lỗi bằng chứng hoặc đánh giá
Thử lại / phục hồi: Chỉ thử lại khi ngữ nghĩa về độ mới dữ liệu và thử thách còn hợp lệ.

Ví dụ yêu cầu / phản hồi

YÊU CẦU / Đầu vào

{"deviceId":"device:123","attestation":{"format":"deployment-selected","challenge":"..."}}

PHẢN HỒI / KẾT QUẢ

{"appraisalId":"appraisal:01...","status":"accepted-for-appraisal","certificateStatus":"separate-context"}

TRÌNH KHÁM PHÁ TĨNH

Khám phá hợp đồng API mà không cần máy chủ.

YÊU CẦU

PHẢN HỒI THAM CHIẾU

Trình khám phá API tĩnh chỉ hiển thị ví dụ và không gọi API vận hành thực tế.

ĐẶC TẢ

Đặc tả máy đọc được là thao tác thứ cấp.

Đặc tả đọc được bằng máy

OpenAPI 3.1

Hợp đồng REST tham chiếu.

Tải YAML ↓

AsyncAPI 3.0

Event Hợp đồng tham chiếu.

Tải YAML ↓

Postman

Bộ sưu tập này phục vụ thử nghiệm có kiểm soát.

Tải JSON ↓