สัญญาเชื่อมต่อ 1.1 · เว็บไซต์รุ่น 2.6.13

ERP ส่วนกลาง
เชื่อมยอดถึงลูกค้า

PetPOS ส่งผ่าน ERP สาขา / Branch Server ไปยัง ERP ส่วนกลาง ส่วนกลางเป็นผู้เรียก API เว็บไซต์เพื่อบันทึกแสตมป์และพอยท์

เริ่มเชื่อมต่อที่ส่วนกลาง

1. SUPER ADMIN เปิด SaaS → โปรไฟล์และการตั้งค่า → เชื่อมต่อ API · ERP/POS
2. ลงทะเบียน ERP ส่วนกลาง เลือกสาขาและสิทธิ์ แล้วเก็บ API key ไว้ที่บริการ HQ
3. ตั้งกุญแจในระบบจัดการ secret ของ HQ ห้ามตั้งที่ PetPOS หรือเครื่องสาขา
4. ERP เรียก GET status แล้วนำเข้าทะเบียนและเผยแพร่เงื่อนไข

/api/integrations/loyalty/v1/
Authorization: Bearer YOUR_ENROLLED_HQ_KEY
Content-Type: application/json

หากติดตั้งใต้โฟลเดอร์ย่อย ให้เติมชื่อโฟลเดอร์หน้า /api ตาม URL ในหน้าตั้งค่า ใช้ HTTPS ในระบบจริง

เส้นทางข้อมูล

เงื่อนไขจาก ERP

สร้างหรือแก้ผ่าน POST rules ด้วยกุญแจ HQ ที่มี rules:write หน้าตั้งค่าเว็บไซต์แสดงสถานะและ revision แบบอ่านอย่างเดียว ตัวอย่าง:

{
  "externalId": "STAMP-100",
  "commandId": "RULE-STAMP-100-V1",
  "revision": 0,
  "name": "ทุก 100 บาท รับ 1 ดวง",
  "active": true,
  "currency": "stamps",
  "mode": "per_amount",
  "basis": "eligibleAmount",
  "spendEvery": "100.00",
  "reward": 1,
  "branches": ["chaengwattana"]
}

คำนวณต่อบิล ปัดเศษลง ไม่ยกเศษข้ามบิล ใช้ points และ reward เป็นข้อความทศนิยมเพื่อสะสม PTS ได้ ERP ต้องส่ง revision ที่อนุมัติ หากคำนวณเงื่อนไขซับซ้อนที่ HQ แล้ว ใช้ type grant และสิทธิ์ grants:write

ชำระด้วยแสตมป์หรือ PTS

ใช้สามขั้นตอน กันยอด → ยืนยันตัดยอด หรือปล่อยยอด POST quote เป็นเพียงการตรวจ ไม่ได้กันยอด

1. POST reservations — ส่งธุรกรรมทั้งชุดที่จะยืนยัน:

{
  "externalId": "HQ-INTENT-0001",
  "expiresInSeconds": 300,
  "transaction": {
    "externalId": "HQ-INV-0001",
    "type": "sale",
    "customer": { "externalId": "ERP-C0001" },
    "branch": "chaengwattana",
    "amount": "550.00",
    "eligibleAmount": "500.00",
    "cashAmount": "450.00",
    "spend": { "stamps": 2, "points": "10.50" },
    "rules": [{ "externalId": "STAMP-100", "revision": 1 }]
  }
}

ตรวจว่า reservation.status เป็น held ก่อนดำเนินการต่อ บันทึก reservationId ใน ERP ยอดจริงยังไม่ถูกหัก แต่ช่องทางอื่นใช้ยอดที่กันไว้ซ้ำไม่ได้ อายุเริ่มต้น 300 วินาที ระบุได้ 30–900 วินาที และไม่เกินวันหมดอายุของกระเป๋าที่ใช้

2. POST reservations/commit — เมื่อพร้อมยืนยันบิล:

{ "reservationId": "hold_ID_FROM_RESERVATION" }

ยืนยันตามข้อมูลและเงื่อนไขฉบับที่กันไว้ ไม่รับการเปลี่ยนยอดตอน commit บันทึกสมุดยอด ธุรกรรมอ้างอิง และสถานะกันยอดในธุรกรรมฐานข้อมูลเดียว ส่งซ้ำคืนผลเดิม หากยังไม่ทราบผล ห้ามสร้างบิลหรือเลขกันยอดใหม่เพื่อส่งซ้ำ

3. POST reservations/release — ยกเลิกก่อนยืนยัน:

{
  "externalId": "HQ-RELEASE-0001",
  "reservationId": "hold_ID_FROM_RESERVATION",
  "reason": "ยกเลิกบิลหน้าร้าน"
}

รายการหมดอายุคืนยอดพร้อมใช้อัตโนมัติ รายการที่ commit แล้วต้องคืนด้วย refund/void อ้างอิงธุรกรรมเดิม ERP ต้องประสานสถานะเงินจริง บิล และ Loyalty โดยไม่ถือว่าระบบฐานข้อมูลสองแห่ง commit พร้อมกันอัตโนมัติ

รายการรับเข้าและส่งออก

การส่งออกใช้ cursor และ snapshot ตามค่าที่ API คืน ไม่ส่ง webhook ออกเอง จำนวนเงินและ PTS เป็นข้อความทศนิยมไม่เกิน 2 ตำแหน่ง แสตมป์เป็นจำนวนเต็มหน่วยดวง

เครื่องมือสำหรับ HQ

ในชุดมี integrations/erp-hq-client.mjs รองรับ status, quote, record, reserve, commit, release, rules และ customer ตั้ง DDSC_HQ_API_URL และ DDSC_HQ_API_KEY ที่เซิร์ฟเวอร์ส่วนกลาง

ตัวส่ง PetPOS ตรงเข้าเว็บไซต์รุ่นเดิมถูกปิดแล้ว ตัวแปลง PetPOS เป็นเพียงเครื่องมือแปลงข้อมูลให้ ERP ตรวจรับ ไม่ใช่สิทธิ์สร้างรหัสสินค้า เงื่อนไข หรือส่งคำสั่งข้าม ERP

ดาวน์โหลด OpenAPI 3.1

ขอบเขตและสถานะ

จำกัด JSON 64 KiB และ 600 คำขอต่อนาทีต่อกุญแจ ใช้ code และ X-Request-Id ตรวจเหตุขัดข้อง ส่งซ้ำด้วยเลขและข้อมูลเดิม เว็บไซต์รุ่นนี้เพิ่มการบังคับ HQ และกันยอดฝั่งเว็บไซต์ พร้อมสัญญาและตัวเรียก API ฝั่ง HQ ต้องนำไปเชื่อมกับบริการ ERP ส่วนกลางจริงตามแผนโครงการก่อนใช้งานร่วมทุกสาขา