Tổng quan API của cổng

Không phải hệ thống nào của trường cũng hỗ trợ OneRoster. API của cổng (v1) là một API REST JSON đơn giản để phần mềm của trường đọc và gửi dữ liệu thực tập: sinh viên, đợt thực tập, ghi danh vào đợt, khoá tài khoản; đọc kết quả thực tập và doanh nghiệp đã duyệt. API này cũng nhận gói CSV OneRoster cho trường xuất được gói nhưng không có API OneRoster.

Hệ thống đã hỗ trợ OneRoster 1.2 thì nên dùng API OneRoster để đọc. Hai API dùng chung kết nối, quyền và giới hạn.

Đặc điểm chínhSao chép liên kết tới mục này

• Địa chỉ gốc: https://<trường>.<tên-miền-nền-tảng>/integration/v1. Trường được xác định theo tên miền; mã của trường nào chỉ dùng được ở trường đó.
• Định dạng: JSON UTF-8. Thời điểm theo ISO 8601 (UTC); ngày (startDate, endDate) dạng YYYY-MM-DD theo giờ Việt Nam.
• Lỗi: theo Problem Details (RFC 9457), kiểu application/problem+json. Xem Giới hạn và lỗi.
• Đặc tả máy đọc được: OpenAPI 3.1 tại /integration/v1/openapi.json.

Xác thựcSao chép liên kết tới mục này

Mọi lời gọi gửi tiêu đề Authorization: Bearer <mã>. Nhà trường tạo kết nối ở trang Kết nối hệ thống và chọn một trong hai loại:

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://<trường>.<tên-miền-nền-tảng>/integration/v1/seasons"

• Thay khoá: nhà trường bấm Thay khoá để cấp mã (hoặc khoá bí mật) mới; mã cũ còn dùng được 24 giờ để kịp đổi.
• Thu hồi: ngừng ngay mọi mã của kết nối; không hoàn tác được.
• Giới hạn địa chỉ: nếu nhà trường nhập danh sách địa chỉ mạng (IPv4/IPv6, nhận dạng CIDR như 203.0.113.0/24), lời gọi từ địa chỉ khác bị từ chối với 403.

QuyềnSao chép liên kết tới mục này

Theo dõi việc xử lý (/jobs/...) cần một trong các quyền ghi: students:write, enrollments:write, imports:write. Thiếu quyền trả 403 kèm tên quyền cần.

Quy ước chungSao chép liên kết tới mục này

Phân trangSao chép liên kết tới mục này

Danh sách dài (/students, /seasons/{id}/enrollments, /seasons/{id}/results) trả từng trang:

• limit: 1 đến 500, mặc định 100.
• Thân phản hồi có next: chuỗi con trỏ của trang sau, hoặc null khi hết. Gửi lại bằng ?cursor=<next> cùng các tham số cũ.
• Tiêu đề Link: <...>; rel="next" (RFC 8288) chứa sẵn địa chỉ trang sau.

Đồng bộ phần thay đổiSao chép liên kết tới mục này

GET /students?updatedSince=2026-11-01T00:00:00Z chỉ trả sinh viên có thay đổi từ thời điểm đó. Lưu thời điểm bắt đầu mỗi lần đồng bộ rồi dùng cho lần sau.

Chạy thửSao chép liên kết tới mục này

Mọi lệnh ghi nhận ?dryRun=true: cổng kiểm tra và trả kết quả như thật nhưng không lưu gì.

Gửi lại an toànSao chép liên kết tới mục này

Lệnh gửi theo lô (POST) nhận tiêu đề Idempotency-Key (1 đến 255 ký tự, nên dùng UUID). Gửi lại cùng khoá trong 24 giờ thì nhận lại đúng phản hồi lần đầu (kèm Idempotent-Replayed: true), không tạo việc mới. Cùng khoá mà nội dung khác thì bị từ chối (422).

Định danhSao chép liên kết tới mục này

• Sinh viên được nhận ra theo mã sinh viên (studentCode, không phân biệt hoa thường).
• externalId (tuỳ chọn, tối đa 128 ký tự) là mã của bản ghi trong hệ thống của trường. Gửi kèm thì lần sau cổng nhận ra sinh viên theo mã này trước, rồi mới tới mã sinh viên, rồi email.
• Đợt thực tập có id do cổng cấp và externalId là mã kỳ học bên hệ thống trường.

Các nhóm điểm truy cậpSao chép liên kết tới mục này