แต้มและคูปองจากระบบ POS

ระบบขายที่ไม่ใช่ Tellfox (POS ของร้าน เว็บขายของ หรือระบบประตูของยิม) ทำที่หน้าเคาน์เตอร์ได้เหมือนที่ทีมทำในหน้าลูกค้า สร้างคีย์ที่มีสิทธิ์ customers:write loyalty:write และ packages:write ถ้าจะขายแพ็กเกจ ลองด้วยคีย์ทดสอบก่อน ทุกการเขียนต้องมี Idempotency-Key ที่ไม่ซ้ำตลอดไป สร้างจากการขาย เช่น วันที่และเลขที่การขาย 2026-10-22-1001-stamp เพื่อให้การส่งซ้ำไม่ให้แต้มสองครั้ง เลขที่การขายที่เริ่มใหม่ทุกวันใช้อย่างเดียวไม่ได้

1. หาลูกค้า

ด้วยเบอร์โทรตามที่แคชเชียร์พิมพ์

curl "https://api.tellfox.app/v1/customers?phone=081-234-5678" -H "Authorization: Bearer $KEY"

ไม่พบ ให้เพิ่มลูกค้า ถ้าร้านมีลูกค้าคนนี้อยู่แล้ว (external_id ของคุณ อีเมลเดียวกัน หรือเบอร์เดียวกัน ตามลำดับ) จะได้ลูกค้าคนนั้นกลับมาแทน (200) จึงเรียกได้ทุกครั้ง ลูกค้าที่พบยังใช้ข้อมูลเดิม เพิ่มเบอร์หรืออีเมลได้ด้วย PATCH

curl https://api.tellfox.app/v1/customers -X POST \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Idempotency-Key: new-cust-0812345678" \
  -d '{"name": "Somchai", "phone": "081-234-5678", "external_id": "POS-4471"}'

external_id คือเลขลูกค้าใน POS ของคุณ ครั้งต่อไปหาได้ด้วย ?external_id=POS-4471

2. แสดงบัตร

curl https://api.tellfox.app/v1/customers/cus_…/loyalty -H "Authorization: Bearer $KEY"

ตอบจำนวนแต้ม คะแนน และคูปอง คูปองที่ใช้ได้อยู่ก่อน แต่ละใบมี id สำหรับใช้คูปอง

3. ให้แต้มหรือคะแนนจากการขาย

แต้มสำหรับการมาใช้บริการ

curl https://api.tellfox.app/v1/customers/cus_…/stamps -X POST \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Idempotency-Key: sale-1001-stamp" \
  -d '{"count": 1, "reason": "Sale 1001"}'

บัตรเต็มแล้วจะได้คูปองรางวัลทันทีเหมือนที่ร้าน คะแนนตามยอดที่ใช้จ่าย (เป็นสตางค์ อัตราของร้านคิดเป็นคะแนน)

curl https://api.tellfox.app/v1/customers/cus_…/points -X POST \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Idempotency-Key: sale-1001-points" \
  -d '{"amount": 125000, "reference": "Sale 1001"}'

4. ใช้คูปอง

curl https://api.tellfox.app/v1/customers/cus_…/coupons/gcp_…/use -X POST \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Idempotency-Key: sale-1001-coupon" -d '{}'

คูปองใช้ได้ครั้งเดียว คูปองที่ใช้แล้ว หมดอายุ หรือเป็นของสาขาอื่นจะตอบ 409 ส่วนลดดูจากเงื่อนไขคูปองในบัตร POS ของคุณหักออกจากบิลเอง

5. ขายแพ็กเกจ

curl https://api.tellfox.app/v1/customers/cus_…/packages -X POST \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Idempotency-Key: sale-1002-package" \
  -d '{"package_id": "pkg_…", "payment_method": "card"}'

ราคาเป็นราคาของแพ็กเกจเอง (GET /v1/packages แสดงทั้งหมด) ลูกค้าได้รับข้อความ “ซื้อแพ็กเกจแล้ว” ตามปกติและใช้จองได้ทันที