API Pembukuan Jauh

Log masuk sebagai admin, buka Tetapan → 🔑 API Pembukuan Jauh dan klik "Jana token".

Token teks biasa dipaparkan sekali sahaja — segera salin. Pelayan hanya menyimpan hash SHA-256, jadi token yang hilang hanya boleh diganti dengan putaran (yang membatalkan yang lama).

Format token: bb_<userId>_<secret>. Hantar dalam setiap permintaan sebagai Authorization: Bearer <token>.

Body permintaan ialah objek JSON dengan medan berikut:

• title (string, wajib) — nama transaksi
• amount (number, wajib) — mesti positif
• type (string, pilihan, lalai expense) — salah satu daripada expense / income / prepaid_expense / pending_income
• category (string, pilihan) — nama kategori
• note (string, pilihan) — nota bebas
• created_at (string, pilihan) — ISO 8601; lalai sekarang

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

Mengembalikan nama kategori admin dalam urutan dropdown papan pemuka. Respons hanya mengandungi nama — tiada id, user id atau data transaksi.

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

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

Mengembalikan awalan tag yang baru-baru ini dikemaskini (penanda #XXX yang tertanam dalam tajuk). Lalai 20; gunakan ?limit= untuk menggantikan (maks 100).

Mengembalikan array kosong dan bukan ralat jika jadual tag_prefixes belum wujud.

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

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

Semua ralat adalah JSON: { "error": "mesej" }.

• 401 — kebenaran tiada, format token salah, dibatalkan atau tidak sepadan
• 402 — langganan tamat; pembaharuan diperlukan untuk menulis
• 405 — kaedah tidak disokong (cth. GET pada /api/ingest)
• 501 — pelayan kekurangan SUPABASE_SERVICE_ROLE_KEY
• 500 — ralat dalaman lain

Reka bentuknya, token hanya boleh menulis ke organisasinya sendiri — tidak boleh menyamar sebagai org lain atau membaca data sedia ada:

• user_id sentiasa pemilik token; tidak boleh dipalsukan
• org_id sentiasa org pemilik; penulisan merentas org adalah mustahil
• Token hanya dikeluarkan kepada peranan admin (manager / staff dapat 403)
• Respons tidak pernah membocorkan baris lain — hanya { id, created_at } dikembalikan
• Pembatalan serta-merta; putar bila-bila masa dari Tetapan

Tambah tindakan "Get Contents of URL", URL https://billbook.me/api/ingest, kaedah POST, header Authorization: Bearer bb_... dan Content-Type: application/json, dan body permintaan sebagai JSON: {"title":"Kopi","amount":120,"type":"expense"}. Sambungkan title dan amount ke input Pintasan atau pemboleh ubah "Tanya Setiap Kali".