Walaora API ریفرنس

POS، ای کامرس اسٹور یا اندرونی سسٹم منسلک کریں۔ HTTPS پر JSON، ہر انٹیگریشن کے لیے ایک API key۔

کسٹمرز کا ڈیٹا صرف ان کے علم میں لا کر بھیجیں، اور marketingConsent کو true صرف اسی وقت کریں جب کسٹمر نے واضح طور پر رضامندی دی ہو۔

تصدیق (Authentication)

ڈیش بورڈ ← API اور Webhooks میں ایک key بنائیں (Business یا Enterprise پلان)۔ اسے ہر درخواست کے ساتھ بھیجیں۔ Keys صرف ایک بار دکھائی جاتی ہیں؛ اگر ظاہر ہو جائیں تو انہیں منسوخ کر دیں۔ حد: ہر key کے لیے فی منٹ 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` پری پیڈ پیکیجز: ایک استعمال کم کرتا ہے (ختم یا میعاد گزرنے پر انکار)۔ ملازم کارڈز: روزانہ حد کے اندر سہولت درج کرتا ہے۔ 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 } اس گاہک کو ایک کوڈ دیتا ہے (یہ اس کے کارڈ پیج پر دکھتا ہے)؛ یا { 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 گھنٹوں کے اندر اسی key کے ساتھ دوبارہ کوشش کرنے پر دو بار اسٹیمپ لگنے کے بجائے اصل جواب واپس ملتا ہے۔

غلطیاں (Errors)

غلطی کی صورت میں HTTP اسٹیٹس کے ساتھ JSON باڈی { error: { code, message } } واپس آتی ہے: 401 غلط key · 403 plan_required · 404 نہیں ملا · 409 cooldown / no_reward / program_inactive · 422 توثیق کی غلطی · 429 حد سے زیادہ درخواستیں۔

Webhooks

ڈیش بورڈ میں ایک HTTPS endpoint شامل کریں اور ایونٹس منتخب کریں۔ ہر ڈیلیوری JSON { id, type, createdAt, data } کے ساتھ ایک POST ہوتی ہے جس میں یہ ہیڈرز ہوتے ہیں: Walaora-Event، Walaora-Delivery اور Walaora-Signature۔ 10 سیکنڈ کے اندر 2xx کے ساتھ جواب دیں۔ ناکام ڈیلیوریز 1 منٹ، 5 منٹ، 30 منٹ، 2 گھنٹے اور 12 گھنٹے بعد دوبارہ بھیجی جاتی ہیں۔

ایونٹس

customer.enrolled
card.earned
reward.unlocked
reward.redeemed
card.adjusted
customer.deleted
feedback.received
package.sold
package.used
perk.used
coupon.redeemed

دستخطوں کی تصدیق (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 ?? ""));
}