মূল কনটেন্টে যান
walaoraWalaora

Walaora API রেফারেন্স

POS, ই-কমার্স স্টোর বা অভ্যন্তরীণ সিস্টেম যুক্ত করুন। HTTPS-এর মাধ্যমে JSON, প্রতিটি ইন্টিগ্রেশনের জন্য একটি API কী।

গ্রাহকের ডেটা শুধু তাঁদের জ্ঞাতসারে পাঠান, আর গ্রাহক স্পষ্টভাবে সম্মতি দিলে তবেই marketingConsent true করুন।

অথেনটিকেশন

ড্যাশবোর্ড → API ও webhooks-এ একটি কী তৈরি করুন (Business বা Enterprise প্ল্যান)। প্রতিটি রিকোয়েস্টে এটি পাঠান। কী শুধু একবার দেখানো হয়; ফাঁস হয়ে গেলে বাতিল করুন। সীমা: প্রতি কী-তে মিনিটে ১২০টি রিকোয়েস্ট।

Authorization: Bearer wl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

এন্ডপয়েন্ট

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

GET/programs

লয়্যালটি প্রোগ্রামের তালিকা।

GET/customers?phone=0551234567&tag=vip

গ্রাহক খুঁজুন (প্রতি পেজে ৫০ জন, ?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 হেডার পাঠান (যেকোনো অনন্য স্ট্রিং, যেমন আপনার রসিদ নম্বর)। ২৪ ঘণ্টার মধ্যে একই কী দিয়ে আবার চেষ্টা করলে দুবার স্ট্যাম্প না দিয়ে আগের রেসপন্সটিই ফেরত আসে।

ত্রুটি

ত্রুটি হলে একটি HTTP স্ট্যাটাসসহ JSON বডি { error: { code, message } } ফেরত আসে: 401 ভুল কী · 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। ১০ সেকেন্ডের মধ্যে 2xx দিয়ে রেসপন্স করুন। ব্যর্থ ডেলিভারি ১ মিনিট, ৫ মিনিট, ৩০ মিনিট, ২ ঘণ্টা ও ১২ ঘণ্টা পর আবার চেষ্টা করা হয়।

ইভেন্ট

সিগনেচার যাচাই (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 ?? ""));
}