Giới thiệu API - econtractid

Tải bản PDF phần API Reference

Trọn bộ tài liệu tích hợp (xác thực, endpoint, webhook, mã lỗi) dưới dạng PDF để gửi cho đội phát triển. Xem thêm các bản PDF khác.

Tổng quan

Integration API cho phép hệ thống của bạn tạo hồ sơ ký số, theo dõi trạng thái và nhận callback khi hồ sơ hoàn tất — không cần người dùng thao tác trên giao diện econtractid.

Base URL Production

https://api.econtractid.com/api

Base URL Development

https://api-dev.epaperless.vn/api

Quy ước	Giá trị
Namespace	`/integration/*`
Xác thực	Header `X-API-Key`
Content-Type	`application/json`
Đặt tên field	camelCase

Các API chính

Việc cần làm	Endpoint
Tạo hồ sơ ký số	`POST /api/integration/documents`
Kích hoạt quy trình (khi tạo với `disableStart: true`)	`POST /api/integration/documents/{documentId}/start`
Tra cứu trạng thái hồ sơ	`GET /api/integration/documents/{documentId}`
Liệt kê file của hồ sơ	`GET /api/integration/documents/{documentId}/files`
Tải file	`GET /api/integration/files/{fileUuid}/download`
Lấy danh sách hồ sơ cần ký / đã ký của một người dùng	`GET /api/integration/tasks`
Xem chi tiết một công việc ký	`GET /api/integration/tasks/{taskCode}`
Xem lịch sử phê duyệt của hồ sơ	`GET /api/integration/documents/{documentId}/history`
Bắn thử webhook tới endpoint đã đăng ký	`POST /api/integration/webhooks/test`
Nhận thông báo hoàn tất	Webhook gửi tới URL đã đăng ký

Chi tiết: API Hồ sơ · API Công việc ký · Webhook

Xác thực

Mọi request gửi kèm header X-API-Key:

X-API-Key: econtract_a1b2c3d4e5f6...
Content-Type: application/json

Xem chi tiết tại Xác thực.

Định dạng Response

Mọi response REST đều được bọc trong envelope chuẩn. Dữ liệu thật nằm trong data:

{
  "statusCode": 200,
  "data": { },
  "timestamp": "2026-05-15T10:00:00.123Z"
}

Trường	Kiểu	Mô tả
`statusCode`	`number`	Luôn là `200` khi thành công — xem cảnh báo bên dưới
`data`	`object`	Dữ liệu trả về
`timestamp`	`string`	Thời điểm response (ISO 8601)

statusCode trong body không phải HTTP status thật. Response thành công luôn ghi 200, trong khi POST trả về HTTP 201. Luôn kiểm tra HTTP status code thật của response, không dựa vào trường này.

Webhook payload KHÔNG có envelope — gửi raw object. Xem Webhook.

Response lỗi có shape riêng:

{
  "statusCode": 400,
  "code": "INVALID_FILE_URL",
  "message": "fileUrl must use HTTPS",
  "data": null,
  "timestamp": "2026-05-15T10:00:00Z"
}

Danh sách mã lỗi: Mã lỗi.

Nguyên tắc codes-first

API dùng mã do bạn cung cấp thay vì ID số nội bộ, giúp định danh ổn định khi hệ thống nâng cấp:

Mã	Nguồn	Dùng để
`documentId`	Bạn cấp khi tạo hồ sơ	Định danh hồ sơ + khoá idempotency
`processDefCode`	Cấu hình workflow của bạn	Chọn quy trình ký
`stepCode`	Cấu hình workflow của bạn	Gán người ký vào đúng bước
`ecmClassCode`	Cấu hình phân loại tài liệu	Xác định loại tài liệu
`documentUuid`, `fileUuid`	Hệ thống sinh, bất biến	Tham chiếu chéo hệ thống, tải file
`taskCode`	Hệ thống sinh, bất biến	Định danh một công việc ký (vd `TI000123`)

Idempotency

documentId là khoá idempotency. Gọi POST /documents hai lần với cùng documentId trong một tổ chức → lần thứ hai trả về 409 DUPLICATE_DOCUMENT_ID, không tạo hồ sơ trùng.

Dùng chính mã hồ sơ bên hệ thống của bạn (vd: HD-2026-001) làm documentId — vừa tránh trùng, vừa đối chiếu được hai chiều mà không cần lưu thêm bảng mapping.

Onboarding

Trước khi tích hợp, cần liên hệ đội ngũ econtractid để thiết lập:

API Key

Được cấp khi onboard tổ chức. Chỉ hiển thị 1 lần — lưu vào secret manager ngay.

Process definition + step code

Đặt mã cho từng bước trong quy trình ký (vd: STEP_SIGN_HR, STEP_SIGN_MANAGER). Sau đó request chỉ cần trỏ người ký vào đúng stepCode — workflow luôn map chính xác kể cả khi thứ tự bước thay đổi.

Webhook subscription

Gửi cho đội ngũ econtractid: URL endpoint (HTTPS) + danh sách event muốn nhận. Admin tạo subscription và cấp HMAC secret (hiển thị 1 lần). Partner không tự đăng ký webhook qua API được.

Tải bản PDF phần API Reference

​Tổng quan

Base URL Production

Base URL Development

​Các API chính

​Xác thực

​Định dạng Response

​Nguyên tắc codes-first

​Idempotency

​Onboarding

Tổng quan

Các API chính

Xác thực

Định dạng Response

Nguyên tắc codes-first

Idempotency

Onboarding