← 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 పట్టిక ఇంకా లేకుంటే ఎర్రర్‌కు బదులుగా ఖాళీ శ్రేణిని తిరిగి ఇస్తుంది.

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 కోడ్ సత్యానికి మూలం.