Phiên bản: 2.3.0

Tạo mới hoặc cập nhật người lao động

Ngày cập nhật: 18 tháng 8, 2026
Người cập nhật: VNPT eContract's team

Mục đích

Tạo mới hoặc cập nhật thông tin người lao động trong hệ thống, đồng thời tự động tạo/cập nhật tài khoản người dùng (user) liên kết với NLĐ. Đây là bước đầu tiên, cần thực hiện trước khi khởi tạo hợp đồng lao động cho người lao động tương ứng (mục 7.2).

Request URL: /api/employees/create-or-update
HTTP method: POST
HTTP content-type: application/json
Authorize: Bearer token
Parameter:

Key	Type	Description
`employeeCode`	string	[Bắt buộc] Mã định danh người lao động (dùng để xác định tạo mới hay cập nhật)
`fullName`	string	[Bắt buộc] Họ và tên người lao động
`dateOfBirth`	string	[Bắt buộc] Ngày sinh (định dạng: `yyyy-MM-dd`)
`gender`	int	[Bắt buộc] Giới tính theo danh mục hệ thống: - 1: Nam - 2: Nữ
`identityNumber`	string	[Bắt buộc] Số CCCD/CMND
`email`	string	[Bắt buộc] Email người lao động
`phoneNumber`	string	[Bắt buộc] Số điện thoại
`socialInsuranceCode`	string	Mã sổ bảo hiểm xã hội
`status`	int	[Bắt buộc] Trạng thái NLĐ (1: Kích hoạt)
`workingPosition`	int	[Bắt buộc] Vị trí công việc theo danh mục hệ thống
`contractType`	int	[Bắt buộc] Loại hợp đồng (2: Xác định thời hạn)
`contractReportType`	int	Hình thức báo cáo hợp đồng
`contractSigningMethod`	int	[Bắt buộc] Hình thức ký hợp đồng (1: HĐLĐ điện tử)
`jobTitle`	string	[Bắt buộc] Chức danh công việc
`salary`	number	[Bắt buộc] Mức lương
`salaryAllowance`	number	Phụ cấp lương
`contractEffectiveDate`	string	[Bắt buộc] Ngày hiệu lực hợp đồng hiện tại của NLĐ (định dạng: `yyyy-MM-dd`)
`contractExpiredDate`	string	Ngày hết hạn hợp đồng (định dạng: `yyyy-MM-dd`, truyền `null` nếu không xác định thời hạn)
`contractNote`	string	Ghi chú hợp đồng
`user`	object	[Bắt buộc] Đối tượng thông tin tài khoản đăng nhập { "code": "string", // [Bắt buộc] Mã tài khoản đăng nhập liên kết "username": "string", // [Bắt buộc] Tên đăng nhập (thường là email) "name": "string", // [Bắt buộc] Tên hiển thị tài khoản "generateSelfSignedCertEnabled": boolean // Tự động sinh CTS tự ký (true/false) }

ghi chú

Request Body là một mảng (array), cho phép tạo/cập nhật nhiều người lao động trong cùng một lần gọi. Nếu employeeCode đã tồn tại trong hệ thống, bản ghi sẽ được cập nhật; nếu chưa tồn tại, hệ thống sẽ tạo mới.

Request mẫu

[
  {
    "employeeCode": "NVC20260805062149",
    "fullName": "Nguyễn Văn Cường 2149",
    "dateOfBirth": "1997-02-17",
    "gender": 1,
    "identityNumber": "909218625041",
    "email": "nguyenvancuong20260805062149@example.com",
    "phoneNumber": "091****109",
    "socialInsuranceCode": "BH178591090921862504",
    "status": 1,
    "workingPosition": 1,
    "contractType": 2,
    "contractReportType": 1,
    "contractSigningMethod": 1,
    "jobTitle": "Chuyên viên kinh doanh",
    "salary": 20000000,
    "salaryAllowance": 4,
    "contractEffectiveDate": "2026-01-15",
    "contractExpiredDate": null,
    "contractNote": "Hợp đồng lao động xác định thời hạn tạo qua API",
    "user": {
      "code": "NVC20260805062149",
      "username": "nguyenvancuong20260805062149@example.com",
      "name": "Nguyễn Văn Cường 2149",
      "generateSelfSignedCertEnabled": false
    }
  }
]

Response mẫu — http 200

{
  "data": [
    {
      "id": 1430,
      "createdDate": "2026-08-05T13:21:52.8949042+07:00",
      "userId": 70427,
      "user": {
        "id": 70427,
        "createdDate": "2026-08-05T13:21:51.9310169+07:00",
        "comId": 7354,
        "code": "NVC20260805062149",
        "username": "nguyenvancuong20260805062149@example.com",
        "name": "Nguyễn Văn Cường 2149",
        "phone": "091****109",
        "email": "nguyenvancuong20260805062149@example.com",
        "identityVerificationStatus": {
          "value": 0,
          "description": "Not verified"
        },
        "identityVerifiedType": {
          "value": 0,
          "description": "Unknown"
        },
        "identityVerifiedSource": {
          "value": 0,
          "description": "Unknown"
        },
        "isValid": false,
        "signConfirmationEnabled": true,
        "isAccountLocked": false,
        "accountId": "5cf86e5e-b873-48a5-9c6b-eb9c3384dcda",
        "signMethod": {
          "value": 2,
          "description": "VNPT SmartCA"
        },
        "status": {
          "value": 1,
          "description": "Enabled"
        },
        "receiveOtpMethod": {
          "value": 1,
          "description": "Email"
        },
        "receiveNotificationMethod": {
          "value": 0,
          "description": "Email"
        },
        "usedMemory": 0,
        "waitingChangeRequest": false,
        "twoFactorEnabled": false
      },
      "employeeCode": "NVC20260805062149",
      "fullName": "Nguyễn Văn Cường 2149",
      "dateOfBirth": "1997-02-17T00:00:00",
      "gender": 1,
      "identityNumber": "909218625041",
      "email": "nguyenvancuong20260805062149@example.com",
      "phoneNumber": "091****109",
      "socialInsuranceCode": "BH178591090921862504",
      "status": {
        "value": 1,
        "description": "Enabled"
      },
      "currentWorkingPosition": 1,
      "currentJobTitle": "Chuyên viên kinh doanh",
      "currentSalary": 20000000,
      "currentSalaryAllowance": 4,
      "currentContractType": 2,
      "currentReportType": 1,
      "currentContractEffectiveDate": "2026-01-15T00:00:00",
      "currentContractNote": "Hợp đồng lao động xác định thời hạn tạo qua API",
      "currentContractSigningMethod": {
        "value": 1,
        "description": "Electronic Labor Contract"
      },
      "syncStatus": {
        "value": 1,
        "description": "Not Synced"
      },
      "currentContractNumber": ""
    }
  ],
  "success": true,
  "code": 0,
  "messages": [
    "Create 1 employee success, update 0 employee success."
  ]
}

thông tin

Lưu ý: messages trả về thể hiện số bản ghi được tạo mới/cập nhật thành công, ví dụ: "Create 1 employee success, update 0 employee success."

Response Parameter

Key	Type	Description
`data`	Array[object]	Danh sách thông tin người lao động đã tạo mới/cập nhật thành công
`success`	boolean	Trạng thái xử lý yêu cầu (true: Thành công, false: Thất bại)
`code`	int	Mã trạng thái phản hồi
`messages`	Array[string]	Danh sách thông báo kết quả xử lý từ hệ thống

Chi tiết các thuộc tính trong `data`:

Key	Type	Description
`id`	int	ID bản ghi người lao động trong hệ thống
`createdDate`	string	Thời gian tạo bản ghi (định dạng ISO 8601)
`userId`	int	ID tài khoản người dùng liên kết
`user`	object	Chi tiết thông tin tài khoản đăng nhập liên kết (xem bên dưới)
`employeeCode`	string	Mã định danh người lao động
`fullName`	string	Họ và tên người lao động
`dateOfBirth`	string	Ngày sinh (định dạng ISO 8601)
`gender`	int	Giới tính (1: Nam, 2: Nữ)
`identityNumber`	string	Số CCCD/CMND
`email`	string	Email người lao động
`phoneNumber`	string	Số điện thoại
`socialInsuranceCode`	string	Mã số bảo hiểm xã hội
`status`	object	Trạng thái người lao động 1: Enabled -1: Disabled
`currentWorkingPosition`	int	Vị trí công việc hiện tại
`currentJobTitle`	string	Chức danh công việc
`currentSalary`	number	Mức lương hiện tại
`currentSalaryAllowance`	number	Phụ cấp lương
`currentContractType`	int	Loại hợp đồng 1: Không định thời hạn 2: Xác định thời hạn
`currentReportType`	int	Hình thức báo cáo hợp đồng
`currentContractEffectiveDate`	string	Ngày hiệu lực hợp đồng (định dạng ISO 8601)
`currentContractNote`	string	Ghi chú hợp đồng
`currentContractSigningMethod`	object	Hình thức ký hợp đồng 1: Electronic Labor Contract (Hợp đồng lao động điện tử) 2: Paper Labor Contract (Hợp đồng lao động giấy)
`syncStatus`	object	Trạng thái đồng bộ 1: Not Synced (Chưa đồng bộ) 2: Synced (Đã đồng bộ) 3: Failed (Thất bại)
`currentContractNumber`	string	Số hợp đồng hiện tại

Chi tiết đối tượng `user` trong Response:

Key	Type	Description
`id`	int	ID tài khoản người dùng
`createdDate`	string	Thời gian tạo tài khoản (định dạng ISO 8601)
`comId`	int	ID công ty/doanh nghiệp
`code`	string	Mã tài khoản người dùng
`username`	string	Tên đăng nhập
`name`	string	Tên hiển thị người dùng
`phone`	string	Số điện thoại
`email`	string	Địa chỉ email
`identityVerificationStatus`	object	Trạng thái xác thực danh tính (0: Not verified)
`identityVerifiedType`	object	Loại xác thực danh tính
`identityVerifiedSource`	object	Nguồn xác thực danh tính
`isValid`	boolean	Trạng thái hợp lệ của tài khoản
`signConfirmationEnabled`	boolean	Bật/tắt xác nhận khi ký
`isAccountLocked`	boolean	Trạng thái khóa tài khoản
`accountId`	string	GUID định danh tài khoản hệ thống
`signMethod`	object	Phương thức ký (2: VNPT SmartCA)
`status`	object	Trạng thái tài khoản (1: Enabled)
`receiveOtpMethod`	object	Phương thức nhận OTP (1: Email)
`receiveNotificationMethod`	object	Phương thức nhận thông báo (0: Email)
`usedMemory`	number	Dung lượng lưu trữ đã sử dụng
`waitingChangeRequest`	boolean	Có yêu cầu thay đổi thông tin đang chờ duyệt hay không
`twoFactorEnabled`	boolean	Bật/tắt xác thực 2 yếu tố

Các lỗi thường gặp

`success`	`code`	`messages`	Ý nghĩa
`false`	`400`	`"Identity number already exists for another employee: 0123456XXXXX"`	Mã số định danh/CCCD này đã được sử dụng cho một nhân viên khác. Cần kiểm tra lại hoặc nhập mã khác.
`false`	`0`	`"The user already exists with a different username. Please check again in the User list"`	Đã tồn tại mã nhân viên (User Code) trong hệ thống gắn với một Username khác. Cần kiểm tra Danh sách người dùng để điều chỉnh lại User Code.
`false`	`0`	`"Username example@email.com already exists in the company"`	Username/Email này đã tồn tại trong công ty. Cần thay đổi Username khác.

Mục đích​

Request mẫu​

Response mẫu — http 200​

Response Parameter​

Chi tiết các thuộc tính trong data:​

Chi tiết đối tượng user trong Response:​

Các lỗi thường gặp​