Tài liệu kết nối

Dành cho đơn vị cung cấp dịch vụ đã ký kết với TRACE.VN — hợp đồng điện tử, hoá đơn điện tử, chữ ký số, kiểm nghiệm, chứng nhận, thiết kế và in ấn tem. Hệ thống của bạn nhận việc, báo giá và bàn giao kết quả qua API, không cần người đăng nhập thủ công.

1. Trước khi kết nối

Ba điều kiện, thiếu một là cổng đóng:

1. Đơn vị đã được tạo trên hệ thống và được cấp mã đơn vị theo loại dịch vụ.
2. Hồ sơ KYC đã được duyệt. Chưa duyệt thì tài khoản chỉ tồn tại, không thao tác được.
3. Đã được gán Module 5 (Đối tác dịch vụ). Khoá API hợp lệ nhưng thiếu module này thì vẫn bị từ chối ngay tại cổng.

Mã đơn vị theo loại dịch vụ

Tiền tố	Loại đơn vị	Tiền tố	Loại đơn vị
eC-	Hợp đồng điện tử	KN-	Kiểm nghiệm
eI-	Hoá đơn điện tử	CN-	Chứng nhận
eS-	Chữ ký số	TK-	Thiết kế tem
DV-	Cung cấp dịch vụ	IN-	In ấn tem
CG-	Chuyên gia tư vấn	VT-	Cung ứng vật tư
NN-	Cơ quan quản lý nhà nước

Khoá API do quản trị hệ thống TRACE.VN cấp riêng cho từng đơn vị. Liên hệ support@trace.vn để được cấp.

2. Xác thực

Gửi khoá ở header X-API-Key trên mọi yêu cầu. Cổng này không dùng phiên đăng nhập, không cần lấy token trước.

Địa chỉ gốc: https://api.trace.vn/api

# Kiểm tra kết nối — nên gọi đầu tiên
curl https://api.trace.vn/api/api-don-vi/ho-so \
  -H "X-API-Key: <khoá của đơn vị>"

Kết nối đúng thì nhận về hồ sơ đơn vị và danh sách module được gán:

{
  "donVi": { "id": "...", "ten": "...", "loai": "...", "kyc": "da_duyet" },
  "moduleDuocGan": [5],
  "ketNoi": "OK — khoá API hợp lệ, hồ sơ đã xác minh."
}

Khi bị từ chối

Mã	Thông báo	Nghĩa là
401	Thiếu khoá API. Gửi kèm header X-API-Key…	Yêu cầu không có header khoá.
401	Khoá API không hợp lệ hoặc đã bị thu hồi.	Sai khoá, hoặc khoá đã bị vô hiệu.
403	Không có quyền với module này	Khoá đúng nhưng đơn vị chưa được gán Module 5.

3. Vòng đời một công việc

TRACE.VN giao việc cho đơn vị; hệ thống của bạn nhận, báo giá rồi bàn giao kết quả. Bốn bước, theo đúng thứ tự:

1. Lấy danh sách việc được giao cho đơn vị mình.
2. Nhận việc — xác nhận đơn vị sẽ làm.
3. Báo giá — gửi số tiền và diễn giải để bên giao duyệt.
4. Hoàn thành — nộp kết quả để bên giao nghiệm thu.

4. Danh mục endpoint

Hồ sơ đơn vị và trạng thái kết nối. Dùng để kiểm tra khoá còn sống.

Danh sách module đơn vị được gán — quyết định đơn vị làm được nghiệp vụ nào.

Toàn bộ công việc đang giao cho đơn vị, kèm trạng thái từng việc.

Nhận việc. Không có thân yêu cầu.

Gửi báo giá.

{
  "soTien": 2500000,          // số nguyên, > 0
  "dienGiai": "..."           // tuỳ chọn, tối đa 2000 ký tự
}

Nộp kết quả để bên giao nghiệm thu.

{
  "ketQua": "..."             // bắt buộc, tối đa 4000 ký tự
}

ketQua là bắt buộc: một công việc "hoàn thành" mà không nói rõ kết quả là gì thì bên giao không có căn cứ nghiệm thu.

5. Ví dụ trọn một vòng

KEY="<khoá của đơn vị>"
API="https://api.trace.vn/api/api-don-vi"

# 1. Kiểm tra kết nối
curl -H "X-API-Key: $KEY" $API/ho-so

# 2. Xem việc được giao
curl -H "X-API-Key: $KEY" $API/cong-viec

# 3. Nhận việc
curl -X POST -H "X-API-Key: $KEY" $API/cong-viec/<id>/nhan

# 4. Báo giá
curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"soTien":2500000,"dienGiai":"Phí dịch vụ trọn gói"}' \
  $API/cong-viec/<id>/bao-gia

# 5. Bàn giao kết quả
curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"ketQua":"Đã phát hành, mã tham chiếu ..."}' \
  $API/cong-viec/<id>/hoan-thanh

6. Quy ước chung

• Múi giờ UTC. Mọi mốc thời gian trả về là giờ UTC, không kèm ký hiệu vùng.
• Thông báo lỗi bằng tiếng Việt, nằm ở trường message, kèm statusCode chuẩn HTTP.
• Chỉ dùng HTTPS.
• Mọi thao tác đổi trạng thái đều được ghi vết và không xoá được.

7. Hỗ trợ kỹ thuật

Vướng ở bước nào, gửi kèm mã đơn vị, thời điểm gọi và nguyên văn thông báo lỗi tới support@trace.vn. Đừng gửi khoá API trong thư — chúng tôi không cần nó để tra cứu.