SectionOrder integration guide

คู่มือ API อ่าน เพิ่ม และแก้ไข SectionOrder

สำหรับโปรแกรมใหม่ที่ต้องจัดการข้อมูลกลุ่มเรียนใน dbo.SectionOrder ครบทุกคอลัมน์

สถานะ: API อ่านและเขียนเปิดใช้งานสำหรับ API key ที่ได้รับสิทธิ์ section-orders:read หรือ section-orders:write

Endpoints

รายการ API

GET

`/api/v1/section-orders`

อ่านกลุ่มเรียนในปีและภาคเรียนที่ระบุ กรองรหัสวิชาและกลุ่มเรียนเพิ่มเติมได้ คืนครบ 10 คอลัมน์

สิทธิ์ที่ต้องมี: section-orders:read

GET

`/api/v1/section-orders/:year/:term/:courseCode/:section`

อ่านหนึ่งกลุ่มตามคีย์หลัก พร้อม ETag สำหรับใช้เมื่อแก้ข้อมูล

สิทธิ์ที่ต้องมี: section-orders:read

POST

`/api/v1/section-orders`

เพิ่มกลุ่มใหม่ รับค่าครบ 10 คอลัมน์ คีย์หลัก 4 ช่องต้องมีค่า อีก 6 ช่องส่งค่าหรือ null ได้

สิทธิ์ที่ต้องมี: section-orders:write

PUT

`/api/v1/section-orders/:year/:term/:courseCode/:section`

แก้ข้อมูลครบแถวเดิม คีย์หลักใน body ต้องตรงกับ URL และต้องส่ง If-Match จาก GET ล่าสุด

สิทธิ์ที่ต้องมี: section-orders:write

Complete row schema

ฟิลด์ที่อ่านและรับบันทึก

ชื่อ JSON ตรงกับชื่อคอลัมน์จริง รวมการสะกด Couse_no ของระบบเดิม

ฟิลด์	ชนิดข้อมูล	การบันทึก
`YEAR`	`nvarchar(4)`	ต้องมี · คีย์หลัก
`TERM`	`nvarchar(1)`	ต้องมี · คีย์หลัก
`Couse_no`	`nvarchar(10)`	ต้องมี · คีย์หลัก
`Section`	`nvarchar(4)`	ต้องมี · คีย์หลัก
`Total`	`int`	จำนวนเต็มหรือ `null`
`OrderHow`	`int`	จำนวนเต็มหรือ `null`
`SField`	`nvarchar(4)`	ข้อความหรือ `null`
`memo`	`nvarchar(90)`	ข้อความหรือ `null`
`OrderHowNet`	`int`	จำนวนเต็มหรือ `null`
`TeacherID`	`nvarchar(15)`	ข้อความหรือ `null`

API รับค่า Total, OrderHow และ OrderHowNet ตามที่โปรแกรมส่งมา โดยตรวจว่าเป็นจำนวนเต็ม 32 บิตหรือ null ไม่คำนวณหรือเทียบกับจำนวนในตารางอื่น ช่องที่ไม่ส่งจะบันทึกเป็น NULL

Request examples

ตัวอย่างสำหรับโปรแกรมที่จะเชื่อมต่อ

ใช้ค่าแทนข้อมูลจริงและเก็บ API key ฝั่งเซิร์ฟเวอร์ โปรแกรมต้องได้รับ scope สำหรับงานที่จะเรียก

อ่านรายการของภาคเรียน

curl "https://api.tapee.ac.th/api/v1/section-orders?year=2569&term=1" \
  -H "x-api-key: YOUR_API_KEY"

อ่านหนึ่งกลุ่มและ ETag

curl -i "https://api.tapee.ac.th/api/v1/section-orders/2569/1/COURSE_CODE/T1" \
  -H "x-api-key: YOUR_API_KEY"

เพิ่มกลุ่มใหม่

curl -X POST "https://api.tapee.ac.th/api/v1/section-orders" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "YEAR": "2569",
    "TERM": "1",
    "Couse_no": "COURSE_CODE",
    "Section": "T1",
    "Total": 40,
    "OrderHow": 0,
    "SField": null,
    "memo": null,
    "OrderHowNet": 0,
    "TeacherID": "TEACHER_ID"
  }'

แก้แถวเดิม

curl -X PUT "https://api.tapee.ac.th/api/v1/section-orders/2569/1/COURSE_CODE/T1" \
  -H "x-api-key: YOUR_API_KEY" \
  -H 'If-Match: "ETAG_FROM_GET"' \
  -H "Content-Type: application/json" \
  -d '{
    "YEAR": "2569",
    "TERM": "1",
    "Couse_no": "COURSE_CODE",
    "Section": "T1",
    "Total": 45,
    "OrderHow": 0,
    "SField": null,
    "memo": "เพิ่มจำนวนรับ",
    "OrderHowNet": 0,
    "TeacherID": "TEACHER_ID"
  }'

Responses

วิธีอ่านผลลัพธ์

200 / 201อ่านหรือแก้สำเร็จ / เพิ่มสำเร็จ

400ข้อมูลหรือชนิดฟิลด์ไม่ถูกต้อง

401 / 403ไม่มี API key หรือสิทธิ์/IP ไม่ผ่าน

404ไม่พบกลุ่มเรียนที่ระบุ

409คีย์ของกลุ่มใหม่ซ้ำ

412 / 428ETag ไม่ตรง / ไม่ส่ง If-Match

422ผลอ่านเกิน 500 แถว ให้กรองเพิ่ม

ตัวอย่าง GET รายการเดียวจะคืนข้อมูลครบ 10 คอลัมน์พร้อม ETag ใน header; PUT สำเร็จจะคืนข้อมูลและ ETag ใหม่

HTTP/1.1 200 OK
ETag: "ETAG_FROM_GET"

{
  "requestId": "REQUEST_ID",
  "data": {
    "YEAR": "2569",
    "TERM": "1",
    "Couse_no": "COURSE_CODE",
    "Section": "T1",
    "Total": 40,
    "OrderHow": 0,
    "SField": null,
    "memo": null,
    "OrderHowNet": 0,
    "TeacherID": "TEACHER_ID"
  }
}

Before launch

เงื่อนไขสำคัญ

คีย์หลักPUT ใช้คีย์ใน URL เพื่อหาแถวเดิม คีย์ 4 ช่องใน body ต้องตรงกัน หากต้องเปลี่ยนคีย์ต้องออกแบบขั้นตอนแยก
ป้องกันแก้ทับอ่านแถวล่าสุดก่อนแก้ และส่ง ETag ใน If-Match หากแถวถูกแก้ไปแล้ว API จะไม่เขียนทับ
ตัวนับกลุ่มเรียนโปรแกรมต้นทางเป็นผู้กำหนด Total, OrderHow และ OrderHowNet; API ตรวจชนิดข้อมูลแล้วบันทึกตามคำขอ ไม่ปรับค่าเหล่านี้จาก REGISTER หรือ RegisterNet
สิทธิ์ใช้งานผู้ดูแลจะออก API key แยกให้โปรแกรมใหม่ตามชื่อระบบและ IP ที่อนุมัติ ไม่เปิด DELETE

GET รายการจำกัด 500 แถวต่อคำขอ หากได้ 422 ให้เพิ่มตัวกรอง courseCode หรือ section การเขียนเปิดสำหรับคีย์ที่ได้รับสิทธิ์เท่านั้น และไม่มี DELETE