API Danh mục tổ chức & vai trò

Hai endpoint chỉ đọc, là bước chuẩn bị bắt buộc trước khi đồng bộ người dùng: hệ thống của bạn cần biết eContract gọi phòng ban và chức danh bằng mã nào.

#	Endpoint	Mục đích
1	`GET /api/integration/directory/organizations`	Cây đơn vị của tenant
2	`GET /api/integration/directory/roles`	Vai trò của tenant

Toàn bộ nhóm directory nói bằng mã, không bằng id số: code của đơn vị và vai trò chính là giá trị bạn gửi lại ở organizationCode / roleCode khi tạo hoặc cập nhật người dùng.

Base URL

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

Xác thực

Nhóm directory chỉ nhận X-API-Key — không có đường đi bằng access token.

Loại key	`tenantCode`	Tenant được xác định là
Toàn cục (không gắn tổ chức)	Bắt buộc	Tổ chức có `code` trùng `tenantCode`
Theo tổ chức	Tuỳ chọn	Tổ chức của key. Gửi `tenantCode` thì phải trùng, lệch là `403`

GET /api/integration/directory/organizations?tenantCode=ACME
X-API-Key: econtract_a1b2c3d4e5f6...

Với key toàn cục, tenantCode đi ở query string (request GET) hoặc trong body (request POST/PUT). Cả hai đều được đọc.

tenantCode phải chỉ tới đúng một tổ chức. organizations.code không có ràng buộc duy nhất trên toàn hệ thống, nên khi một mã trùng ở hai tổ chức, key toàn cục nhận 400 TENANT_CODE_AMBIGUOUS thay vì bị gán bừa vào một tenant.

Đừng gắn API Key theo tổ chức vào tài khoản super admin. Endpoint /auth/login-server đổi một API Key hợp lệ thành access token của tài khoản gắn key mà không cần mật khẩu — key gắn super admin vì thế là thông tin xác thực cấp toàn hệ thống, không còn giới hạn trong một tenant. Hãy gắn vào tài khoản quản trị của chính tenant đó.

1. Danh sách đơn vị

GET /api/integration/directory/organizations

Query

Tham số	Kiểu	Mặc định	Mô tả
`tenantCode`	`string`	—	Bắt buộc với key toàn cục
`code`	`string`	—	Lọc đúng một đơn vị theo mã (khớp tuyệt đối)
`parentCode`	`string`	—	Chỉ lấy đơn vị con trực tiếp của đơn vị này
`status`	`integer`	—	`1` hoạt động, `2` ngừng, `3` tạm khoá
`type`	`integer`	—	Loại đơn vị
`q`	`string`	—	Tìm theo tên hoặc mã, không phân biệt hoa thường
`updatedFrom`	`string`	—	ISO 8601 — chỉ lấy bản ghi sửa từ mốc này trở đi
`updatedTo`	`string`	—	ISO 8601
`page`	`integer`	`1`	Trang, tính từ 1
`pageSize`	`integer`	`50`	Tối đa `200`

Response

{
  "items": [
    {
      "code": "ACME",
      "name": "Công ty ACME",
      "parentCode": null,
      "type": 1,
      "status": 1,
      "address": "12 Nguyễn Huệ, Q1",
      "phone": "02838221234"
    },
    {
      "code": "ACME-IT",
      "name": "Phòng Công nghệ thông tin",
      "parentCode": "ACME",
      "type": 1,
      "status": 1,
      "address": null,
      "phone": null
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 2
}

Trường	Mô tả
`code`	Mã đơn vị — giá trị dùng làm `organizationCode` khi gán người dùng
`parentCode`	Mã đơn vị cha. `null` khi đây là gốc tenant, hoặc khi cha nằm ngoài tenant của bạn
`status`	`1` hoạt động, `2` ngừng, `3` tạm khoá. Dữ liệu cũ có thể mang giá trị khác

Kết quả luôn giới hạn trong cây tenant đã phân giải. Đơn vị của tenant khác không bao giờ xuất hiện, kể cả khi trùng mã.

2. Danh sách vai trò

GET /api/integration/directory/roles

Query

Tham số	Kiểu	Mặc định	Mô tả
`tenantCode`	`string`	—	Bắt buộc với key toàn cục
`code`	`string`	—	Lọc đúng một vai trò theo mã
`organizationCode`	`string`	—	Chỉ lấy vai trò thuộc đơn vị này
`status`	`integer`	—	Trạng thái vai trò
`isDepartmentHead`	`boolean`	—	`true` chỉ lấy vai trò trưởng đơn vị
`q`	`string`	—	Tìm theo tên hoặc mã
`updatedFrom` / `updatedTo`	`string`	—	ISO 8601
`page`	`integer`	`1`
`pageSize`	`integer`	`50`	Tối đa `200`

Response

{
  "items": [
    {
      "code": "NHANVIEN",
      "name": "Nhân viên",
      "organizationCode": "ACME-IT",
      "isDepartmentHead": false,
      "status": 1
    },
    {
      "code": "TRUONGPHONG",
      "name": "Trưởng phòng",
      "organizationCode": "ACME-IT",
      "isDepartmentHead": true,
      "status": 1
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 2
}

code của vai trò thường không phân biệt được gì. Trên dữ liệu thực tế, phần lớn vai trò dùng chung một mã mặc định (role) — kể cả nhiều vai trò trong cùng một đơn vị. Thứ duy nhất trong phạm vi một đơn vị là name.Vì vậy khi gán người dùng, hãy gửi organizationCode + roleName. Dùng roleCode chỉ an toàn khi tổ chức của bạn thật sự đặt mã riêng cho từng vai trò.

organizationCode trả về null khi đơn vị sở hữu vai trò đã bị xoá mềm. Vai trò vẫn được liệt kê để bạn thấy dữ liệu tồn đọng, nhưng đừng gán người dùng vào nó.

Mã lỗi

HTTP	`code`	Nguyên nhân
`400`	`TENANT_CODE_REQUIRED`	Dùng key toàn cục nhưng không gửi `tenantCode`
`400`	`TENANT_CODE_AMBIGUOUS`	`tenantCode` trùng ở nhiều tổ chức
`403`	`TENANT_CODE_MISMATCH`	Key gắn tổ chức A nhưng `tenantCode` chỉ tới tổ chức B
`404`	`TENANT_CODE_NOT_FOUND`	Không có tổ chức nào mang mã đó
`404`	`ORGANIZATION_CODE_NOT_FOUND`	`organizationCode` / `parentCode` không có trong tenant
`400`	`ORGANIZATION_CODE_AMBIGUOUS`	Mã đơn vị trùng ở nhiều bản ghi trong tenant
`401`	`API_KEY_LEGACY_NOT_SUPPORTED`	Dùng API Key kiểu cũ (lưu dạng plaintext, không thu hồi được)

Danh sách đầy đủ: Mã lỗi.

Tổng quan

Xác thực

Endpoints

Webhook

Mã lỗi

API Danh mục tổ chức & vai trò

Base URL

Xác thực

1. Danh sách đơn vị

Query

Response

2. Danh sách vai trò

Query

Response

Mã lỗi

​Base URL

​Xác thực

​1. Danh sách đơn vị

​Query

​Response

​2. Danh sách vai trò

​Query

​Response

​Mã lỗi

Base URL

Xác thực

1. Danh sách đơn vị

Query

Response

2. Danh sách vai trò

Query

Response

Mã lỗi