জানাও ডেভেলপার এপিআই

ভূমিকা

নাগরিকদের জানানো সমস্যার তথ্যের মূল ভান্ডার হলো জানাও। টিকিট সিস্টেম, ড্যাশবোর্ড বা ওয়ার্ড অফিসের সফটওয়্যার এখান থেকে পড়ে এবং এখানেই স্ট্যাটাস ফেরত লেখে, আলাদা পুরনো হয়ে যাওয়া কপি রাখে না।

সব এন্ডপয়েন্ট /api/v1 এর অধীনে। উত্তর JSON। OpenAPI বিবরণ পাওয়া যায় /api/v1/openapi.json এ।

দ্রুত শুরু

কী পেলে একটি কলেই সাম্প্রতিক সমস্যাগুলির তালিকা পাবেন। প্লেসহোল্ডারের জায়গায় নিজের কী বসান এবং ক্লায়েন্ট-সাইড কোডে রাখবেন না।

curl -H "Authorization: Bearer jnk_YOUR_KEY" \
  "https://YOUR_JAANAO_HOST/api/v1/issues?status=reported&limit=20"

অথেন্টিকেশন

প্রতিটি অনুরোধে কী-টি বিয়ারার টোকেন হিসেবে পাঠান। কী jnk_ দিয়ে শুরু হয় এবং জানাও অ্যাডমিন অ্যাডমিন এলাকার ইন্টিগ্রেশন অংশে তৈরি করেন। কী নির্দিষ্ট ওয়ার্ড বা বিভাগে সীমিত করা যায়।

Authorization: Bearer jnk_YOUR_KEY

স্কোপ

• issues:readসমস্যা, আপডেট, ওয়ার্ড ও ইভেন্ট ফিড পড়া।
• stats:readসামগ্রিক পরিসংখ্যান পড়া।
• issues:writeনিজের সিস্টেম থেকে সমস্যা তৈরি করা।
• issues:updateকী-এর সীমার মধ্যে সমস্যার স্ট্যাটাস বদলানো।

ত্রুটি

সব ত্রুটির গঠন একই। 401 মানে কী নেই বা ভুল, 403 মানে স্কোপ নেই বা সমস্যাটি কী-এর ওয়ার্ডের বাইরে, 404 মানে পাওয়া যায়নি, 429 মানে খুব দ্রুত অনুরোধ পাঠানো হচ্ছে।

{ "error": { "code": "forbidden", "message": "Key lacks the issues:write scope." } }

এন্ডপয়েন্ট

{
  "data": [ {
      "id": "b7c1f0e2-5c1d-4a39-9d4e-0a7f3e2d1c11",
      "title": "Streetlight not working",
      "description": "Dark stretch near the bus stop.",
      "category": "light",
      "status": "reported",
      "ward_id": "3f2c9a64-7d1e-4b8a-9c05-1e6d2a7b8f90",
      "ward_name": "Ward 64",
      "locality": "Example Road",
      "lat": 22.5726,
      "lng": 88.3639,
      "support_count": 12,
      "created_at": "2026-10-01T08:30:00Z",
      "updated_at": "2026-10-02T10:00:00Z",
      "photo_urls": [],
      "is_demo": false,
      "external_ref": null,
      "merged_into": null
    } ],
  "next_cursor": "opaque-cursor-or-null"
}

{
  "id": "b7c1f0e2-5c1d-4a39-9d4e-0a7f3e2d1c11",
  "title": "Streetlight not working",
  "description": "Dark stretch near the bus stop.",
  "category": "light",
  "status": "reported",
  "ward_id": "3f2c9a64-7d1e-4b8a-9c05-1e6d2a7b8f90",
  "ward_name": "Ward 64",
  "locality": "Example Road",
  "lat": 22.5726,
  "lng": 88.3639,
  "support_count": 12,
  "created_at": "2026-10-01T08:30:00Z",
  "updated_at": "2026-10-02T10:00:00Z",
  "photo_urls": [],
  "is_demo": false,
  "external_ref": null,
  "merged_into": null
}

{
  "data": [
    {
      "id": "42",
      "type": "issue.status_changed",
      "issue_id": "b7c1f0e2-5c1d-4a39-9d4e-0a7f3e2d1c11",
      "ward_id": "3f2c9a64-7d1e-4b8a-9c05-1e6d2a7b8f90",
      "created_at": "2026-10-02T10:00:00.000Z",
      "data": {
        "issue_id": "b7c1f0e2-5c1d-4a39-9d4e-0a7f3e2d1c11",
        "status": "in_progress",
        "previous_status": "reported",
        "ward_id": "3f2c9a64-7d1e-4b8a-9c05-1e6d2a7b8f90"
      }
    }
  ],
  "next_cursor": "ZTo0Mg"
}

curl -X POST https://YOUR_JAANAO_HOST/api/v1/issues \
  -H "Authorization: Bearer jnk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Open drain",
    "description": "Uncovered drain beside the market.",
    "category": "drain",
    "ward_id": "3f2c9a64-7d1e-4b8a-9c05-1e6d2a7b8f90",
    "lat": 22.5726,
    "lng": 88.3639,
    "external_ref": "ticket-4821"
  }'

curl -X PATCH https://YOUR_JAANAO_HOST/api/v1/issues/ISSUE_ID/status \
  -H "Authorization: Bearer jnk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "in_progress", "note": "Crew assigned." }'

পেজিনেশন ও পোলিং

তালিকার এন্ডপয়েন্ট next_cursor ফেরত দেয়। পরের পেজের জন্য সেটি cursor হিসেবে পাঠান; এটি null হলে শেষ। কার্সরকে অস্বচ্ছ স্ট্রিং ধরুন।

ওয়েবহুক ছাড়া সিঙ্কে থাকতে ইভেন্ট ফিড পোল করুন। শেষ প্রক্রিয়া করা cursor জমা রাখুন, তার পরের ইভেন্ট চান, প্রতিটি সামলান, তারপর নতুন cursor সংরক্ষণ করুন। কিছু না এলে পোলের ব্যবধান বাড়ান।

# Poll the change feed, resuming from the last saved cursor
curl -H "Authorization: Bearer jnk_YOUR_KEY" \
  "https://YOUR_JAANAO_HOST/api/v1/events?after=LAST_CURSOR&limit=100"

ওয়েবহুক দ্রুততর, তবে মিস হওয়া ডেলিভারির জন্য পোলিং ভালো বিকল্প।

ওয়েবহুক

অ্যাডমিনের মাধ্যমে একটি এন্ডপয়েন্ট নিবন্ধন করুন, ইভেন্ট JSON POST হিসেবে পাবেন: issue.created, issue.status_changed, issue.update_added ও issue.merged (ডুপ্লিকেট অন্য অভিযোগে মেলানো হয়েছে; data.merged_into হলো মূল অভিযোগ)। রিপোর্টকারী জানালে যে সারানো ইস্যু অসম্পূর্ণ এবং সেটি আবার কাজ চলছে অবস্থায় ফিরলে issue.reopened পাঠানো হয়।

হেডার

• X-Jaanao-Eventইভেন্টের নাম, যেমন issue.status_changed।
• X-Jaanao-Deliveryএই ডেলিভারির অনন্য আইডি। নকল বাদ দিতে ব্যবহার করুন।
• X-Jaanao-Timestampডেলিভারি সাইন করার ইউনিক্স সময় (সেকেন্ড)।
• X-Jaanao-Signatureসময়, একটি বিন্দু এবং মূল বডি জুড়ে এন্ডপয়েন্টের সিক্রেট দিয়ে করা HMAC-SHA256 (হেক্স)।

পার্স করার আগে মূল রিকোয়েস্ট বডির সঙ্গে স্বাক্ষর মেলান। রিপ্লে ঠেকাতে ৫ মিনিটের চেয়ে পুরনো টাইমস্ট্যাম্প বাতিল করুন। ব্যর্থ ডেলিভারি ক্রমবর্ধমান বিরতিতে আবার চেষ্টা হয়, তাই দ্রুত 2xx দিন এবং পরে ইভেন্ট প্রক্রিয়া করুন।

import crypto from "node:crypto";

// rawBody must be the exact request body string, before JSON.parse.
export function verify(rawBody, headers, secret) {
  const timestamp = headers["x-jaanao-timestamp"];
  const signature = headers["x-jaanao-signature"];
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!timestamp || !signature || age > 300) return false; // older than 5 minutes
  const expected = crypto
    .createHmac("sha256", secret)
    .update(timestamp + "." + rawBody)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hashlib, hmac, time

def verify(raw_body: bytes, headers: dict, secret: str) -> bool:
    timestamp = headers.get("X-Jaanao-Timestamp", "")
    signature = headers.get("X-Jaanao-Signature", "")
    try:
        if abs(time.time() - float(timestamp)) > 300:  # older than 5 minutes
            return False
    except ValueError:
        return False
    message = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

স্ট্যাটাসের ধাপ

সমস্যা এই ধাপগুলো পেরিয়ে এগোয়। ইন্টিগ্রেশন seen, in_progress, fixed ও closed দিতে পারে। confirmed শুধু যিনি জানিয়েছেন তিনিই দিতে পারেন।

1. জানানো হয়েছেreported↓→
2. কাজ চলছেin_progress↓→
3. ঠিক হয়েছেfixed↓→
4. নিশ্চিতconfirmedশুধু রিপোর্টার↓→
5. বন্ধclosed

রেট লিমিট

প্রতিটি কী-এর জন্য আলাদা সীমা প্রযোজ্য। সীমা ছাড়ালে এপিআই 429 দেয়, সঙ্গে Retry-After হেডারে কত সেকেন্ড অপেক্ষা করতে হবে তা থাকে। ঘন ঘন পুরো তালিকা না টেনে ইভেন্ট ফিড বা ওয়েবহুক ব্যবহার করুন।

গোপনীয়তার নিশ্চয়তা

রিপোর্ট বেনামি হোক বা না হোক, এপিআই কখনও রিপোর্টারের পরিচয় বা ফোন নম্বর ফেরত দেয় না।

• কোনো উত্তর, ইভেন্ট বা ওয়েবহুকে নাম, ফোন নম্বর বা অ্যাকাউন্ট আইডি থাকে না।
• এপিআই দিয়ে তৈরি সমস্যায় কোনো ব্যক্তিগত তথ্য রাখা হয় না।
• অবস্থান মানে রিপোর্টারের বসানো পিন, ব্যক্তিগত ঠিকানা নয়।
• কী নির্দিষ্ট ওয়ার্ড বা বিভাগে সীমিত করা যায়, ফলে পার্টনার শুধু প্রয়োজনীয় তথ্যই দেখে।

কী চান

কী দেন জানাও অ্যাডমিন। চাইতে হলে জানান আপনি কে, কী বানাচ্ছেন, কোন স্কোপ লাগবে এবং কোন ওয়ার্ড জুড়ে কাজ।

কী চাওয়ার যোগাযোগের তথ্য এখানে প্রকাশ করা হবে। ততদিন যে মাধ্যমে জানাও দলের সঙ্গে কথা বলেন সেটিতেই জানান।