← กลับไป Billbook

API บันทึกบัญชีระยะไกล

อัปเดตล่าสุด: 10 พฤษภาคม 2026

บันทึกรายการจาก cURL, iOS Shortcuts หรือสคริปต์อัตโนมัติด้วย API token ส่วนตัว Token นี้เขียนได้อย่างเดียว — สามารถเพิ่มรายการและอ่านรายการหมวดหมู่ / แท็กได้ แต่ไม่สามารถอ่านหรือลบข้อมูลรายการได้

1. ขอ token

ลงชื่อเข้าใช้เป็น admin, เปิด ตั้งค่า → 🔑 API บันทึกบัญชีระยะไกล แล้วกด "สร้าง token"

Token แบบข้อความแสดงเพียงครั้งเดียว — คัดลอกทันที เซิร์ฟเวอร์เก็บเฉพาะ SHA-256 hash หาก token หาย จะแทนได้ด้วยการสร้างใหม่เท่านั้น (ทำให้ token เก่าใช้ไม่ได้)

รูปแบบ token: bb_<userId>_<secret> ส่งในทุกคำขอเป็น Authorization: Bearer <token>

2. POST /api/ingest — เพิ่มรายการหนึ่งรายการ

Body ของคำขอเป็น JSON object ที่มีฟิลด์ต่อไปนี้:

  • title (string, จำเป็น) — ชื่อรายการ
  • amount (number, จำเป็น) — ต้องเป็นค่าบวก
  • type (string, ไม่บังคับ, ค่าเริ่มต้น expense) — expense / income / prepaid_expense / pending_income
  • category (string, ไม่บังคับ) — ชื่อหมวดหมู่
  • note (string, ไม่บังคับ) — บันทึกย่ออิสระ
  • created_at (string, ไม่บังคับ) — ISO 8601; ค่าเริ่มต้นคือเวลาปัจจุบัน
curl -X POST https://billbook.me/api/ingest \
  -H "Authorization: Bearer bb_<userId>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Coffee","amount":120,"type":"expense","category":"Food"}'

# response: 201
{ "id": "...", "created_at": "..." }

3. GET /api/ingest/categories — ดึงรายการหมวดหมู่

คืนชื่อหมวดหมู่ของ admin ตามลำดับเดียวกับเมนูบนแดชบอร์ด ตอบกลับมีเฉพาะชื่อ — ไม่มี id, user id หรือข้อมูลรายการ

curl https://billbook.me/api/ingest/categories \
  -H "Authorization: Bearer bb_<userId>_<secret>"

# response: 200
{ "categories": ["Food", "Rent", "..."] }

4. GET /api/ingest/tags — แท็กที่ใช้ล่าสุด

คืนคำนำหน้าแท็กที่อัปเดตล่าสุด (เครื่องหมาย #XXX ในชื่อรายการ) ค่าเริ่มต้น 20 รายการ ใช้ ?limit= เพื่อปรับ (สูงสุด 100)

คืนอาร์เรย์ว่างแทนข้อผิดพลาด หากตาราง tag_prefixes ยังไม่มี

curl "https://billbook.me/api/ingest/tags?limit=20" \
  -H "Authorization: Bearer bb_<userId>_<secret>"

# response: 200
{ "tags": ["#management-fee", "#travel", "..."] }

5. รหัสข้อผิดพลาด

ข้อผิดพลาดทั้งหมดอยู่ในรูป JSON: { "error": "ข้อความ" }

  • 401 — ไม่มีการอนุญาต, รูปแบบ token ผิด, ถูกเพิกถอนหรือไม่ตรง
  • 402 — สมาชิกหมดอายุ ต้องต่ออายุเพื่อเขียน
  • 405 — ไม่รองรับเมธอด (เช่น GET ที่ /api/ingest)
  • 501 — เซิร์ฟเวอร์ยังไม่ตั้งค่า SUPABASE_SERVICE_ROLE_KEY
  • 500 — ข้อผิดพลาดภายในอื่น ๆ

6. ความปลอดภัยและข้อจำกัด

โดยการออกแบบ token เขียนได้เฉพาะองค์กรของผู้เรียกเอง — ไม่สามารถปลอมเป็นองค์กรอื่นหรืออ่านข้อมูลที่มีอยู่ได้:

  • user_id เป็นเจ้าของ token เสมอ ปลอมแปลงไม่ได้
  • org_id เป็นองค์กรของเจ้าของเสมอ เขียนข้ามองค์กรไม่ได้
  • Token ออกให้บทบาท admin เท่านั้น (manager / staff ได้ 403)
  • การตอบกลับไม่เปิดเผยแถวอื่น คืนเฉพาะ { id, created_at }
  • การเพิกถอนมีผลทันที หมุนเวียนได้ตลอดเวลาจากการตั้งค่า

7. ตัวอย่าง iOS Shortcut

เพิ่มการกระทำ "Get Contents of URL", URL https://billbook.me/api/ingest, เมธอด POST, ส่วนหัว Authorization: Bearer bb_... และ Content-Type: application/json, body เป็น JSON: {"title":"กาแฟ","amount":120,"type":"expense"} เชื่อม title และ amount กับข้อมูลขาเข้าของ Shortcut หรือตัวแปร "ถามทุกครั้ง"

เอกสารนี้เป็นการอ้างอิงอย่างย่อ พฤติกรรมจริงยึดตามโค้ดฝั่ง backend