واجهة برمجة المحاسبة عن بعد

سجّل الدخول كـ admin، وافتح الإعدادات ← 🔑 واجهة برمجة المحاسبة عن بعد وانقر "إنشاء رمز".

يُعرض الرمز النصي مرة واحدة فقط — انسخه فورًا. يحفظ الخادم فقط تجزئة SHA-256، لذا لا يمكن استبدال رمز مفقود إلا بالتدوير (الذي يلغي القديم).

تنسيق الرمز: bb_<userId>_<secret>. أرسله في كل طلب بصيغة Authorization: Bearer <token>.

جسم الطلب هو كائن 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": "..." }

يُرجع أسماء فئات admin بترتيب القائمة المنسدلة في لوحة التحكم. تحتوي الاستجابة على الأسماء فقط — بدون أي معرفات أو بيانات معاملات.

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

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

يُرجع بادئات العلامات الأحدث تحديثًا (علامات #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", "..."] }

جميع الأخطاء بصيغة JSON: { "error": "رسالة" }.

• 401 — تفويض مفقود، تنسيق الرمز خاطئ، ملغى أو غير متطابق
• 402 — انتهت صلاحية الاشتراك؛ التجديد مطلوب للكتابة
• 405 — الطريقة غير مدعومة (مثل GET على /api/ingest)
• 501 — الخادم لا يحتوي على SUPABASE_SERVICE_ROLE_KEY
• 500 — خطأ داخلي آخر

بحكم التصميم، يمكن للرمز الكتابة فقط في مؤسسته الخاصة — لا يمكنه انتحال orgs أخرى أو قراءة البيانات الموجودة:

• user_id هو دائمًا مالك الرمز؛ لا يمكن تزويره
• org_id هو دائمًا org المالك؛ الكتابة عبر المؤسسات مستحيلة
• الرموز تُصدر فقط لدور admin (manager / staff يحصلون على 403)
• الاستجابات لا تكشف صفوفًا أخرى — يُرجع فقط { id, created_at }
• الإلغاء فوري؛ يمكن التدوير في أي وقت من الإعدادات

أضف إجراء "Get Contents of URL"، الرابط https://billbook.me/api/ingest، الطريقة POST، الترويسات Authorization: Bearer bb_... و Content-Type: application/json، وجسم الطلب JSON: {"title":"قهوة","amount":120,"type":"expense"}. اربط title و amount بمدخل الاختصار أو متغيرات "اسأل في كل مرة".