← Billbook-এ ফিরে যান

রিমোট হিসাবরক্ষণ API

সর্বশেষ হালনাগাদ: ১০ মে ২০২৬

একটি ব্যক্তিগত API টোকেন ব্যবহার করে cURL, iOS শর্টকাট বা অটোমেশন স্ক্রিপ্ট থেকে এন্ট্রি লিখুন। টোকেনটি শুধু লেখার জন্য — এটি লেনদেন যোগ করতে এবং বিভাগ / ট্যাগ তালিকা পড়তে পারে, কিন্তু কোনো লেনদেন ডেটা পড়তে বা মুছতে পারে না।

1. একটি টোকেন নিন

admin হিসেবে সাইন ইন করুন, সেটিংস → 🔑 রিমোট হিসাবরক্ষণ API খুলুন এবং "টোকেন তৈরি করুন" ক্লিক করুন।

প্লেইনটেক্সট টোকেন শুধু একবার দেখানো হয় — অবিলম্বে কপি করুন। সার্ভার শুধু এর SHA-256 হ্যাশ সংরক্ষণ করে, তাই হারানো টোকেন কেবল রোটেট করে (যা পুরোনোটি বাতিল করে) প্রতিস্থাপন করা যায়।

টোকেন ফরম্যাট: bb_<userId>_<secret>। প্রতিটি অনুরোধে Authorization: Bearer <token> হিসেবে পাঠান।

2. POST /api/ingest — একটি লেনদেন যোগ করুন

অনুরোধের body হলো এই ফিল্ডগুলো সহ একটি JSON অবজেক্ট:

  • title (string, আবশ্যক) — লেনদেনের নাম
  • amount (number, আবশ্যক) — অবশ্যই ধনাত্মক হতে হবে
  • type (string, ঐচ্ছিক, ডিফল্ট expense) — expense / income / prepaid_expense / pending_income-এর একটি
  • category (string, ঐচ্ছিক) — বিভাগের নাম
  • note (string, ঐচ্ছিক) — মুক্ত নোট
  • created_at (string, ঐচ্ছিক) — ISO 8601; ডিফল্ট এখন
curl -X POST https://billbook.me/api/ingest \
  -H "Authorization: Bearer bb_<userId>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Coffee","amount":120,"type":"expense","category":"Food"}'

# response: 201
{ "id": "...", "created_at": "..." }

3. GET /api/ingest/categories — বিভাগ তালিকা

admin-এর বিভাগের নামগুলো ড্যাশবোর্ড ড্রপডাউনের ক্রমে ফেরত দেয়। প্রতিক্রিয়ায় শুধু নাম থাকে — কোনো ids, user ids বা লেনদেন ডেটা নয়।

curl https://billbook.me/api/ingest/categories \
  -H "Authorization: Bearer bb_<userId>_<secret>"

# response: 200
{ "categories": ["Food", "Rent", "..."] }

4. GET /api/ingest/tags — সম্প্রতি ব্যবহৃত ট্যাগ

সবচেয়ে সাম্প্রতিক হালনাগাদ করা ট্যাগ উপসর্গগুলো (শিরোনামে এমবেড করা #XXX চিহ্ন) ফেরত দেয়। ডিফল্ট ২০; ওভাররাইড করতে ?limit= পাঠান (সর্বোচ্চ ১০০)।

tag_prefixes টেবিল এখনও না থাকলে ত্রুটির পরিবর্তে একটি খালি অ্যারে ফেরত দেয়।

curl "https://billbook.me/api/ingest/tags?limit=20" \
  -H "Authorization: Bearer bb_<userId>_<secret>"

# response: 200
{ "tags": ["#management-fee", "#travel", "..."] }

5. ত্রুটি কোড

সব ত্রুটি JSON: { "error": "message" }।

  • 401 — অনুমোদন অনুপস্থিত, ত্রুটিপূর্ণ টোকেন, প্রত্যাহৃত বা অমিল
  • 402 — সাবস্ক্রিপশন মেয়াদোত্তীর্ণ; লেখার জন্য নবায়ন প্রয়োজন
  • 405 — পদ্ধতি সমর্থিত নয় (যেমন /api/ingest-এ GET)
  • 501 — সার্ভারে SUPABASE_SERVICE_ROLE_KEY নেই
  • 500 — অন্য অভ্যন্তরীণ ত্রুটি

6. নিরাপত্তা ও সীমা

ডিজাইন অনুযায়ী, টোকেন কেবল নিজের সংস্থায় লিখতে পারে — অন্য orgs-এর ছদ্মবেশ ধরতে বা বিদ্যমান ডেটা পড়তে পারে না:

  • user_id সবসময় টোকেন মালিক; জাল করা যায় না
  • org_id সবসময় মালিকের org; orgs-এর মধ্যে লেখা অসম্ভব
  • টোকেন শুধু admin ভূমিকায় ইস্যু করা হয় (manager / staff 403 পায়)
  • প্রতিক্রিয়া কখনও অন্য সারি ফাঁস করে না — শুধু { id, created_at } ফেরত দেয়
  • প্রত্যাহার তাৎক্ষণিক; সেটিংস থেকে যেকোনো সময় রোটেট করুন

7. iOS শর্টকাট উদাহরণ

একটি "Get Contents of URL" অ্যাকশন যোগ করুন, URL https://billbook.me/api/ingest, পদ্ধতি POST, হেডার Authorization: Bearer bb_... ও Content-Type: application/json, এবং অনুরোধ body JSON হিসেবে: {"title":"কফি","amount":120,"type":"expense"}। title ও amount শর্টকাট ইনপুট বা "প্রতিবার জিজ্ঞাসা করুন" ভেরিয়েবলে সংযুক্ত করুন।

এই নথিটি একটি দ্রুত রেফারেন্স; প্রকৃত আচরণের জন্য backend কোডই সত্যের উৎস।