Đang tải dữ liệu...
Tài nguyên kỹ thuật
Tài liệu giao tiếp lập trình và chuẩn tích hợp dành cho nhà phát triển, hệ thống giáo dục và các tác tử AI trên nền tảng Giáo Án 24h.
Giáo Án 24h cung cấp hệ thống API RESTful phục vụ tra cứu danh mục, kiểm tra trạng thái dịch vụ và tích hợp mua tài liệu giáo dục số. Nền tảng hỗ trợ các tiêu chuẩn khám phá tự động theo chuẩn RFC 9727 và các tài liệu đặc tả máy đọc.
Lưu ý: Hệ thống sử dụng phiên bản URL cố định, bảo đảm tính toàn vẹn của dữ liệu giáo án, bài giảng và tài nguyên số.
Dưới đây là các ví dụ cURL thực tế gọi đến các điểm cuối đang hoạt động trên hệ thống Giáo Án 24h:
Kiểm tra trạng thái hệ thống:
curl -s https://giaoan24h.com/api/healthPhản hồi công khai: {"status":"ok"} (hoặc kèm chi tiết thành phần khi ở môi trường phát triển).
Tra cứu danh mục cây phân cấp tài liệu:
curl -s https://giaoan24h.com/api/v1/catalog/categoriesTrả về danh sách danh mục phân cấp với các trường: id, name, slug, parentId, fullPath, depth, isActive.
Tra cứu các gói nạp xu hiện hành:
curl -s https://giaoan24h.com/api/v1/topup/denominationsTrả về cấu hình mệnh giá và tỷ lệ thưởng xu phục vụ nạp ví.
Kiểm tra trạng thái đơn hàng (Polling QR Checkout):
curl -s -b "order_access_{orderId}=..." https://giaoan24h.com/api/v1/checkout/{orderId}Yêu cầu phiên đăng nhập người mua hoặc cookie chữ ký truy cập đơn hàng phát hành khi tạo đơn.
Giáo Án 24h sử dụng cơ chế phiên dựa trên cookie mã hóa HMAC (better-auth.session_data), không vận hành máy chủ cấp phát OAuth 2.0 / Bearer token cho bên thứ ba.
Để tích hợp thay mặt người dùng hoặc tác tử AI, client thực hiện các bước đăng nhập tiêu chuẩn qua Better Auth:
POST /api/auth/sign-in/email: Đăng nhập bằng email và mật khẩu.POST /api/auth/sign-in/email-otp: Xác thực 2 bước qua mã OTP gửi về email.GET /api/auth/session: Kiểm tra trạng thái phiên hiện hành.Các endpoint có kiểm soát hạn mức (search, checkout, topup, giftcode, chat, biểu mẫu công khai...) thông báo định mức của bạn trên mọi phản hồi thông qua bộ tiêu đề chuẩn RFC 9331:
RateLimit-Limit - số yêu cầu tối đa cho phép trong cửa sổ hiện tại.RateLimit-Remaining - số yêu cầu còn lại trong cửa sổ.RateLimit-Reset - số giây còn lại đến khi cửa sổ được đặt lại.429 Too Many Requests kèm thân JSON chuẩn ApiError ({ error: { code: 'rate_limited', message } }) và tiêu đề Retry-After: <giây> cho biết thời gian chờ trước khi thử lại.Tự điều tiết: client nên đọc RateLimit-Remaining và RateLimit-Reset để giãn nhịp yêu cầu; khi nhận 429, hãy chờ đủ Retry-After giây trước khi thử lại thay vì gửi lại ngay lập tức. Ví dụ: hạn mức tìm kiếm công khai là 30 yêu cầu/phút trên mỗi địa chỉ IP; các hạn mức hỗ trợ và tương tác AI có bảo vệ burst và hạn ngạch ngày riêng biệt.
Tất cả API chính thức được định danh phiên bản qua tiền tố URL: /api/v1/*. Các thay đổi phá vỡ tương thích (breaking changes) chỉ được phát hành dưới một tiền tố phiên bản mới (ví dụ /api/v2/*) và KHÔNG bao giờ sửa đổi hợp đồng v1 hiện hành.
- Tính ổn định: Các endpoint trong v1 không thay đổi phá vỡ tương thích mà không nâng cấp phiên bản URL; các trường mới chỉ được thêm dưới dạng tùy chọn (optional).
- Quy trình ngừng hỗ trợ (deprecation): Khi một endpoint chuẩn bị ngừng hoạt động, hệ thống sẽ thông báo qua:
Deprecation: @<timestamp> (RFC 9745) - thời điểm endpoint bắt đầu bị deprecate (Unix timestamp).Sunset: <ngày HTTP> (RFC 8594) - thời điểm endpoint chính thức ngừng hoạt động.- Thời hạn hỗ trợ: Endpoint bị deprecate được duy trì hoạt động tối thiểu 6 tháng kể từ khi tiêu đề Deprecation xuất hiện lần đầu trước khi tới ngày Sunset. Mọi thông báo đều được cập nhật tại cổng tài liệu này.
Nhằm đảm bảo an toàn dữ liệu và tính trung thực, Giáo Án 24h không cung cấp thông tin định danh ảo hay môi trường sandbox chia sẻ công khai. Thay vào đó, nhà phát triển có thể thiết lập môi trường cục bộ độc lập thông qua Docker Compose:
docker compose --env-file .env.local up -dMôi trường cục bộ cung cấp đầy đủ dịch vụ cơ sở dữ liệu PostgreSQL, PgBouncer, Valkey và MinIO tương đương với kiến trúc production.
Các tài nguyên đọc công khai sau có thể truy cập trực tiếp bằng phương thức GET mà không yêu cầu phiên người dùng:
GET /api/health- Kiểm tra trạng thái máy chủGET /api/v1/catalog/categories- Danh sách cây danh mục và khối lớpGET /api/v1/topup/denominations- Danh sách mệnh giá nạp xu công khaiGET /api-docs- Trang tài liệu kỹ thuật HTMLGET /openapi.json- Tệp đặc tả OpenAPI 3.1GET /.well-known/api-catalog- Danh mục API catalog RFC 9727GET /llms.txt- Tài liệu khám phá máy đọc cho tác tử AI (text/markdown)GET /.well-known/oauth-protected-resource- Metadata tài nguyên bảo vệ theo RFC 9728 (application/json)