← Billbook पर वापस

रिमोट बहीखाता API

अंतिम अद्यतन: 10 मई 2026

व्यक्तिगत API टोकन का उपयोग करके cURL, iOS शॉर्टकट या ऑटोमेशन स्क्रिप्ट से प्रविष्टियाँ दर्ज करें। टोकन केवल लिखने योग्य है — यह लेन-देन जोड़ सकता है और श्रेणी / टैग सूचियाँ पढ़ सकता है, लेकिन किसी भी लेन-देन डेटा को पढ़ या हटा नहीं सकता।

1. टोकन प्राप्त करें

admin के रूप में साइन इन करें, सेटिंग्स → 🔑 रिमोट बहीखाता API खोलें और "टोकन बनाएँ" पर क्लिक करें।

सादे टेक्स्ट का टोकन केवल एक बार दिखाया जाता है — तुरंत कॉपी करें। सर्वर केवल SHA-256 हैश संग्रहीत करता है, खोए हुए टोकन को केवल पुनः बनाकर (जो पुराने को अमान्य कर देता है) बदला जा सकता है।

टोकन प्रारूप: bb_<userId>_<secret>। हर अनुरोध में Authorization: Bearer <token> के रूप में भेजें।

2. POST /api/ingest — एक लेन-देन डालें

अनुरोध बॉडी इन फ़ील्ड्स वाला 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 के श्रेणी नामों को डैशबोर्ड ड्रॉपडाउन क्रम में लौटाता है। प्रतिक्रिया में केवल नाम होते हैं — कोई id, user id या लेन-देन डेटा नहीं।

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 तालिका अभी मौजूद नहीं है तो त्रुटि के बजाय खाली 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": "संदेश" }।

  • 401 — प्राधिकरण नहीं, टोकन प्रारूप ग़लत, रद्द या मेल नहीं
  • 402 — सदस्यता समाप्त; लिखने के लिए नवीनीकरण आवश्यक
  • 405 — विधि समर्थित नहीं (जैसे /api/ingest पर GET)
  • 501 — सर्वर पर SUPABASE_SERVICE_ROLE_KEY अनुपस्थित
  • 500 — अन्य आंतरिक त्रुटि

6. सुरक्षा और सीमाएँ

डिज़ाइन के अनुसार, टोकन केवल अपने स्वयं के संगठन में लिख सकता है — अन्य orgs का प्रतिरूपण या मौजूदा डेटा पढ़ना संभव नहीं:

  • user_id हमेशा टोकन के स्वामी का होता है; जाली नहीं हो सकता
  • org_id हमेशा स्वामी के org का होता है; org-पार लेखन असंभव
  • टोकन केवल 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, अनुरोध बॉडी JSON: {"title":"कॉफी","amount":120,"type":"expense"}। title और amount को शॉर्टकट इनपुट या "Ask Each Time" चर से जोड़ें।

यह दस्तावेज़ एक त्वरित संदर्भ है; वास्तविक व्यवहार के लिए बैकएंड कोड ही प्रामाणिक है।