API Reference

Base URL: https://crm.gachapon.one

Machine-readable spec: openapi/gg-crm-public-api.yaml (OpenAPI 3.1)

POST/api/webhooks/transaction

รับ transaction จาก POS ใดก็ได้ — คำนวณ XP และ update Adventurer profile

Headers
X-Merchant-Key: <api_key>
Idempotency-Key: ORDER-001  // ใช้แทน reference_id ได้
Body
{
  "phone": "0812345678",
  "amount_thb": 150,
  "reference_id": "ORDER-001",  // required ถ้าไม่ส่ง Idempotency-Key
  "items": ["Americano"]        // optional
}
Response
{
  "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"
}
Example
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.

POST/api/webhooks/transaction/void

ยกเลิก transaction — คืน Gold + แต้มร้านที่ได้จาก reference_id (clamp ที่ยอดคงเหลือ, idempotent)

Headers
X-Merchant-Key: <api_key>
Body
{ "reference_id": "ORDER-001" }
Response
{ "success": true, "reversed": { "gold": 15, "points": 15 } }
POST/api/webhooks/redeem

POS ภายนอกใช้แต้มร้าน และ/หรือ คูปอง (CP-XXXX-XX) ตัดกับบิลของตัวเอง — atomic + idempotent ต่อ reference_id (ต่อร้าน) · endpoint นี้ไม่สะสมแต้ม/XP — ส่งยอดขายจริงผ่าน /api/webhooks/transaction แยกต่างหาก (ยอดสุทธิหลังหักส่วนลด) · ใช้คูปองต้องส่ง bill_amount_thb เสมอ

Headers
X-Merchant-Key: <api_key>
Body
{
  "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
}
Response 200
{
  "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
}
Errors
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 (จะรองรับในเฟสถัดไป)
GET/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": "..." } }
GET/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" } ] }
GET/api/public/store-status

ดูสถานะ merchant ทั้งหมด — ไม่ต้อง auth — สำหรับ World Map. status = open / closed / unknown (คำนวณจากเวลาทำการร้าน, เขต Asia/Bangkok)

Invoke-RestMethod http://localhost:3002/api/public/store-status
GET/api/public/adventurer/:phone

ดู profile Adventurer — level, XP, merchant profiles

Invoke-RestMethod http://localhost:3002/api/public/adventurer/0812345678
POST/api/me

ยืนยันตัวลูกค้าจาก LINE LIFF idToken แล้วตั้ง session cookie. Dormant (503) จนกว่าจะตั้ง LINE_LOGIN_CHANNEL_ID; devPhone = dev-only bypass (ปิดใน production)

Body
{ "idToken": "<LIFF id token>" }   // prod
{ "devPhone": "0812345678" }       // dev only
Response (+ Set-Cookie)
{ "adventurerId": "uuid", "phone": "0812345678", "displayName": "..." }