Gửi dữ liệu

Mọi đường dẫn tính từ https://<trường>.<tên-miền-nền-tảng>/integration/v1. Thân yêu cầu là JSON (Content-Type: application/json), tối đa 5 MB.

Lệnh gửi theo lô luôn được xếp lượt và xử lý dần ở nền, để một lần gửi lớn không làm chậm cổng. Mọi lệnh ghi nhận ?dryRun=true để chạy thử.

Nguyên tắcSao chép liên kết tới mục này

• Không xoá. API không xoá sinh viên hay đợt. Sinh viên không còn học thì khoá; sinh viên không có trong lần gửi thì giữ nguyên.
• Không đổi cách đăng nhập của tài khoản đã có. Cập nhật chỉ đổi họ tên, mã sinh viên, externalId; email, mật khẩu và cách đăng nhập của tài khoản đã có giữ nguyên.
• Mọi sinh viên gửi lên đều là sinh viên thực tập của trường.
• Mọi thay đổi ghi vào Nhật ký của trường, người thực hiện là tên kết nối.

Đợt thực tậpSao chép liên kết tới mục này

PUT /seasons/external/{externalId} tạo hoặc cập nhật đợt theo một kỳ học bên hệ thống của trường. externalId là mã kỳ học (tối đa 128 ký tự).

curl -X PUT -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Học kỳ 2 năm học 2026-2027","startDate":"2027-02-10","endDate":"2027-06-30"}' \
  https://<trường>.<tên-miền-nền-tảng>/integration/v1/seasons/external/HK2-2026

Cổng xếp đợt theo ngày của kỳ:

Cổng không tự đóng đợt đang mở để chuyển sang đợt mới: khi có switchNeeded, cán bộ nhà trường xác nhận chuyển đợt ở trang Kết nối hệ thống. Gửi lại cùng externalId thì cập nhật tên và ngày đóng. Đợt chưa mở được mở khi bạn gửi lại trong thời gian kỳ diễn ra và trường không mở đợt nào khác (cổng không tự mở theo lịch).

{
  "result": "created",
  "data": { "id": "k3v9x2m1q8w7e6r5t4y3u2i1", "externalId": "HK2-2026", "name": "Học kỳ 2 năm học 2026-2027", "status": "upcoming", "openedAt": null, "closesAt": "2027-06-30T16:59:59.000Z", "closedAt": null, "updatedAt": "2026-11-13T02:00:00.000Z" },
  "switchNeeded": { "from": "Đợt thực tập học kỳ 1 năm học 2026-2027", "to": "Học kỳ 2 năm học 2026-2027" }
}

result: created, opened, updated, unchanged. Mã 201 khi tạo mới, 200 khi cập nhật.

Một sinh viênSao chép liên kết tới mục này

PUT /students/{studentCode} tạo hoặc cập nhật một sinh viên (không đổi đợt).

curl -X PUT -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Nguyễn Văn An","email":"[email protected]","externalId":"U-1001"}' \
  https://<trường>.<tên-miền-nền-tảng>/integration/v1/students/SV2026001

{ "result": "created", "data": { "id": "p0o9i8u7y6t5r4e3w2q1a2s3", "studentCode": "SV2026001", "externalId": "U-1001", "name": "Nguyễn Văn An", "email": "[email protected]", "signIn": "google", "loginName": null, "status": "active", "createdAt": "2026-11-13T02:00:00.000Z", "updatedAt": "2026-11-13T02:00:00.000Z" } }

result: created (201), updated, unchanged. Cổng tìm sinh viên theo externalId, rồi mã sinh viên, rồi email. Trả 409 khi dữ liệu trỏ tới hai tài khoản khác nhau, ví dụ email đã thuộc sinh viên có mã khác, hoặc mã sinh viên đã là tên đăng nhập của người khác.

Nhiều sinh viênSao chép liên kết tới mục này

POST /students/batch nhận tối đa 500 sinh viên mỗi lần, cùng các trường như trên cộng studentCode. Gửi thêm season (là id của đợt) để đưa luôn các sinh viên vào đợt đó.

curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a0e-6d55-4a8e-9a57-0f3b8e7d2c11" \
  -d '{"season":"k3v9x2m1q8w7e6r5t4y3u2i1","students":[{"studentCode":"SV2026001","name":"Nguyễn Văn An","email":"[email protected]"},{"studentCode":"SV2026002","name":"Trần Thị Bình","password":"MatKhau@2026"}]}' \
  https://<trường>.<tên-miền-nền-tảng>/integration/v1/students/batch

Cổng kiểm tra cả lô trước: có dòng sai (thiếu trường, trùng mã trong lô) thì trả 422 với danh sách errors và không xếp lượt gì. Hợp lệ thì trả 202 Accepted, tiêu đề Location trỏ tới lượt xử lý:

{ "job": { "id": "at8w3w2oxfpggp9ng0w5a3de", "kind": "students", "status": "queued", "dryRun": false, "total": 2, "processed": 0, "counts": {}, "warnings": {}, "failureCount": 0, "createdAt": "2026-11-13T02:00:00.000Z", "startedAt": null, "finishedAt": null, "by": "Kết nối “Phần mềm đào tạo”" } }

Đưa sinh viên vào đợtSao chép liên kết tới mục này

POST /seasons/{id}/enrollments nhận tối đa 500 sinh viên đã có, mỗi mục là { "studentCode": "..." } hoặc { "externalId": "..." }. Đợt đã đóng trả 409. Kết quả là một lượt xử lý (202), như trên.

Khoá và mở khoáSao chép liên kết tới mục này

POST /students/{studentCode}/block khoá tài khoản, như khi nhà trường khoá trên màn hình: sinh viên không đăng nhập được, hồ sơ đang chờ xét hoặc chờ trả lời bị rút và doanh nghiệp được báo. POST /students/{studentCode}/unblock mở lại. Không cần thân yêu cầu; phản hồi là sinh viên sau khi đổi.

Theo dõi việc xử lýSao chép liên kết tới mục này

GET /jobs/{id} trả trạng thái lượt (chỉ lượt do chính kết nối gửi):

counts đếm kết quả, ví dụ students.created, students.updated, students.blocked, enrollments.enrolled, seasons.created, failed. Nên hỏi lại mỗi 2 đến 5 giây.

GET /jobs/{id}/failures trả các dòng lỗi dạng CSV (ref,code,message). Dòng lỗi được giữ 30 ngày.