कंटेंट पर जाएँ
walaoraWalaora

Walaora API संदर्भ

POS, ई-कॉमर्स स्टोर या आंतरिक सिस्टम को जोड़ें। HTTPS पर JSON, हर इंटीग्रेशन के लिए एक API key।

ग्राहकों का डेटा सिर्फ़ उनकी जानकारी में भेजें, और marketingConsent को true तभी रखें जब ग्राहक ने साफ़ तौर पर सहमति दी हो।

ऑथेंटिकेशन

डैशबोर्ड → API और Webhooks में एक key बनाएँ (बिज़नेस या एंटरप्राइज़ प्लान)। इसे हर अनुरोध के साथ भेजें। Keys सिर्फ़ एक बार दिखाई जाती हैं; उजागर होने पर उन्हें रद्द करें। सीमा: हर key के लिए प्रति मिनट 120 अनुरोध।

Authorization: Bearer wl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

एंडपॉइंट

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}'

दोबारा प्रयास और आइडेम्पोटेंसी

POST अनुरोधों के लिए Idempotency-Key हेडर भेजें (कोई भी यूनिक स्ट्रिंग, जैसे आपका रसीद नंबर)। 24 घंटे के भीतर उसी key के साथ दोबारा प्रयास करने पर दो बार स्टैम्प लगाने के बजाय मूल रिस्पॉन्स लौटता है।

त्रुटियाँ

त्रुटियाँ HTTP स्टेटस के साथ JSON बॉडी { error: { code, message } } लौटाती हैं: 401 गलत key · 403 plan_required · 404 नहीं मिला · 409 cooldown / no_reward / program_inactive · 422 वैलिडेशन · 429 रेट लिमिट।

Webhooks

डैशबोर्ड में एक HTTPS एंडपॉइंट जोड़ें और इवेंट चुनें। हर डिलीवरी JSON { id, type, createdAt, data } के साथ एक POST होती है और इसमें ये हेडर होते हैं: Walaora-Event, Walaora-Delivery और Walaora-Signature। 10 सेकंड के भीतर 2xx से जवाब दें। असफल डिलीवरी 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 ?? ""));
}