← Billbook پر واپس جائیں

ریموٹ بک کیپنگ API

آخری بار اپ ڈیٹ: 10 مئی 2026

ذاتی 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 نشانات) واپس کرتا ہے۔ طے شدہ 20؛ اوور رائیڈ کے لیے ?limit= بھیجیں (زیادہ سے زیادہ 100)۔

اگر tag_prefixes ٹیبل ابھی موجود نہیں ہے تو ایرر کے بجائے ایک خالی array واپس کرتا ہے۔

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 کوڈ سچائی کا ماخذ ہے۔