Tellfox API

Tellfox API ให้ระบบอื่นอ่านและแก้ไขข้อมูลลูกค้า การจอง แพ็กเกจ และบัตรสะสมแต้มของธุรกิจ เป็นส่วนเสริมรายปีสำหรับแพ็กเกจ Business และ Pro (แพ็กเกจและส่วนเสริม → ส่วนเสริม) หน้านี้เขียนสำหรับนักพัฒนาที่ทำการเชื่อมต่อ

ที่อยู่หลัก: https://api.tellfox.app/v1
รูปแบบ: JSON ทั้งขาเข้าและขาออก UTF-8 เวลาเป็น UTC (ISO 8601) เงินเป็นสตางค์ เป็นจำนวนเต็ม 1 บาท = 100 สตางค์
สเปกสำหรับเครื่อง: OpenAPI 3.1 สร้างจากตารางเดียวกับที่ API ใช้ทำงาน

รายการ endpoint ทั้งหมด

คีย์

เจ้าของร้านสร้างคีย์ที่ ตั้งค่า → API ในหน้าของร้าน แต่ละคีย์มี

ชื่อ เช่น “POS หน้าร้าน” หน้ากิจกรรมแสดงชื่อนี้กับทุกอย่างที่คีย์ทำ
ชื่อระบบ เช่น pos หรือ crm รหัสลูกค้าของระบบคุณ (external_id) เก็บแยกตามชื่อนี้
สิทธิ์ ว่าคีย์ทำอะไรได้ เช่น customers:read customers:write bookings:read packages:write loyalty:write payments:read สิทธิ์เขียนอ่านได้ด้วย ทุกคีย์อ่านข้อมูลร้าน สาขา บริการ และทีมได้
สาขา (ไม่บังคับ) ถ้าเลือก คีย์จะเห็นและแก้ไขได้เฉพาะการจอง บริการ และทีมของสาขานั้น

คีย์ลับแสดงครั้งเดียว Tellfox เก็บไว้เพียงค่าแฮช ส่งคีย์มากับทุกคำขอ

curl https://api.tellfox.app/v1/business \
  -H "Authorization: Bearer tfx_live_…"

GET /v1/business ตอบข้อมูลร้าน สาขา และสิทธิ์ของคีย์ เหมาะเป็นคำขอแรก คีย์ที่ถูกยกเลิกจะตอบ 401 key_revoked ทันที เมื่อปีของส่วนเสริมสิ้นสุด หรือแพ็กเกจไม่ใช่ Business หรือ Pro แล้ว ทุกคีย์จะตอบ 403 addon_required (ไม่มีอะไรถูกลบ ต่ออายุแล้วคีย์เดิมใช้ได้ทันที)

คีย์ทดสอบ

คีย์ทดสอบ (tfx_test_…) ทำงานกับ สำเนาทดสอบ ของร้าน ซึ่งสร้างพร้อมคีย์ทดสอบคีย์แรก มีสาขา เวลาเปิด ทีม บริการ ห้อง แพ็กเกจ แท็ก และบัตรสะสมแต้ม ไม่มีลูกค้าหรือการจอง และไม่มีข้อความใดถูกส่งจากสำเนาทดสอบ (ทั้ง LINE และอีเมล) ลองทุกคำขอที่นี่ก่อน เจ้าของร้านสร้างสำเนาใหม่จากร้านตอนนี้ได้ (สร้างสำเนาใหม่ ที่ ตั้งค่า → API) โค้ดเดียวกันใช้กับคีย์ใช้งานจริงได้ทันที

คำตอบและข้อผิดพลาด

เมื่อสำเร็จจะตอบ {"data": …} (รายการมี "meta": {"next_cursor": …} ด้วย) การสร้างตอบ 201 ข้อผิดพลาดตอบสถานะและ

{ "error": { "code": "invalid", "message": "Not a phone number.", "field": "query.phone", "request_id": "req_…" } }

สถานะ	`code`	ควรทำอย่างไร
400	`bad_request`, `idempotency_key_required`	แก้คำขอ (ส่ง JSON และส่ง Idempotency-Key กับการเขียน)
401	`unauthorized`, `key_revoked`	ตรวจคีย์
403	`addon_required`, `scope_required`, `branch_forbidden`	ส่วนเสริมปิดอยู่ หรือคีย์ไม่มีสิทธิ์
404	`not_found`	ไม่พบในธุรกิจนี้
409	`conflict`, `idempotency_in_progress`	ดูสถานะ หรือลองใหม่อีกสักครู่
422	`invalid`, `plan_limit`, `idempotency_key_reused`	ค่าไม่ถูกต้อง (`field` บอกว่าค่าไหน) หรือแพ็กเกจไม่ให้เพิ่มอีก
429	`rate_limited`, `daily_limit`	รอตามวินาทีใน `Retry-After`
500	`server_error`	ส่งซ้ำด้วย Idempotency-Key เดิม

ทุกคำตอบมี header X-Request-Id แจ้งค่านี้กับฝ่ายช่วยเหลือของ Tellfox เมื่อสอบถามเรื่องคำขอใด

ขีดจำกัด

60 ครั้งต่อนาทีต่อคีย์ เกินแล้วตอบ 429 rate_limited พร้อม Retry-After
10,000 ครั้งต่อวันต่อธุรกิจ (วันตามเวลา UTC คีย์ใช้งานจริงและคีย์ทดสอบนับแยกกัน) เกินแล้วตอบ 429 daily_limit จนถึงวันถัดไป
รายการตอบได้ครั้งละไม่เกิน 200 (ค่าเริ่มต้น 50)

การแบ่งหน้า

รายการตอบทีละหน้าพร้อม meta.next_cursor ส่งค่านี้กลับมาเป็น cursor เพื่อขอหน้าถัดไป ถ้าเป็น null แปลว่าหมดแล้ว

curl "https://api.tellfox.app/v1/customers?limit=100" -H "Authorization: Bearer $KEY"
curl "https://api.tellfox.app/v1/customers?limit=100&cursor=WyIyMDI2…" -H "Authorization: Bearer $KEY"

ซิงก์ข้อมูลกับระบบอื่น

GET /v1/customers และ GET /v1/bookings?updated_since=… ตอบรายการที่เปลี่ยนก่อนสุดก่อน พร้อม updated_at (UTC) วิธีซิงก์

อ่านทุกหน้าหนึ่งรอบโดยส่ง updated_since=1970-01-01T00:00:00Z และเก็บค่า updated_at ที่มากที่สุดไว้ (ถ้าไม่ส่ง updated_since การจองจะเรียงตามเวลาเริ่มตั้งแต่ตอนนี้ไป ซึ่งใช้แสดงปฏิทิน ไม่ใช่ใช้ซิงก์)
ทุกไม่กี่นาที เรียกใหม่โดยส่ง updated_since เป็นเวลา ก่อนค่านั้นหนึ่งนาที อ่านทุกหน้า แล้วเก็บค่า updated_at ที่มากที่สุดใหม่ หนึ่งนาทีนี้ครอบคลุมการเปลี่ยนแปลงที่กำลังบันทึกอยู่ระหว่างที่คุณอ่าน

updated_at ของลูกค้าเปลี่ยนเมื่อมีการเปลี่ยนแปลงใดๆ กับลูกค้า เบอร์โทร อีเมล แท็ก การยินยอม หรือรหัส (จำนวนครั้งที่มาใช้บริการเปลี่ยนตามการจอง) ของการจองเปลี่ยนเมื่อการจองเปลี่ยน คุณอาจเห็นรายการเดิมซ้ำได้ แต่ไม่พลาดรายการใด

ลูกค้าที่ร้านลบข้อมูลตามคำขอ (PDPA) จะถูกทำให้ไม่ระบุตัวตน (ยังอยู่ในรายการ anonymised: true ชื่อและช่องทางติดต่อหายไป) หรือถูกลบเมื่อไม่มีข้อมูลอื่น อ่าน GET /v1/customers/erased ด้วย updated_since เดียวกัน แล้วลบสำเนาของรหัสเหล่านั้นในระบบของคุณ

หาลูกค้าคนเดียวด้วย phone (รูปแบบใดก็ได้ 081-234-5678 จะพบ +66812345678) email หรือ external_id ของระบบคุณ

การเขียนและการส่งซ้ำอย่างปลอดภัย

ทุกการเขียน (POST, PATCH, DELETE) ต้องมี header Idempotency-Key เป็นข้อความยาวไม่เกิน 255 ตัวอักษรที่ไม่ซ้ำตลอดไป เช่น UUID หรือวันที่พร้อมเลขที่การขายของคุณ ส่งคำขอเดิมซ้ำด้วยคีย์เดิมจะไม่ทำซ้ำและได้คำตอบแรกกลับมา (พร้อม header Idempotent-Replayed: true) คีย์นี้เก็บไว้ 24 ชั่วโมง ส่งคีย์เดิมกับคำขอที่ต่างไปจะตอบ 422 idempotency_key_reused

การเขียนผ่านกฎเดียวกับหน้าของร้าน ทั้งขีดจำกัดของแพ็กเกจ คีย์ที่จำกัดสาขา และข้อความที่ลูกค้าได้รับตามปกติ ราคาคิดจากราคาใน Tellfox เสมอ ไม่ใช้ราคาจากคำขอ

สิ่งที่ทำในหน้าของร้าน

การส่งข้อความ LINE และบรอดแคสต์ การยืนยันและคืนเงิน การลบลูกค้า และการเปลี่ยนแพ็กเกจ ทีม เวลาเปิด ราคา และการตั้งค่า ทำในหน้าของร้าน โดยคนเป็นผู้ตัดสินใจ