API Công việc ký

Ba endpoint xoay quanh công việc ký của một người dùng và vết phê duyệt của hồ sơ.

#	Endpoint	Mục đích
1	`GET /api/integration/tasks`	Danh sách hồ sơ cần ký / đã ký
2	`GET /api/integration/tasks/{taskCode}`	Chi tiết một công việc
3	`GET /api/integration/documents/{documentId}/history`	Lịch sử phê duyệt của hồ sơ

Base URL

Môi trường	Base URL
Production	`https://api.econtractid.com/api`
Development	`https://api-dev.epaperless.vn/api`

Cả ba endpoint chấp nhận hai cách xác thực, chọn một:

Header	Dùng khi	Người dùng được xác định là
`X-API-Key: econtract_...`	Backend của bạn gọi server-to-server	Tài khoản gắn với API Key
`x-access-token: eyJhbGciOi...`	Ứng dụng/iframe gọi thay cho người dùng cuối	Chủ sở hữu access token

GET /api/integration/tasks
X-API-Key: econtract_a1b2c3d4e5f6...

API Key phải resolve được người dùng. Key chưa gắn tài khoản → 401 với message API key chưa gắn người dùng; tài khoản đã bị vô hiệu hoá → 401 Tài khoản dịch vụ không hoạt động. Xem Xác thực.API Key trả về công việc của chính tài khoản gắn với key. Muốn lấy danh sách theo từng người ký, dùng access token của người đó (lấy qua partner-login).

Access token đi ở header x-access-token, không phải Authorization: Bearer. Gửi đồng thời cả hai header thì X-API-Key được ưu tiên.

1. Danh sách công việc ký

GET /api/integration/tasks

Body

Không có. Đây là request GET, mọi tham số truyền qua query string.

Query

Tham số	Kiểu	Mặc định	Mô tả
`status`	`enum`	(tất cả)	Xem bảng giá trị ngay dưới. Bỏ trống = `all`
`page`	`integer`	`1`	Trang, tính từ 1
`pageSize`	`integer`	`20`	Số bản ghi mỗi trang, tối đa `100`
`fromDate`	`string`	—	ISO 8601. `pending` lọc theo `assignedAt`; `completed` lọc theo `actionAt`
`toDate`	`string`	—	ISO 8601, cùng quy tắc với `fromDate`
`documentId`	`string`	—	Lọc đúng một hồ sơ theo mã hồ sơ bạn cấp khi tạo
`keyword`	`string`	—	Tìm toàn văn theo tên hồ sơ và tên bước ký

Giá trị của `status`

Giá trị là bản viết thường của items[].status, cộng hai giá trị gộp:

Giá trị	Trả về
`pending`	Công việc đang chờ người dùng xử lý
`approved`	Công việc người dùng đã ký / đã duyệt
`rejected`	Công việc người dùng đã từ chối
`expired`	Công việc người dùng để quá hạn
`completed`	Gộp `approved` + `rejected` + `expired`
`all` (mặc định)	Tất cả, trộn và sắp xếp theo thời gian giảm dần

Các tập con cộng lại đúng bằng tập cha: approved + rejected + expired = completed, và pending + completed = all.

# Cả cần ký lẫn đã ký
curl -sS -H "X-API-Key: econtract_a1b2c3d4..." \
  "https://api.econtractid.com/api/integration/tasks?page=1&pageSize=20"

# Chỉ hồ sơ cần ký
curl -sS -H "X-API-Key: econtract_a1b2c3d4..." \
  "https://api.econtractid.com/api/integration/tasks?status=pending"

# Chỉ hồ sơ đã ký (bỏ qua từ chối và quá hạn)
curl -sS -H "X-API-Key: econtract_a1b2c3d4..." \
  "https://api.econtractid.com/api/integration/tasks?status=approved"

Tham số không nằm trong bảng trên bị bỏ qua, không báo lỗi.

Response

{
  "statusCode": 200,
  "data": {
    "items": [
      {
        "taskId": 2476,
        "taskCode": "TI000123",
        "stepCode": "customer",
        "stepName": "Khách hàng ký",
        "signType": "digital_signature",
        "status": "PENDING",
        "assignedAt": "2026-07-10T04:50:12.000Z",
        "expireAt": "2026-07-17T04:50:12.000Z",
        "document": {
          "folderId": 12345,
          "documentId": "HD-2026-001",
          "documentUuid": "8d5e7b2a-1c4f-4a3b-9d6e-2f8c7a1e5b9d",
          "documentTitle": "Hợp đồng dịch vụ — Nguyễn Văn A",
          "transactionId": "PI000042",
          "ecmClassCode": "Tai-lieu-hop-dong-lao-dong",
          "status": "PENDING_SIGN",
          "requiredCount": 2,
          "signedCount": 0,
          "createdAt": "2026-07-10T04:50:00.000Z"
        }
      }
    ],
    "page": 1,
    "pageSize": 20,
    "total": 1
  },
  "timestamp": "2026-07-10T05:00:00.000Z"
}

Trường cấp `data`

Trường	Kiểu	Mô tả
`items[]`	`array`	Danh sách công việc, xem bảng dưới
`page`	`integer`	Trang hiện tại (echo lại query)
`pageSize`	`integer`	Kích thước trang (echo lại query)
`total`	`integer`	Tổng số bản ghi khớp bộ lọc, không phụ thuộc phân trang

Trường của `items[]`

Trường	Kiểu	Mô tả
`taskId`	`integer`	ID số của công việc. Dùng dựng deeplink mở giao diện econtractid: `/tasks?id={taskId}` (nhúng iframe hoặc SDK)
`taskCode`	`string`	Định danh công việc (vd `TI000123`). Dùng làm path param cho endpoint chi tiết
`stepCode`	`string`	Mã bước ký trong quy trình — chính là `stepCode` bạn gửi khi tạo hồ sơ
`stepName`	`string`	Tên hiển thị của bước ký
`signType`	`string`	Hình thức ký cấu hình ở bước: `digital_signature`, `image_signature`, `app_submit`, `notification`
`status`	`enum`	`PENDING` (chờ xử lý) · `APPROVED` (đã ký/duyệt) · `REJECTED` (đã từ chối) · `EXPIRED` (quá hạn). Xem bảng suy ra bên dưới
`assignedAt`	`string`	Thời điểm công việc được giao (ISO 8601)
`expireAt`	`string`	Hạn xử lý (ISO 8601). Vắng mặt nếu bước không đặt hạn
`actionAt`	`string`	Thời điểm người dùng ký/từ chối. Chỉ có ở bản ghi đã xử lý
`comment`	`string`	Ý kiến người dùng nhập khi ký hoặc từ chối
`document`	`object`	Hồ sơ chứa công việc này, xem bảng dưới

Trường của `items[].document`

Trường	Kiểu	Mô tả
`folderId`	`integer`	ID số của hồ sơ (= `folderId` ở API tạo hồ sơ). Deeplink: `/folders?id={folderId}`
`documentId`	`string`	Mã hồ sơ bạn cấp khi tạo — khớp với `documentId` ở các endpoint khác. Rỗng nếu hồ sơ không được tạo qua Integration API (vd người dùng tạo trực tiếp trên web)
`documentUuid`	`string`	UUID công khai của hồ sơ, bất biến
`documentTitle`	`string`	Tên hiển thị của hồ sơ
`transactionId`	`string`	Mã tiến trình quy trình (vd `PI000042`)
`ecmClassCode`	`string`	Phân loại hồ sơ
`status`	`enum`	Trạng thái hồ sơ — cùng thang giá trị với tra cứu hồ sơ: `PENDING`, `PENDING_SIGN`, `IN_PROGRESS`, `COMPLETED`, `REJECTED`, `EXPIRED`
`requiredCount`	`integer`	Tổng số bước ký của hồ sơ
`signedCount`	`integer`	Số bước ký đã hoàn tất
`createdAt`	`string`	Thời điểm tạo hồ sơ (ISO 8601)

`items[].status` được suy ra từ đâu

Nguồn	Giá trị DB	`status` trả về
Hành động đã thực hiện (`task_history.action_code`)	`NEXT`	`APPROVED`
	`REJECT`	`REJECTED`
	`OVERDUE`	`EXPIRED`
Trạng thái công việc (`process_tasks.status`) — khi chưa có hành động nào của người dùng	`1` (chờ)	`PENDING`
	`2`	`APPROVED`
	`3`	`REJECTED`
	`4`	`EXPIRED`

Hành động được ưu tiên hơn trạng thái công việc: một bước có thể đã bị đóng bởi bước sau, nhưng lượt xử lý của bạn vẫn phải phản ánh đúng việc bạn đã làm.

Danh sách trả về mọi công việc của người dùng, kể cả hồ sơ do người dùng tạo trực tiếp trên web. Những hồ sơ đó không có mã bạn cấp nên document.documentId rỗng — hãy dùng document.documentUuid làm định danh ổn định trong trường hợp này.

Trường không có giá trị được lược khỏi JSON, không trả null. Ví dụ hồ sơ chờ ký sẽ không có actionAt và comment; bước không đặt hạn sẽ không có expireAt.

Khác biệt giữa hai loại bản ghi

	Chờ xử lý	Đã xử lý
Nguồn	Công việc đang chờ, thuộc hồ sơ đang chạy	Mỗi lượt người dùng đã ký / từ chối / để quá hạn
`items[].status`	`PENDING`	`APPROVED` · `REJECTED` · `EXPIRED`
`actionAt`	Không có	Luôn có
Lọc `fromDate`/`toDate` theo	`assignedAt`	`actionAt`

Khi status bỏ trống, hai loại được trộn và sắp xếp theo thời gian giảm dần (actionAt nếu đã xử lý, assignedAt nếu đang chờ).

Một công việc có thể xuất hiện hai lần khi bạn lấy cả hai loại: bước có nhiều người ký, bạn đã ký phần mình (bản ghi APPROVED) nhưng bước vẫn đang chờ người còn lại (bản ghi PENDING). Đây là hai sự kiện khác nhau, không phải trùng lặp.

2. Chi tiết một công việc

GET /api/integration/tasks/{taskCode}

taskCode lấy từ items[].taskCode của endpoint danh sách. Trả về toàn bộ trường của một item trong danh sách, kèm ba nhóm bổ sung: assignee, files/attachments, và history.

{
  "statusCode": 200,
  "data": {
    "taskId": 2476,
    "taskCode": "TI000123",
    "stepCode": "customer",
    "stepName": "Khách hàng ký",
    "signType": "digital_signature",
    "status": "APPROVED",
    "assignedAt": "2026-07-10T04:50:12.000Z",
    "expireAt": "2026-07-17T04:50:12.000Z",
    "actionAt": "2026-07-10T04:53:51.644Z",
    "comment": "Đồng ý các điều khoản",
    "assignee": {
      "email": "a@x.com",
      "phone": "0909123001",
      "identityNumber": "079209876543"
    },
    "document": {
      "folderId": 12345,
      "documentId": "HD-2026-001",
      "documentUuid": "8d5e7b2a-1c4f-4a3b-9d6e-2f8c7a1e5b9d",
      "documentTitle": "Hợp đồng dịch vụ — Nguyễn Văn A",
      "transactionId": "PI000042",
      "ecmClassCode": "Tai-lieu-hop-dong-lao-dong",
      "status": "IN_PROGRESS",
      "requiredCount": 2,
      "signedCount": 1,
      "createdAt": "2026-07-10T04:50:00.000Z"
    },
    "files": [
      {
        "id": 678,
        "fileUuid": "f1a2b3c4-...",
        "title": "Hợp đồng",
        "type": "MAIN",
        "url": "https://minio.../f1a2b3c4.pdf?X-Amz-Signature=...",
        "downloadUrl": "/api/integration/files/f1a2b3c4-.../download",
        "ecmClassCode": "Tai-lieu-hop-dong-lao-dong",
        "size": 234567,
        "mimeType": "application/pdf"
      }
    ],
    "attachments": [],
    "history": [
      {
        "taskId": 2476,
        "taskCode": "TI000123",
        "stepCode": "customer",
        "stepName": "Khách hàng ký",
        "action": "NEXT",
        "actionLabel": "Ký duyệt",
        "actionAt": "2026-07-10T04:53:51.644Z",
        "comment": "Đồng ý các điều khoản",
        "actorName": "Nguyễn Văn A",
        "actorEmail": "a@x.com"
      }
    ]
  },
  "timestamp": "2026-07-10T05:00:00.000Z"
}

Trường bổ sung

Trường	Kiểu	Mô tả
`assignee`	`object`	Người phải xử lý bước. Chỉ chứa các trường ứng với loại bước: khách mời → `email`/`phone`/`identityNumber`/`taxCode`; nhân sự nội bộ → `username`/`name`/`email`/`phone`; bước theo vai trò → thêm `roleCode`/`roleName`
`files[]`	`array`	File chính của hồ sơ — cùng cấu trúc với liệt kê file
`attachments[]`	`array`	File đính kèm, không tham gia ký
`history[]`	`array`	Lịch sử thao tác của riêng công việc này, xem bảng ở mục 3

username và roleCode/roleName chỉ trả với bước ký bằng tài khoản nội bộ. Với khách mời, username hệ thống chính là CCCD/MST nên không được trả ra, tránh lộ định danh cá nhân qua trường sai ngữ nghĩa.

Lỗi

HTTP	Nguyên nhân
`404`	`taskCode` không tồn tại, hoặc nằm ngoài phạm vi đọc của bạn (gộp hai trường hợp — không lộ sự tồn tại)

3. Lịch sử phê duyệt của hồ sơ

GET /api/integration/documents/{documentId}/history

Toàn bộ vết phê duyệt của hồ sơ — mọi bước, mọi người ký — sắp xếp theo thời gian tăng dần, đọc từ trên xuống là đúng trình tự.

{
  "statusCode": 200,
  "data": {
    "folderId": 12345,
    "documentId": "HD-2026-001",
    "documentUuid": "8d5e7b2a-1c4f-4a3b-9d6e-2f8c7a1e5b9d",
    "documentTitle": "Hợp đồng dịch vụ — Nguyễn Văn A",
    "transactionId": "PI000042",
    "status": "COMPLETED",
    "requiredCount": 2,
    "signedCount": 2,
    "history": [
      {
        "taskId": 2476,
        "taskCode": "TI000123",
        "stepCode": "customer",
        "stepName": "Khách hàng ký",
        "action": "NEXT",
        "actionLabel": "Ký duyệt",
        "actionAt": "2026-07-10T04:53:51.644Z",
        "comment": "Đồng ý các điều khoản",
        "actorName": "Nguyễn Văn A",
        "actorEmail": "a@x.com"
      },
      {
        "taskId": 2477,
        "taskCode": "TI000124",
        "stepCode": "internal_user",
        "stepName": "Nhân sự nội bộ ký",
        "action": "NEXT",
        "actionAt": "2026-07-10T04:55:36.327Z",
        "actorName": "Nguyễn Thành Long",
        "actorUsername": "longnt"
      }
    ]
  },
  "timestamp": "2026-07-10T05:00:00.000Z"
}

Trường của `history[]`

Trường	Kiểu	Mô tả
`taskId`	`integer`	ID số của công việc — deeplink `/tasks?id={taskId}`
`taskCode`	`string`	Mã công việc tương ứng — dùng để gọi endpoint chi tiết
`stepCode`	`string`	Mã bước ký
`stepName`	`string`	Tên bước ký
`action`	`enum`	`NEXT` (ký/duyệt) · `REJECT` (từ chối) · `OVERDUE` (quá hạn)
`actionLabel`	`string`	Nhãn hiển thị do quy trình cấu hình (vd `Ký duyệt`)
`actionAt`	`string`	Thời điểm thực hiện (ISO 8601)
`comment`	`string`	Ý kiến người xử lý
`actorName`	`string`	Họ tên người thực hiện
`actorUsername`	`string`	Username — chỉ với bước ký bằng tài khoản nội bộ
`actorEmail` / `actorPhone`	`string`	Email / SĐT người thực hiện

Bản ghi OVERDUE do hệ thống sinh khi bước quá hạn; actor* khi đó là người được giao bước, không phải người bấm nút.

Lỗi

HTTP	Nguyên nhân
`404`	`documentId` không tồn tại, hoặc nằm ngoài phạm vi đọc của bạn

Phạm vi dữ liệu

Danh sách công việc luôn giới hạn theo người dùng đã xác thực: công việc gán trực tiếp, gán cho vai trò họ đảm nhiệm, hoặc do người khác uỷ quyền cho họ (uỷ quyền chỉ áp cho phần chờ xử lý).
Khi xác thực bằng X-API-Key, kết quả còn bị giới hạn trong tổ chức của API Key. Với access token thì không — phạm vi giống hệt những gì người dùng thấy trên web/app.
Với lịch sử phê duyệt hồ sơ, người ký bên ngoài chỉ đọc được hồ sơ mà họ có tham gia.
Không có công việc nào → items là mảng rỗng, total bằng 0. Không trả 404.

total được tính theo đúng cách web/app đếm — phần chờ xử lý đếm số công việc, phần đã xử lý đếm số lượt xử lý — nên con số khớp với màn hình Xử lý công việc của người dùng.

Lỗi chung

HTTP	Nguyên nhân
`400`	`status` không thuộc `{pending, approved, rejected, expired, completed, all}`; `page`/`pageSize` không phải số nguyên dương; `pageSize` lớn hơn `100`; `fromDate`/`toDate` không đúng ISO 8601
`401`	API Key sai/thu hồi/hết hạn, API Key chưa gắn người dùng, tài khoản không hoạt động, hoặc access token sai/hết hạn

Chi tiết: Mã lỗi.

Bước tiếp theo

API Hồ sơ

Tạo hồ sơ, tra cứu trạng thái đầy đủ và tải file

Webhook

Nhận thông báo thay vì hỏi vòng (polling)

Tổng quan

Xác thực

Endpoints

Webhook

Mã lỗi

Base URL

Header

1. Danh sách công việc ký

Body

Query

Giá trị của `status`

Response

Trường cấp `data`

Trường của `items[]`

Trường của `items[].document`

`items[].status` được suy ra từ đâu

Khác biệt giữa hai loại bản ghi

2. Chi tiết một công việc

Trường bổ sung

Lỗi

3. Lịch sử phê duyệt của hồ sơ

Trường của `history[]`

Lỗi

Phạm vi dữ liệu

Lỗi chung

Bước tiếp theo

API Hồ sơ

Webhook

​Base URL

​Header

​1. Danh sách công việc ký

​Body

​Query

​Giá trị của status

​Response

​Trường cấp data

​Trường của items[]

​Trường của items[].document

​items[].status được suy ra từ đâu

​Khác biệt giữa hai loại bản ghi

​2. Chi tiết một công việc

​Trường bổ sung

​Lỗi

​3. Lịch sử phê duyệt của hồ sơ

​Trường của history[]

​Lỗi

​Phạm vi dữ liệu

​Lỗi chung

​Bước tiếp theo

API Hồ sơ

Webhook

Base URL

Header

1. Danh sách công việc ký

Body

Query

Giá trị của `status`

Response

Trường cấp `data`

Trường của `items[]`

Trường của `items[].document`

`items[].status` được suy ra từ đâu

Khác biệt giữa hai loại bản ghi

2. Chi tiết một công việc

Trường bổ sung

Lỗi

3. Lịch sử phê duyệt của hồ sơ

Trường của `history[]`

Lỗi

Phạm vi dữ liệu

Lỗi chung

Bước tiếp theo