← Billbook သို့ ပြန်သွားရန်

အဝေးမှ စာရင်းကိုင် API

နောက်ဆုံးအပ်ဒိတ်: ၂၀၂၆ မေ ၁၀

ကိုယ်ပိုင် API token ကိုအသုံးပြု၍ cURL, iOS Shortcuts သို့မဟုတ် အလိုအလျောက်စကရစ်များမှ စာရင်းသွင်းမှုများ ရေးသွင်းပါ။ token သည် ရေးသားရန်သာ ဖြစ်သည် — ၎င်းသည် ငွေသွင်းငွေထုတ်များ ထည့်သွင်းနိုင်ပြီး အမျိုးအစား / tag စာရင်းများ ဖတ်နိုင်သော်လည်း မည်သည့် ငွေသွင်းငွေထုတ် ဒေတာကိုမျှ မဖတ်နိုင် မဖျက်နိုင်ပါ။

1. token ရယူပါ

admin အဖြစ် ဝင်ရောက်ပြီး ဆက်တင်များ → 🔑 အဝေးမှ စာရင်းကိုင် API ကိုဖွင့်ကာ "token ထုတ်ရန်" ကိုနှိပ်ပါ။

စာသားအတိုင်း token ကို တစ်ကြိမ်တည်းသာ ပြသသည် — ချက်ချင်းကူးယူပါ။ ဆာဗာသည် ၎င်း၏ SHA-256 hash ကိုသာ သိမ်းဆည်းသဖြင့် ပျောက်ဆုံးသွားသော token ကို လှည့်ပတ်ခြင်း (အဟောင်းကို ပျက်ပြယ်စေသည်) ဖြင့်သာ အစားထိုးနိုင်သည်။

token ပုံစံ: bb_<userId>_<secret>။ တောင်းဆိုမှုတိုင်းတွင် Authorization: Bearer <token> အဖြစ် ပို့ပါ။

2. POST /api/ingest — ငွေသွင်းငွေထုတ်တစ်ခု ထည့်ရန်

တောင်းဆိုမှု body သည် ဤအကွက်များပါသော JSON object ဖြစ်သည်:

  • 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 ၏ အမျိုးအစားအမည်များကို dashboard dropdown အစီအစဉ်အတိုင်း ပြန်ပေးသည်။ တုံ့ပြန်မှုတွင် အမည်များသာ ပါဝင်သည် — 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 — မကြာသေးမီက သုံးခဲ့သော tag များ

လတ်တလော အပ်ဒိတ်လုပ်ထားသော tag ရှေ့ဆက်များ (ခေါင်းစဉ်များတွင် ထည့်သွင်းထားသော #XXX အမှတ်အသားများ) ကို ပြန်ပေးသည်။ မူရင်း ၂၀; ကျော်လွှားရန် ?limit= ပို့ပါ (အများဆုံး ၁၀၀)။

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 — ခွင့်ပြုချက် မရှိ၊ token ပုံစံ မှားယွင်း၊ ရုပ်သိမ်းပြီး သို့မဟုတ် မကိုက်ညီ
  • 402 — subscription သက်တမ်းကုန်; ရေးသားရန် သက်တမ်းတိုးရန် လိုအပ်
  • 405 — method မပံ့ပိုး (ဥပမာ /api/ingest တွင် GET)
  • 501 — ဆာဗာတွင် SUPABASE_SERVICE_ROLE_KEY မရှိ
  • 500 — အခြား အတွင်းပိုင်း အမှား

6. လုံခြုံရေးနှင့် ကန့်သတ်ချက်များ

ဒီဇိုင်းအရ token သည် ၎င်း၏ ကိုယ်ပိုင်အဖွဲ့အစည်းသို့သာ ရေးသားနိုင်သည် — အခြား orgs အဖြစ် အယောင်ဆောင်ခြင်း သို့မဟုတ် ရှိပြီးသား ဒေတာ ဖတ်ခြင်း မပြုနိုင်ပါ:

  • user_id သည် အမြဲ token ပိုင်ရှင်; အတုလုပ်၍ မရ
  • org_id သည် အမြဲ ပိုင်ရှင်၏ org; orgs အကြား ရေးသားခြင်း မဖြစ်နိုင်
  • token များကို admin အခန်းကဏ္ဍသို့သာ ထုတ်ပေး (manager / staff သည် 403 ရသည်)
  • တုံ့ပြန်မှုများသည် အခြားအတန်းများကို ဘယ်တော့မှ မပေါက်ကြား — { id, created_at } သာ ပြန်ပေးသည်
  • ရုပ်သိမ်းမှုသည် ချက်ချင်း; ဆက်တင်များမှ အချိန်မရွေး လှည့်ပတ်ပါ

7. iOS Shortcut ဥပမာ

"Get Contents of URL" လုပ်ဆောင်ချက်တစ်ခု ထည့်ပါ၊ URL https://billbook.me/api/ingest၊ method POST၊ header များ Authorization: Bearer bb_... နှင့် Content-Type: application/json၊ နှင့် တောင်းဆိုမှု body ကို JSON အဖြစ်: {"title":"ကော်ဖီ","amount":120,"type":"expense"} ဟု သတ်မှတ်ပါ။ title နှင့် amount ကို Shortcut input သို့မဟုတ် "အကြိမ်တိုင်းမေးရန်" variable များနှင့် ချိတ်ဆက်ပါ။

ဤစာရွက်စာတမ်းသည် အမြန်ကိုးကားချက်ဖြစ်သည်; အမှန်တကယ် အပြုအမူအတွက် backend ကုဒ်သည် အမှန်တရား၏ အရင်းအမြစ်ဖြစ်သည်။