DormBix · สำหรับนักพัฒนา
ต่อ DormBix ผ่าน MCP & OAuth
DormBix เปิดให้เข้าถึงระบบบริหารหอพักแบบ programmatic ผ่าน Model Context Protocol (MCP) — endpoint เดียว, ยืนยันตัวตนด้วย OAuth 2.1, ทุก tool จำกัดด้วย scope และแยกข้อมูลรายหอ งานที่แก้ข้อมูลเดินผ่าน plan → approve → execute เสมอ หน้านี้อธิบายทุกส่วนตามจริง
ถ้าคุณเป็นเจ้าของหอและแค่อยากต่อแอป AI (Claude/ChatGPT) แบบคลิก ๆ ดูที่ เอกสารการเชื่อมต่อ AI แทน — หน้านี้เป็นเชิงเทคนิค
ภาพรวม
| Base URL | https://www.dormbix.com |
| MCP endpoint | https://www.dormbix.com/api/mcp |
| Protocol | Model Context Protocol over HTTP (JSON-RPC 2.0) |
| Auth | OAuth 2.1 (authorization code + PKCE S256, public client) |
| Isolation | 1 token = 1 หอ · ข้ามหอไม่ได้ |
| ทิศทางหลัก | บริหารหอสำหรับเจ้าของ (อ่าน/วิเคราะห์/สั่งงาน) |
MCP endpoint
DormBix เป็น MCP server แบบ HTTP (JSON-RPC 2.0) — ประกาศเฉพาะ tools (ไม่มี resources/prompts/sampling) method ที่รองรับ: initialize, tools/list, tools/call, ping
Protocol version ที่รองรับ (ใหม่→เก่า):
2025-06-18 2025-03-26 2024-11-05
ต่อจาก Claude Code / Claude Desktop:
claude mcp add --transport http dormbix \ https://www.dormbix.com/api/mcp \ --header "Authorization: Bearer <TOKEN>"
เรียกตรงด้วย initialize:
curl -s https://www.dormbix.com/api/mcp \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize",
"params":{"protocolVersion":"2025-06-18"}}'tools/list คืนเฉพาะ tool ที่ scope ของ token นั้นเรียกได้จริง — เมื่อ DormBix เพิ่ม tool ใหม่ ให้ลบแล้วเพิ่ม connector ใหม่เพื่อดึงรายการล่าสุด
การยืนยันตัวตน (OAuth 2.1)
ยิงไม่มี token → /api/mcp ตอบ 401 พร้อม header WWW-Authenticate ที่ชี้ไป resource metadata client อ่าน metadata แล้วเดิน OAuth ต่อ
Discovery endpoint:
GET /.well-known/oauth-protected-resource (RFC 9728) GET /.well-known/oauth-authorization-server (RFC 8414)
| authorization_endpoint | /api/oauth/authorize |
| token_endpoint | /api/oauth/token |
| registration_endpoint | /api/oauth/register (Dynamic Client Registration) |
| grant_types | authorization_code |
| PKCE | บังคับ code_challenge_method = S256 |
| client auth | none (public client — ไม่มี client_secret) |
| อายุ token | 30 วัน · เพิกถอนได้ทุกเมื่อ |
| ส่ง token | header: Authorization: Bearer <TOKEN> |
กรณีล็อกอิน DormBix คนละเบราว์เซอร์ (เช่นผ่าน LINE) แอป AI จะโชว์รหัส 6 หลัก — เจ้าของหอเปิด /connect บนเครื่องที่ล็อกอินอยู่แล้วกรอกรหัสเพื่ออนุมัติ
ขอบเขตสิทธิ์ (scopes)
ผู้ใช้ติ๊กเลือก scope ตอน consent (ค่าเริ่มต้น = ดูอย่างเดียว) DormBix บังคับ สองชั้น: scope ต้องอยู่ใน token และ role ของบัญชีต้องมีสิทธิ์นั้นจริง — ติ๊ก scope เกินสิทธิ์ role ก็ยังทำไม่ได้
ตารางนี้คือคำศัพท์ scope ทั้งหมด — จะให้สิทธิ์ได้จริงเฉพาะ scope ที่มี tool รองรับแล้ว(บางตัว เช่น write.billing / write.payment / send.line ยังไม่เปิดให้ AI ทำ) รายการสด ๆ ดูที่ /.well-known/agent-card.json หรือ get_capabilities
| scope | ทำอะไรได้ | ชนิด |
|---|---|---|
| read.rooms | ดูห้อง ประเภทห้อง ห้องว่าง | อ่าน |
| read.tenants | ดูผู้เช่าและสัญญา | อ่าน |
| read.finance | ดูบิล รายได้ การชำระ | อ่าน |
| read.meters | ดูเลขมิเตอร์และค่าตั้งต้น | อ่าน |
| read.expense | ดูค่าใช้จ่ายของหอ | อ่าน |
| read.maint | ดูใบแจ้งซ่อม | อ่าน |
| write.rooms | สร้าง/แก้ห้องและประเภทห้อง | เขียน |
| write.settings | แก้ตั้งค่าหอ (เรตค่าน้ำ–ไฟ รอบบิล) | เขียน |
| write.tenants | แก้ข้อมูลผู้เช่า | เขียน |
| write.meter | บันทึกเลขมิเตอร์ | เขียน |
| write.billing | ออกบิล | เขียน |
| write.payment | บันทึกการชำระ | เขียน |
| write.expense | บันทึกค่าใช้จ่าย | เขียน |
| write.maint | จัดการใบแจ้งซ่อม | เขียน |
| send.line | ส่งข้อความ LINE ถึงผู้เช่า | ส่งออก |
รายการ tool
30 tool แบ่งเป็น ดู · วิเคราะห์ · สั่งงาน — ที่มีป้าย ต้องยืนยัน ต้องผ่าน plan→execute (ดูหัวข้อถัดไป) รายการที่ token เรียกได้จริงดูสด ๆ ที่ get_capabilities
ดูข้อมูล (read-only)
| get_capabilities | ความสามารถและสิทธิ์ของ token นี้ (เรียกก่อนเสมอ) |
| get_setup_checklist | สิ่งที่ยังตั้งค่าไม่ครบก่อนออกบิล/ลงประกาศ |
| get_help | คู่มือวิธีใช้งาน DormBix |
| get_dorm_overview | ภาพรวมหอ (ห้อง รายได้ ยอดค้าง) |
| get_dorm_profile | โปรไฟล์หอสำหรับหน้าประกาศสาธารณะ |
| list_rooms | รายการห้องทั้งหมด |
| get_room | รายละเอียดห้องเดียว |
| get_room_types | ประเภทห้องและราคา |
| get_vacant_rooms | ห้องว่าง |
| get_tenant | รายละเอียดผู้เช่า (ไม่รวมข้อมูลอ่อนไหว) |
| search_tenants | ค้นหาผู้เช่า |
| get_tenant_import_template | เทมเพลตนำเข้าผู้เช่า |
| get_invoice | รายละเอียดบิล |
| get_unpaid_invoices | บิลค้างชำระและยอดรวม |
| get_meter_readings | เลขมิเตอร์น้ำ–ไฟ |
| get_meter_baselines | ค่ามิเตอร์ตั้งต้นที่ยังขาด |
| list_maintenance_tickets | ใบแจ้งซ่อมและสถานะ |
วิเคราะห์ (read-only)
| get_monthly_revenue | รายได้รายเดือน |
| get_occupancy_trend | แนวโน้มอัตราการเข้าพัก |
| get_expense_summary | สรุปค่าใช้จ่ายของหอ |
| find_abnormal_meters | มิเตอร์ที่ค่าพุ่งผิดปกติ |
สั่งงาน
| plan_create_room_types | เตรียมแผนสร้างประเภทห้อง ต้องยืนยัน |
| plan_create_rooms | เตรียมแผนสร้างห้อง ต้องยืนยัน |
| plan_update_rooms | เตรียมแผนแก้ห้อง ต้องยืนยันเขียนทับของเดิม |
| plan_update_room_type | เตรียมแผนแก้ประเภทห้อง ต้องยืนยันเขียนทับของเดิม |
| plan_update_dorm_settings | เตรียมแผนแก้ตั้งค่าหอ ต้องยืนยันเขียนทับของเดิม |
| plan_set_meter_baselines | เตรียมแผนตั้งค่ามิเตอร์ตั้งต้น ต้องยืนยันเขียนทับของเดิม |
| execute_plan | ยืนยันลงมือตาม plan_id ต้องยืนยันเขียนทับของเดิม |
| cancel_plan | ยกเลิกแผนที่ยังไม่ execute |
| send_feedback | ส่งฟีดแบ็กถึงทีม DormBix |
plan → approve → execute
tool ชื่อ plan_* ไม่แก้ข้อมูล — มันคืน พรีวิว: plan_id, จำนวนที่กระทบ, ยอดรวม, คำเตือน และเวลาหมดอายุ ต้องเอาสรุปให้ผู้ใช้ยืนยันก่อน แล้วจึงเรียก execute_plan พร้อม plan_id นั้น
คุณสั่ง → plan_* → พรีวิว (plan_id, กระทบกี่รายการ, คำเตือน)
→ ผู้ใช้ยืนยัน → execute_plan(plan_id) → บันทึกจริง + log- แผน หมดอายุได้ — execute หลังหมดอายุจะถูกปฏิเสธ
- execute ครั้งเดียว: ต่อให้ยิงซ้อนกัน มีแค่คำขอเดียวที่ได้ผล (plan_id เป็น idempotency key ในตัว)
- งานเขียนหนัก (เช่นออกบิลทั้งหอ) เข้าคิวแบบ idempotent — ไม่ทำซ้ำแม้ retry
- ยกเลิกก่อนลงมือได้ด้วย cancel_plan
error
แยก 2 แบบ: protocol พัง → คืน JSON-RPC error (LLM แก้ไม่ได้) ส่วน tool ทำงานแล้วไม่สำเร็จ (เช่น input ผิด) → คืน result ที่มี isError: true พร้อมข้อความไทย + hint เพื่อให้ LLM ปรับ input แล้วลองใหม่ได้
| code | ความหมาย |
|---|---|
| -32700 | Parse error — payload ไม่ใช่ JSON ที่ถูกต้อง |
| -32600 | Invalid request — ไม่ใช่ JSON-RPC 2.0 ที่ถูกต้อง |
| -32601 | Method not found — เรียก method ที่ไม่รองรับ |
| -32602 | Invalid params — พารามิเตอร์ไม่ครบ/ผิด (เช่นไม่มีชื่อ tool) |
| -32603 | Internal error — ข้อผิดพลาดฝั่งเซิร์ฟเวอร์ |
rate limit
จำกัดต่อ token ต่อวัน (รีเซ็ตเที่ยงคืน) — เกินแล้วตอบว่าเต็มโควตาพร้อมเวลารีเซ็ต:
| ชนิด | ต่อวัน | ครอบคลุม |
|---|---|---|
| อ่าน | 1000 | การเรียกดู/วิเคราะห์ |
| เขียน | 100 | การสั่งงานที่แก้ข้อมูล |
| ส่งออก | 300 | การส่งข้อความ LINE |
ความปลอดภัย
- 1 token ผูก 1 หอ ทุกคิวรีตั้ง app.dorm_id — ข้ามไปหออื่นไม่ได้
- ไม่ส่งข้อมูลอ่อนไหวออก: เลขบัตรประชาชน รูปบัตร ที่อยู่ วันเกิด เลขบัญชีธนาคาร
- ทุก action ลง audit log ของหอ (ใคร ผ่าน AI ตัวไหน ทำอะไร เมื่อไหร่)
- Kill switch หลายระดับ: ทั้งแพลตฟอร์ม, รายหอ (opt-in ค่าเริ่มต้นปิด), รายโทเคน
- เพิกถอน token ได้ทุกเมื่อ — งานที่แก้ข้อมูลต้องผ่านการยืนยันเสมอ
หมายเหตุ: ตอนนี้ ยังไม่มี webhooks สาธารณะ สำหรับให้ agent รับ event — การเข้าถึงเป็นแบบ request/response ผ่าน MCP เท่านั้น
API ค้นหาสาธารณะ (secondary)
นอกจากฝั่งบริหาร DormBix มี API ค้นหาหอพักสาธารณะสำหรับผู้เช่า — อ่านอย่างเดียว ไม่ต้องยืนยันตัวตน เป็นคนละ surface กับ MCP:
GET /openapi.json (OpenAPI 3.1 spec) GET /api/public/ai/search ค้นหาหอ (จังหวัด/แลนด์มาร์ก/คีย์เวิร์ด) GET /api/public/ai/availability เช็กห้องว่างแบบเรียลไทม์
ติดต่อ
คำถามเชิงเทคนิค: [email protected] · ภาพรวมสำหรับ AI: /ai · คู่มือต่อแอป AI: /docs/ai-connector