คู่มือ API สำหรับนักพัฒนา

ตรวจสอบสถานะ API, การเชื่อมต่อฐานข้อมูล, ปีการศึกษาและภาคเรียนที่ใช้งานอยู่

Response: { status, database, activeAcademicYear, activeTerm, checkedAt }

สร้าง CSRF token สำหรับ login — ส่ง JSON { csrfToken } และตั้ง cookie csrf_token (httpOnly, SameSite=strict, อายุ 15 นาที)

Double-submit cookie pattern: client เก็บ csrfToken จาก JSON response แล้วส่งกลับเป็น header x-csrf-token ใน POST. Token มีลายเซ็น HMAC จาก CSRF_SIGNING_KEY. Cookie ตั้งแบบ httpOnly + SameSite=strict เพื่อป้องกัน XSS และ cross-origin access.

เข้าสู่ระบบด้วย email และ password (urlencoded) — ต้องส่ง x-csrf-token header ที่ได้จาก GET /auth/login

Rate limit: 5 ครั้ง/15 นาที/IP. Header: x-csrf-token (required). Body: email, password (urlencoded). สำเร็จ: 303 redirect + Set-Cookie: __Host-pv_session. ล้มเหลว: 303 redirect กลับ /login พร้อม error query param.

ลงทะเบียนองค์กรใหม่ (self-service) — สร้าง OrganizationProfile, OrganizationPlan (free tier) และ SUPER_ADMIN ใน transaction เดียว

Body: { organizationName, organizationNameEnglish?, email, password, confirmPassword, displayName }. Rate limit: 10 req/hr/IP. Validates email format, password ≥8 chars, matching confirmPassword. Returns 201 on success, 409 if email already exists.

นำเข้าข้อมูลจากระบบ SIS (Student Information System) — รองรับ entityType: TEACHER, ROOM

Requires: settings:write permission. Body: { entityType: 'TEACHER'|'ROOM', records: [...] }. Returns: { ok, data: { jobId, source, entityType, status, summary } }

นำเข้าข้อมูลจากระบบ HR — รองรับเฉพาะ entityType: TEACHER เท่านั้น

Requires: settings:write permission. Body: { entityType: 'TEACHER', records: [...] }. Returns: { ok, data: { jobId, source, entityType, status, summary } }

Server-Sent Events (SSE) stream สำหรับติดตามการเปลี่ยนแปลงตารางสอนแบบเรียลไทม์

Requires: schedule:view permission. Content-Type: text/event-stream. Events: 'ready' (initial state), 'schedule-update' (changes), 'heartbeat' (every 15s). Use EventSource() on client to connect.

ส่งออกตารางสอนเป็นไฟล์ CSV — รองรับมุมมอง teacher, group, room

Requires: schedule:view permission. Query params: runId (required), view (teacher|group|room, default: teacher), teacherId?, groupId?, roomId?, subjectId?, includeSubstitutions=1?. Returns: CSV file download (UTF-8 with BOM).

ส่งออกตารางสอนเป็นไฟล์ iCalendar (.ics) สำหรับ Google Calendar, Apple Calendar, Outlook

RFC 5545 compliant. Each slot exported as a weekly recurring VEVENT. Timezone: Asia/Bangkok. Compatible with any calendar client.

ดึงข้อมูลการเข้าสอนทั้งหมดในวันที่ระบุ

Requires: attendance:view permission. Returns: { records: Record<slotId, 'present'|'absent'|'late'> }

บันทึก/อัปเดต/ลบการเข้าสอน (upsert)

Requires: schedule:write permission. Rate limit: 30 req/min/IP. Body: { slotId, teacherId, dateKey, status: 'present'|'absent'|'late'|null }. If status is null → deletes the record. Otherwise upserts.

รายงานภาระสอนครู — แสดงคาบสอนรวมแยกตามวัน (จ.–อา.) ต่อครู

Requires: schedule:view permission. Columns: รหัสครู, ชื่อ-นามสกุล, แผนก, คาบรวม, จ.–อา. Returns: CSV file download (UTF-8 with BOM for Excel).

รายงานการเข้าสอน — สรุปสถานะการเข้าสอนของครูในช่วงวันที่กำหนด

Requires: attendance:view permission. Columns: วันที่, คาบ, รหัสครู, ชื่อ-นามสกุล, วิชา, กลุ่ม, ห้อง, สถานะ. Returns: CSV file download (UTF-8 with BOM for Excel).

ดึงรายการตารางสอนที่เผยแพร่แล้ว (published schedule runs)

Cache: 60s (s-maxage=300, stale-while-revalidate=600). Returns array of published runs.

ดึงรายละเอียดตารางสอนที่เผยแพร่แล้วตาม runId

Cache: 60s. Returns 404 if schedule not found or not published. Full slot details included.

LINE Messaging API Webhook — รับ events จาก LINE OA (follow, message) สำหรับการเชื่อมต่อบัญชี

Signature verification: HMAC-SHA256 with LINE_CHANNEL_SECRET. Account linking: user sends 'เชื่อมต่อ <userId>' to link LINE account to EduSync. Env vars required: LINE_CHANNEL_SECRET, LINE_CHANNEL_ACCESS_TOKEN.

อัปโหลดโลโก้สถาบัน — รองรับ PNG, JPG, SVG, WEBP (สูงสุด 2MB)

Requires: settings:organization permission. Form data field: 'logo'. Returns: { url: '/uploads/logo-xxx.ext' }. File saved to public/uploads/.

บันทึก app event สำหรับ observability และ analytics

Requires: settings:write permission. Rate limit: 30 req/min/IP. Body: { name, path, detail }. Records to AppEvent table via recordAppEvent().