← ກັບໄປ Billbook

API ບັນຊີທາງໄກ

ອັບເດດຫຼ້າສຸດ: 10 ພຶດສະພາ 2026

ບັນທຶກລາຍການຈາກ cURL, iOS Shortcuts ຫຼື script ອັດຕະໂນມັດ ໂດຍໃຊ້ token API ສ່ວນຕົວ. token ນີ້ແມ່ນ ສຳລັບຂຽນເທົ່ານັ້ນ — ມັນສາມາດເພີ່ມທຸລະກຳ ແລະ ອ່ານລາຍການໝວດໝູ່ / tag ໄດ້, ແຕ່ບໍ່ສາມາດອ່ານ ຫຼື ລຶບຂໍ້ມູນທຸລະກຳໃດໆໄດ້.

1. ຮັບ token

ເຂົ້າສູ່ລະບົບເປັນ admin, ເປີດ ການຕັ້ງຄ່າ → 🔑 API ບັນຊີທາງໄກ ແລະ ກົດ "ສ້າງ token".

token ແບບຂໍ້ຄວາມທຳມະດາຈະສະແດງ ພຽງຄັ້ງດຽວ — ສຳເນົາມັນທັນທີ. ເຊີບເວີເກັບພຽງ SHA-256 hash ຂອງມັນ, ສະນັ້ນ token ທີ່ສູນຫາຍສາມາດປ່ຽນແທນໄດ້ພຽງໂດຍການໝູນ (ເຊິ່ງເຮັດໃຫ້ອັນເກົ່າໃຊ້ບໍ່ໄດ້).

ຮູບແບບ token: bb_<userId>_<secret>. ສົ່ງມັນໃນທຸກຄຳຮ້ອງເປັນ Authorization: Bearer <token>.

2. POST /api/ingest — ເພີ່ມໜຶ່ງທຸລະກຳ

body ຂອງຄຳຮ້ອງແມ່ນ object JSON ທີ່ມີ field ເຫຼົ່ານີ້:

  • 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 ຕາມລຳດັບ dropdown ຂອງ dashboard. ການຕອບກັບມີພຽງຊື່ເທົ່ານັ້ນ — ບໍ່ມີ 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 ທີ່ໃຊ້ບໍ່ດົນມານີ້

ສົ່ງຄືນ prefix ຂອງ tag ທີ່ອັບເດດຫຼ້າສຸດ (ເຄື່ອງໝາຍ #XXX ທີ່ຝັງໃນຫົວຂໍ້). ຄ່າເລີ່ມຕົ້ນ 20; ໃຊ້ ?limit= ເພື່ອປ່ຽນ (ສູງສຸດ 100).

ສົ່ງຄືນ array ຫວ່າງເປົ່າແທນທີ່ຈະເປັນຂໍ້ຜິດພາດ ຖ້າຕາຕະລາງ 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 — ຂາດການອະນຸຍາດ, ຮູບແບບ token ຜິດ, ຖືກຍົກເລີກ ຫຼື ບໍ່ກົງກັນ
  • 402 — ການສະໝັກໝົດອາຍຸ; ຕ້ອງຕໍ່ອາຍຸເພື່ອຂຽນ
  • 405 — ບໍ່ຮອງຮັບ method (ເຊັ່ນ GET ໃສ່ /api/ingest)
  • 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 ກັບ input ຂອງ Shortcut ຫຼື ຕົວແປ "ຖາມທຸກຄັ້ງ".

ເອກະສານນີ້ເປັນຂໍ້ມູນອ້າງອີງດ່ວນ; ໂຄ້ດ backend ແມ່ນແຫຼ່ງຄວາມຈິງສຳລັບພຶດຕິກຳຕົວຈິງ.