API حسابداری از راه دور

به‌عنوان admin وارد شوید، تنظیمات ← 🔑 API حسابداری از راه دور را باز کنید و روی «تولید توکن» کلیک کنید.

توکن متن ساده فقط یک‌بار نمایش داده می‌شود — فوراً آن را کپی کنید. سرور فقط هش 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 را به ترتیب منوی کشویی داشبورد بازمی‌گرداند. پاسخ فقط شامل نام‌هاست — بدون ids، user ids یا داده تراکنش.

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

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

جدیدترین پیشوندهای برچسب به‌روزشده (نشانگرهای #XXX جاسازی‌شده در عناوین) را بازمی‌گرداند. پیش‌فرض ۲۰؛ برای بازنویسی ?limit= را بفرستید (حداکثر ۱۰۰).

اگر جدول 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": "message" }.

• 401 — نبود مجوز، توکن نادرست، باطل‌شده یا ناهماهنگ
• 402 — اشتراک منقضی شده؛ برای نوشتن تمدید لازم است
• 405 — متد پشتیبانی نمی‌شود (مثلاً GET روی /api/ingest)
• 501 — سرور SUPABASE_SERVICE_ROLE_KEY را ندارد
• 500 — خطای داخلی دیگر

بنا به طراحی، توکن فقط می‌تواند در سازمان خودش بنویسد — نمی‌تواند خود را به جای orgs دیگر جا بزند یا داده‌های موجود را بخواند:

• user_id همیشه مالک توکن است؛ قابل جعل نیست
• org_id همیشه org مالک است؛ نوشتن بین orgs غیرممکن است
• توکن‌ها فقط به نقش admin صادر می‌شوند (manager / staff کد 403 می‌گیرند)
• پاسخ‌ها هرگز ردیف‌های دیگر را افشا نمی‌کنند — فقط { id, created_at } بازگردانده می‌شود
• باطل‌سازی فوری است؛ هر زمان از تنظیمات بچرخانید

یک کنش «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 را به ورودی میان‌بر یا متغیرهای «هر بار بپرس» متصل کنید.