API ya Uhasibu wa Mbali

Ingia kama admin, fungua Mipangilio → 🔑 API ya Uhasibu wa Mbali na bofya "Tengeneza tokeni".

Tokeni ya maandishi wazi inaonyeshwa mara moja tu — inakili mara moja. Seva huhifadhi tu heshi yake ya SHA-256, hivyo tokeni iliyopotea inaweza kubadilishwa tu kwa kuzungusha (jambo linalobatilisha ile ya zamani).

Muundo wa tokeni: bb_<userId>_<secret>. Ituma kwa kila ombi kama Authorization: Bearer <token>.

Mwili wa ombi ni kitu cha JSON chenye sehemu hizi:

• title (string, inahitajika) — jina la muamala
• amount (number, inahitajika) — lazima iwe chanya
• type (string, hiari, chaguo-msingi expense) — moja kati ya expense / income / prepaid_expense / pending_income
• category (string, hiari) — jina la kategoria
• note (string, hiari) — maelezo huru
• created_at (string, hiari) — ISO 8601; chaguo-msingi sasa

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": "..." }

Hurudisha majina ya kategoria ya admin kwa mpangilio wa menyu kunjuzi ya dashibodi. Jibu lina majina tu — hakuna ids, user ids au data ya miamala.

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

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

Hurudisha viambishi awali vya lebo vilivyosasishwa hivi karibuni (alama za #XXX zilizopachikwa kwenye vichwa). Chaguo-msingi 20; tumia ?limit= kubadilisha (kiwango cha juu 100).

Hurudisha safu tupu badala ya hitilafu ikiwa jedwali tag_prefixes bado halipo.

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

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

Hitilafu zote ni JSON: { "error": "ujumbe" }.

• 401 — idhini haipo, tokeni iliyoharibika, iliyobatilishwa au isiyolingana
• 402 — usajili umeisha; uandishi unahitaji kuhuisha
• 405 — mbinu haitumiki (mfano GET kwenye /api/ingest)
• 501 — seva haina SUPABASE_SERVICE_ROLE_KEY
• 500 — hitilafu nyingine ya ndani

Kwa muundo, tokeni inaweza kuandika tu kwenye shirika lake yenyewe — haiwezi kujifanya orgs nyingine wala kusoma data iliyopo:

• user_id daima ni mmiliki wa tokeni; haiwezi kughushiwa
• org_id daima ni org ya mmiliki; uandishi kati ya orgs hauwezekani
• Tokeni hutolewa tu kwa jukumu la admin (manager / staff hupata 403)
• Majibu hayavuji kamwe safu nyingine — { id, created_at } pekee hurudishwa
• Ubatilishaji ni wa papo hapo; zungusha wakati wowote kutoka Mipangilio

Ongeza kitendo cha "Get Contents of URL", weka URL kuwa https://billbook.me/api/ingest, mbinu POST, vichwa Authorization: Bearer bb_... na Content-Type: application/json, na mwili wa ombi kama JSON: {"title":"Kahawa","amount":120,"type":"expense"}. Unganisha title na amount na ingizo la Njia ya mkato au vigeu vya "Uliza Kila Mara".