API Reference
Base URL: https://crm.gachapon.one
Machine-readable spec: openapi/gg-crm-public-api.yaml (OpenAPI 3.1)
/api/webhooks/transactionรับ transaction จาก POS ใดก็ได้ — คำนวณ XP และ update Adventurer profile
X-Merchant-Key: <api_key> Idempotency-Key: ORDER-001 // ใช้แทน reference_id ได้
{
"phone": "0812345678",
"amount_thb": 150,
"reference_id": "ORDER-001", // required ถ้าไม่ส่ง Idempotency-Key
"items": ["Americano"] // optional
}{
"success": true,
"duplicate": false,
"transactionId": "uuid",
"adventurerId": "uuid",
"memberCode": "GG-XXXXXX",
"xp": { "global": 1, "merchant": 7, "skipped": false },
"globalLevel": 1,
"totalGlobalXp": 1,
"merchantXp": 7,
"merchantRank": "Newcomer"
}curl -X POST https://crm.gachapon.one/api/webhooks/transaction \
-H "Content-Type: application/json" \
-H "X-Merchant-Key: <your-merchant-key>" \
-H "Idempotency-Key: ORDER-001" \
-d '{"phone":"0812345678","amount_thb":150}'Your X-Merchant-Key is issued privately — never share it publicly.
Retry ด้วย key เดิมจะคืนผลครั้งแรกพร้อม duplicate: true โดยไม่สะสมซ้ำ; key เดิมกับ payload คนละชุดจะได้ 409.
/api/webhooks/transaction/voidยกเลิก transaction — คืน Gold + แต้มร้านที่ได้จาก reference_id (clamp ที่ยอดคงเหลือ, idempotent)
X-Merchant-Key: <api_key>
{ "reference_id": "ORDER-001" }{ "success": true, "reversed": { "gold": 15, "points": 15 } }/api/webhooks/redeemPOS ภายนอกใช้แต้มร้าน และ/หรือ คูปอง (CP-XXXX-XX) ตัดกับบิลของตัวเอง — atomic + idempotent ต่อ reference_id (ต่อร้าน) · endpoint นี้ไม่สะสมแต้ม/XP — ส่งยอดขายจริงผ่าน /api/webhooks/transaction แยกต่างหาก (ยอดสุทธิหลังหักส่วนลด) · ใช้คูปองต้องส่ง bill_amount_thb เสมอ
X-Merchant-Key: <api_key>
{
"phone": "0812345678",
"points": 50, // optional — แต้มที่ใช้
"reference_id": "POS-SALE-001", // unique ต่อครั้ง (idempotency)
"bill_amount_thb": 450.0, // optional — เปิด cap ตามบิล (จำเป็นถ้ามีคูปอง)
"coupon_claim_code": "CP-7Q2M-4F" // optional
}{
"success": true, "duplicate": false, "redemption_id": "uuid",
"points_burned": 50, "burn_value_thb": 50.0,
"coupon": { "applied": true, "discount_thb": 30.0, "free_item_note": null },
"balance": 120
}404 not_member · 422 burn_disabled | insufficient_points | daily_burn_cap | min_bill |
burn_pct_of_bill | no_stack_with_coupon | claim_used | claim_expired | min_spend | ...duplicate: trueคืนค่าของครั้งแรกเสมอ — retry ต้องส่ง input เดิมเป๊ะ ถ้ายอด/แต้มเปลี่ยน ให้ใช้reference_idใหม่/transaction/voidไม่คืนแต้มที่ burn ผ่าน endpoint นี้อัตโนมัติ — ถ้า void บิลที่ใช้แต้มไป ให้ปรับแต้มคืนที่ dashboard (จะรองรับในเฟสถัดไป)
/api/webhooks/coupon/verify?claim_code=CP-XXXX-XXพรีวิวคูปองก่อนคิดเงิน (read-only — การตัดใช้จริงเกิดใน /redeem เท่านั้น) · auth ด้วย X-Merchant-Key
{ "valid": true, "used": false, "expired": false, "expires_at": "...",
"coupon": { "name": "ลด 10%", "discount_type": "PERCENT", "discount_value": 10,
"min_spend_thb": 200, "max_discount_thb": 100, "free_item_note": null },
"member": { "member_code": "GG-ABC123", "display_name": "..." } }/api/webhooks/member/lookup?q=0812ค้นสมาชิกของร้านด้วยเบอร์ (prefix 3+ หลัก) หรือรหัสสมาชิก (GG-XXXXXX) — สูงสุด 10 รายการ เรียงตามมาล่าสุด · เบอร์ถูก mask · rate-limit 120 ครั้ง/นาที/ร้าน
{ "results": [ { "member_code": "GG-ABC123", "phone_masked": "081xxx5678",
"display_name": "สมชาย", "points_balance": 120, "spend_tier": "Gold" } ] }/api/public/store-statusดูสถานะ merchant ทั้งหมด — ไม่ต้อง auth — สำหรับ World Map. status = open / closed / unknown (คำนวณจากเวลาทำการร้าน, เขต Asia/Bangkok)
Invoke-RestMethod http://localhost:3002/api/public/store-status
/api/public/adventurer/:phoneดู profile Adventurer — level, XP, merchant profiles
Invoke-RestMethod http://localhost:3002/api/public/adventurer/0812345678
/api/meยืนยันตัวลูกค้าจาก LINE LIFF idToken แล้วตั้ง session cookie. Dormant (503) จนกว่าจะตั้ง LINE_LOGIN_CHANNEL_ID; devPhone = dev-only bypass (ปิดใน production)
{ "idToken": "<LIFF id token>" } // prod
{ "devPhone": "0812345678" } // dev only{ "adventurerId": "uuid", "phone": "0812345678", "displayName": "..." }