ข้ามไปยังเนื้อหา
walaoraWalaora

เอกสารอ้างอิง API ของ Walaora

เชื่อมต่อระบบ POS ร้านค้าออนไลน์ หรือระบบภายในของคุณ ใช้ JSON ผ่าน HTTPS และหนึ่งคีย์ API ต่อหนึ่งการเชื่อมต่อ

ส่งข้อมูลของลูกค้าเมื่อลูกค้ารับทราบเท่านั้น และตั้งค่า marketingConsent เป็น true เฉพาะเมื่อลูกค้ายินยอมอย่างชัดแจ้งแล้ว

การยืนยันตัวตน

สร้างคีย์ได้ที่ แดชบอร์ด → API และ Webhooks (แพ็กเกจธุรกิจหรือองค์กร) ส่งคีย์ไปกับทุกคำขอ คีย์จะแสดงเพียงครั้งเดียว หากคีย์รั่วไหลให้เพิกถอนทันที ขีดจำกัด: 120 คำขอต่อนาทีต่อคีย์

Authorization: Bearer wl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Endpoints

Base URL: https://walaora.com/api/v1

GET/programs

แสดงรายการโปรแกรมสะสมแต้ม

GET/customers?phone=0551234567&tag=vip

ค้นหาลูกค้า (50 รายการต่อหน้า, ?page=2…) ?tag=vip แสดงลูกค้าที่มีแท็กนั้น ลูกค้าแต่ละคนมีแท็กของตนแนบมาด้วย

POST/customers

ลงทะเบียนลูกค้าเข้าโปรแกรม เนื้อหา: { programId, name, phone, email?, marketingConsent?, locale? } ส่งคืน 201 เมื่อสร้างใหม่ และ 200 หากลงทะเบียนไว้แล้ว

GET/cards/{serial}

ดึงข้อมูลบัตรจากรหัสบนบัตร / QR ของลูกค้า

POST/cards/{serial}/earn

โปรแกรมแสตมป์: { stamps?: 1–10 } โปรแกรมคะแนน: { amount } ในสกุลเงินของพื้นที่ทำงาน ระบุ { branchId } ได้ตามต้องการ บัตรแสตมป์หลายชุด: ส่ง setId ของชุดหนึ่งในบัตร

POST/cards/{serial}/redeem

แลกรางวัลที่พร้อมใช้หนึ่งรายการ หรือส่ง {"rewardId"} เพื่อแลกรางวัลจากแคตตาล็อกที่กำหนดราคาเป็นแสตมป์/คะแนน

POST/cards/{serial}/sell

แพ็กเกจเติมเงิน: ขายแพ็กเกจ จำนวนครั้งจะเพิ่มเข้าบัตร (ชำระเงินที่เคาน์เตอร์ของคุณ) Webhook: package.sold

POST/cards/{serial}/use

แพ็กเกจเติมเงิน: หัก 1 ครั้ง (ปฏิเสธเมื่อหมดหรือหมดอายุ) บัตรพนักงาน: บันทึกสิทธิ์ภายในขีดจำกัดรายวัน Webhooks: package.used, perk.used

GET/coupons/{code}

ตรวจสอบคูปองโดยไม่ใช้งาน: ข้อเสนอของคูปอง ใช้ได้หรือไม่ และหากใช้ไม่ได้ เพราะเหตุใด (ใช้แล้ว หมดอายุ หรือหยุดชั่วคราว)

POST/coupons/{code}/redeem

ใช้คูปองหนึ่งครั้ง ระบุ { amount } (ยอดขาย ในสกุลเงินของพื้นที่ทำงาน) และ { branchId } ได้ตามต้องการ ส่งคืน 409 เมื่อใช้ไปแล้วหรือข้อเสนอสิ้นสุดแล้ว Webhook: coupon.redeemed

GET/coupon-offers

รายการข้อเสนอคูปอง พร้อมมูลค่า วันสิ้นสุด และสร้างโค้ดได้ในตอนนี้หรือไม่ (usable)

POST/coupon-offers/{id}/coupons

สร้างโค้ดของข้อเสนอ { customerId } ให้โค้ด 1 รายการแก่ลูกค้าคนนั้น (แสดงในหน้าบัตรของลูกค้า) หรือ { count: 1–500 } โค้ดที่ไม่ผูกกับลูกค้าสำหรับพิมพ์หรือแชร์ ส่งกลับ 201 พร้อมโค้ด และ 409 เมื่อข้อเสนอหยุดชั่วคราวหรือสิ้นสุดแล้ว

curl -X POST https://walaora.com/api/v1/cards/ABCDE23456/earn \
  -H "Authorization: Bearer wl_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: receipt-10045" \
  -d '{"stamps": 1}'

การส่งซ้ำและ Idempotency

สำหรับคำขอ POST ให้ส่งเฮดเดอร์ Idempotency-Key (สตริงที่ไม่ซ้ำกัน เช่น เลขที่ใบเสร็จของคุณ) หากส่งซ้ำด้วยคีย์เดิมภายใน 24 ชั่วโมง ระบบจะส่งคืนการตอบกลับเดิมแทนการประทับแสตมป์ซ้ำ

ข้อผิดพลาด

ข้อผิดพลาดจะส่งคืนเนื้อหา JSON { error: { code, message } } พร้อมสถานะ HTTP: 401 คีย์ไม่ถูกต้อง · 403 plan_required · 404 ไม่พบข้อมูล · 409 cooldown / no_reward / program_inactive · 422 ข้อมูลไม่ผ่านการตรวจสอบ · 429 เกินขีดจำกัดอัตรา

Webhooks

เพิ่ม endpoint แบบ HTTPS ในแดชบอร์ดและเลือกเหตุการณ์ที่ต้องการ การส่งแต่ละครั้งเป็นคำขอ POST ที่มี JSON { id, type, createdAt, data } และเฮดเดอร์ต่อไปนี้: Walaora-Event, Walaora-Delivery และ Walaora-Signature โปรดตอบกลับด้วย 2xx ภายใน 10 วินาที การส่งที่ล้มเหลวจะถูกส่งซ้ำหลังจาก 1 นาที, 5 นาที, 30 นาที, 2 ชั่วโมง และ 12 ชั่วโมง

เหตุการณ์

การตรวจสอบลายเซ็น (Node.js)

import crypto from "node:crypto";

// rawBody: the exact request body string; header: req.headers["walaora-signature"]
export function verifyWalaora(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // replay window
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}