API پیگیری هزینه در ۲۰۲۶: خودکارسازی امن تراکنشها و بودجهها
راهنمای عملی کار با API پیگیری هزینه: تراکنشها، انتقالها، حسابها و بودجهها را درست مدل کنید و بعد، بدون خطر خرابشدن نامحسوس دادهها، اسکریپت یا عامل هوش مصنوعی را به آن وصل کنید.
ممکن است یک API پیگیری هزینه، انتقال $900 به حساب پسانداز را به $900 هزینه تبدیل کند و باز هم پاسخ 200 OK بدهد. درخواست درست اجرا شده؛ حسابداری نه.
دشواری واقعی خودکارسازی امور مالی شخصی همینجاست. فرستادن SQL یا JSON از طریق HTTPS کاری عادی در مهندسی نرمافزار است. بخش دشوار، حفظ معنای حسابها، انتقالها، هزینهها و برنامههای بودجه است؛ همان بخشی که یک خودکارسازیِ ظاهراً درست میتواند بیسروصدا خرابش کند.
یک کلاینت امن فقط به مسیری برای نوشتن داده نیاز ندارد. ترتیب کار هم مهم است: ابتدا قرارداد فعلی سرویس را بخواند، احراز هویت کند، فضای کاری درست را انتخاب کند، ساختار داده را بررسی کند، دادههای موجود را بخواند، برای تغییری دقیق از کاربر تأیید بگیرد، شکل نوشتن را روی نمونهای کوچک بیازماید، کار را در دستههای حسابشده ادامه دهد و در پایان نتیجه را با منبع تطبیق دهد.
در ادامه میبینید این گردشکار را چطور با SQL API محدودشدهٔ Expense Budget Tracker بسازید.
مدل داده تعیین میکند خودکارسازی امن است یا نه
از مرزهای حسابداری شروع کنید، نه از فهرست مسیرهای API.
| مفهوم | معنای آن | خطای رایج در خودکارسازی |
|---|---|---|
| حساب | جایی که پول در آن نگهداری میشود یا بدهی به آن تعلق دارد | ثبت ماندهٔ فعلی بهعنوان تراکنشی تازه |
| ردیف دفتر کل | پولی که واقعاً جابهجا شده است | آمیختن مبالغ برنامهریزیشده با هزینههای واقعی |
| انتقال | جابهجایی پول میان حسابهای خودتان | شمردن وجه خروجی بهعنوان هزینه |
| ردیف بودجه | برنامهٔ یک دسته برای دورهای مشخص | جایگزینکردن برنامه با هزینهٔ واقعی و از بین بردن اختلاف آنها |
| فضای کاری | مرز دادههای یک فرد یا گروه | نوشتن دادهٔ درست در دفاتر مالی اشتباه |
این خطاها بهآسانی از چشم دور میمانند، چون هر ردیف بهتنهایی همچنان میتواند منطقی به نظر برسد. ممکن است پرداخت کارت نام فروشندهای آشنا داشته باشد. مبلغ هر دو سمت انتقال میتواند معتبر باشد. شاید بودجهای که با هزینهٔ واقعی برابر شده، گزارشی مرتب هم بسازد. با این حال، معنای دادهها اشتباه است.
مهمترین تمایز، جدایی واقعیتهای ثبتشده از برنامههاست:
- ردیفهای دفتر کل آنچه را اتفاق افتاده ثبت میکنند.
- ردیفهای بودجه آنچه را قصد داشتهاید یا اکنون برنامهریزی کردهاید ثبت میکنند.
- گزارشها این دو را با هم مقایسه میکنند؛ فرایند واردکردن داده نباید آنها را یکی کند.
قابلیتهای جدول بودجه و ماندهحساب در Expense Budget Tracker بر همین جداسازی تکیه دارند. کلاینت API هم باید آن را حفظ کند.
از قرارداد فعلی سرویس شروع کنید
نقطهٔ شروع عمومی، سند شناسایی Expense Budget Tracker است. این سند روند فعلی احراز هویت را توضیح میدهد، به مشخصات OpenAPI پیوند میدهد و به اسکریپت یا عامل میگوید در مرحلهٔ بعد کدام مسیر را فراخوانی کند.
همین پاسخهای زنده را قرارداد سرویس بدانید. فهرستی ذخیرهشده از رابطهها یا نمونهکدی قدیمی ممکن است منسوخ شود، بیآنکه در نگاه اول مشکوک به نظر برسد.
ترتیب فعلی راهاندازی این است:
GET https://api.expense-budget-tracker.com/v1/را بارگذاری کنید.- ایمیل کاربر را به
bootstrapUrlبازگرداندهشده بفرستید. - کد ۸ رقمی ارسالشده با ایمیل را از کاربر بخواهید و بعد، اقدام تأییدی را که سرویس برگردانده دنبال کنید.
ApiKeyبلندمدت را بیرون از حافظهٔ گفتوگو ذخیره کنید./v1/meرا بارگذاری کنید، فهرست/v1/workspacesرا بگیرید و فضای کاری موردنظر را انتخاب کنید.- پس از احراز هویت،
/v1/schemaرا بارگذاری کنید تا رابطهها، ستونها، عملیات مجاز، محدودیتها و راهنماییهای عامل را که برای این کلید در دسترساند ببینید. - پیش از پیشنهاد هر تغییری، دادهها را از طریق
/v1/sqlبخوانید. - فقط تغییر تأییدشده را اجرا کنید و بعد، دادههای تحتتأثیر را دوباره پرسوجو کنید.
مرجع API جزئیات مسیرها را توضیح میدهد و راهنمای راهاندازی عامل روند ورود با کد ایمیلی را قدمبهقدم نشان میدهد. اگر هرکدام با پاسخ فعلی سند شناسایی یا OpenAPI تفاوت داشت، قرارداد فعلی سرویس را مبنا قرار دهید.
شناسایی سرویس و احراز هویت
سند شناسایی عمومی است:
curl --fail --silent --show-error \
https://api.expense-budget-tracker.com/v1/
پس از تأیید، کلید بازگرداندهشده را در سامانهٔ امن مدیریت اسرار یا یک متغیر محیطی محلی نگه دارید. در مستندات و اسکریپتها از جاینگهداری کاملاً مشخص استفاده کنید؛ کلیدی که واقعی به نظر برسد هیچ مزیتی ندارد.
export EXPENSE_BUDGET_TRACKER_API_KEY="<paste-returned-key-here>"
درخواستهای احرازهویتشده از الگوی کامل مجوزدهی ApiKey استفاده میکنند:
curl --fail --silent --show-error \
-H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
https://api.expense-budget-tracker.com/v1/me
فضای کاری را صریح انتخاب کنید
فضاهای کاری در دسترس صاحب کلید را فهرست کنید، همان فضایی را برگزینید که کاربر واقعاً نام برده و آن را برای این کلید ذخیره کنید:
curl --fail --silent --show-error \
-H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
https://api.expense-budget-tracker.com/v1/workspaces
export EXPENSE_BUDGET_TRACKER_WORKSPACE_ID="<workspace-id-from-list>"
curl --fail --silent --show-error \
-X POST \
-H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
"https://api.expense-budget-tracker.com/v1/workspaces/$EXPENSE_BUDGET_TRACKER_WORKSPACE_ID/select"
پس از این انتخاب، لازم نیست درخواستهای بعدی /v1/sql هدر X-Workspace-Id را بفرستند. این هدر همچنان برای تغییر موقت فضای کاری در یک درخواست در دسترس است. آن را یک تغییر عمدی بدانید، نه جزئیاتی که برای راحتی در تابعی کمکی پنهان شود. سادهترین راه برای قراردادن دادهٔ درست در جای اشتباه، نامرئیکردن فضای کاری فعال است.
ساختار دادهٔ در دسترس این کلید را بررسی کنید
سند OpenAPI شیوهٔ تبادل درخواست و پاسخ را توضیح میدهد. /v1/schema احرازهویتشده هم مشخص میکند فضای کاری انتخابشده به کدام بخشهای پایگاه داده دسترسی دارد.
curl --fail --silent --show-error \
-H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
https://api.expense-budget-tracker.com/v1/schema
پیش از تولید SQL، پاسخ را کامل بخوانید. این موارد را بررسی کنید:
- نام دقیق رابطهها و ستونها
- عملیات مجاز برای هر رابطه
- فیلدهای الزامی و محدودیتها
- راهنماییهای مربوط به انتقالها و دیگر قواعد معنایی نوشتن داده
- محدودیتهای نحو و توابع SQL
پاسخ فعلی سند شناسایی، ledger_entries، budget_lines، workspace_settings و account_metadata را طبق قواعد تأیید موجود، قابلنوشتن معرفی میکند. نمای مشتقشدهٔ accounts و رابطههای ارزی تحت مالکیت worker فقط خواندنیاند. این تفاوت مهم است: تغییر ماندهٔ حساب یعنی تغییر دادهٔ درست در دفتر کل، نه بهروزرسانی نمای مشتقشدهٔ حسابها.
یک INSERT را از مقالهای در وبلاگ کپی نکنید و معتبربودن ستونهایش را بدیهی ندانید. بررسی ساختار داده بسیار کمهزینهتر از تعمیر دادههای واردشدهای است که ظاهری قانعکننده اما معنایی نادرست دارند.
پیش از نوشتن، زمینهٔ کافی را بخوانید
یک گردشکار امن برای API مدیریت مالی شخصی با این سؤال شروع میشود: اکنون چه چیزهایی در این فضای کاری درستاند؟
پیش از واردکردن یا ویرایش داده، مطمئن شوید که:
- حساب مقصد در فضای کاری انتخابشده وجود دارد
- ارز آن با دادهٔ منبع یکسان است
- میتوان دستهبندیهای موجود را با همان معنای قبلی دوباره به کار برد
- بازهٔ زمانی مقصد از قبل همان جابهجاییها را در خود ندارد
- دورهٔ بودجه یک برنامه است، نه رکوردی در دفتر کل
- ماندهٔ فعلی، نقطهای برای تطبیق نتیجه در اختیارتان میگذارد
پرسوجوهای دقیق به ساختار فعلی بستگی دارند. برای یک بررسی سادهٔ اتصال، ابتدا نام رابطه را در /v1/schema تأیید کنید و بعد نمای مشتقشدهٔ حسابها را بخوانید:
curl --fail --silent --show-error \
-X POST \
-H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
-H "Content-Type: application/json" \
https://api.expense-budget-tracker.com/v1/sql \
-d '{"sql":"SELECT * FROM accounts LIMIT 10"}'
پاسخ فعلی آرایهای به نام statements دارد که برای هر دستور، فیلدهای rowCount، returnedRowCount، totalRowCount و truncated را برمیگرداند. آنها را بررسی کنید. اینکه توانستهاید JSON را تجزیه کنید، ثابت نمیکند همهٔ نتایج را دریافت کردهاید.
انتقالها را در مجموع هزینهها نیاورید
فرض کنید $900 از حساب جاری به حساب پسانداز منتقل میشود. پول از یک حساب خارج شده و به حساب دیگری رسیده، اما خانوار $900 خرج نکرده است.
یک واردکنندهٔ ضعیف ابتدا برداشت را میبیند و آن را بهعنوان هزینهای در دستهٔ پسانداز ثبت میکند. واردکنندهای دیگر، برداشت و واریز را دو تراکنش نامرتبط میداند؛ در نتیجه گردش حساب را بیش از واقع نشان میدهد و تطبیق بعدی را به هم میزند. یک کلاینت مفید برای API تراکنشهای مالی، پیش از نوشتن داده انتقال را تشخیص میدهد و از ساختار پیوندخوردهای استفاده میکند که ساختار فعلی سرویس تعریف کرده است.
انتقال میان دو ارز هم به همین دقت نیاز دارد. مبلغ و ارزی را که در هر سمت حساب ثبت شده حفظ کنید. یک مبلغ تبدیلشدهٔ ساختگی نسازید که هیچکدام از حسابها آن را گزارش نکردهاند.
پرداخت کارت اعتباری دام آشنای دیگری است. خریدهای ثبتشده روی کارت هزینهاند؛ پرداخت صورتحساب کارت، پول را میان دو حساب جابهجا میکند. اگر هر دو را هزینه بشمارید، یک خرج را دو بار ثبت کردهاید، هرچند گزارش نهایی مرتب به نظر برسد.
به همین دلیل، یک API برای مدیریت هزینه باید معنای ردیفهای دفتر کل را بفهمد. دستهبندی زمانی معنا دارد که کلاینت از قبل فهمیده باشد پول چطور جابهجا شده است.
برنامههای بودجه را از واقعیتهای دفتر کل جدا نگه دارید
یک API بودجهبندی نباید مثل مخزن دوم تراکنشها رفتار کند.
فرض کنید برنامهٔ خرید خواربار در ماه اوت $500 است، اما خریدهای واقعی به $620 میرسند. نتیجهٔ مفید، اختلاف $120 میان برنامه و واقعیت است. اگر خودکارسازی هنگام واردکردن تراکنشها، برنامهٔ اوت را به $620 تغییر دهد، تصمیم اولیه را پاک کرده و گزارش را کمفایدهتر ساخته است.
البته دلایل معتبری برای تغییر بودجه وجود دارد: بازبینی برنامهٔ سپتامبر پس از بررسی اوت، کپیکردن برنامهای تکرارشونده برای ماه آینده یا تغییر یک دسته پس از تغییر درآمد. اینها تصمیمهای برنامهریزیاند؛ آنها را جداگانه ارائه کنید و برایشان جداگانه تأیید بگیرید.
گردشکار درست، برنامهها و ارقام واقعی را میخواند، اختلاف را حساب میکند و تغییری برای بودجهٔ آینده پیشنهاد میدهد. واردکردن تراکنش نباید در کنار کار اصلی و بدون درخواست کاربر، برنامهٔ بودجه را تغییر دهد.
تأیید را پیش از نخستین تغییر داده بگیرید
پیش از اینکه از کاربر برای نوشتن داده تأیید بخواهید، مجموعهتغییری نشان دهید که واقعاً بتواند آن را ارزیابی کند:
- فضای کاری و حساب انتخابشده
- رابطه و بازهٔ زمانی تحتتأثیر
- تعداد موردانتظار ردیفهای منبع و دفتر کل، همراه با مجموع مبالغ
- نحوهٔ رسیدگی به موارد تکراری و انتقالها
- تغییرات بودجه، در صورت وجود، جدا از تغییرات تراکنشها
- پرسوجوهایی که نتیجه را تأیید میکنند
«امور مالی من را مرتب کن» تأیید معناداری نیست. «این ۶۴ ردیف را برای بازهٔ ۱ تا ۳۱ ژوئیه در حساب جاری با ارز EUR وارد کن، چهار انتقال را جفت کن و بودجه را تغییر نده» بسیار دقیقتر است.
دستورالعمل فعلی سند شناسایی برای هر تغییر داده به تأیید انسان نیاز دارد. وقتی کاربر همان مجموعهتغییر دقیق را تأیید کرد، این تأیید هم آزمون نمونه و هم دستههای پیاپی باقیمانده را پوشش میدهد. فقط زمانی دوباره تأیید بخواهید که درخواست تغییر کند، ابهام تازهای پیش بیاید یا اجرا شکست بخورد.
ابتدا شکل نوشتن را بیازمایید، سپس در دستههای سنجیده ادامه دهید
قرارداد فعلی OpenAPI اجازه میدهد /v1/sql یک یا چند دستور SELECT، WITH، INSERT، UPDATE یا DELETE را که با نقطهویرگول جدا شدهاند دریافت کند. پشتیبانی از چند دستور مفید است، اما دلیل خوبی برای فشردن کل فرایند واردکردن داده در یک درخواست مبهم نیست.
برای یک INSERT طولانی، ابتدا همان شکل SQL را با ۱ تا ۳ ردیف و مقدارهای صریحِ برگرفته از دادههای تأییدشده بفرستید. برای یک UPDATE طولانی، ابتدا فقط یک ردیف تأییدشده را هدف بگیرید. از دادههای واقعی همان مجموعهتغییر استفاده کنید، نه رکوردهای مالی ساختگی که بعداً باید پاک شوند.
این آزمون کوچک فقط به یک سؤال پاسخ میدهد: آیا ستونها، مقادیر صریح و محدودیتهای فعلی، این شکل نوشتن را میپذیرند؟ موفقیت آن ثابت نمیکند که دستهبندیها درستاند یا دفاتر مالی با منبع تطبیق دارند.
اگر آزمون موفق بود، کار تأییدشده را بیدرنگ و در دستههای پیاپیِ حداکثر ۱۰۰ رکورد در هر فراخوانی ابزار ادامه دهید. اگر شکست خورد، تا وقتی دامنهٔ اثر کوچک است SQL را اصلاح کنید. برای ناپدیدکردن خطا، دامنه یا معنای تغییر تأییدشده را عوض نکنید.
قرارداد فعلی SQL محدودشده این قواعد را هم مشخص میکند:
ON CONFLICTپشتیبانی نمیشود- فقط فراخوانی توابع
SUM،COUNT،MIN،MAX،AVGوCOALESCEمجاز است - جستوجوی بدون حساسیت به حروف کوچک و بزرگ باید با
ILIKEانجام شود - فیلتر تاریخ باید بهجای توابع تاریخِ زمان اجرا، از بازهای صریح استفاده کند
- مقدارهای رشتهای با تکنقلقول معمولی نوشته میشوند؛ رشتههای محصور در علامت دلار مسدودند
هر بار که کلاینتی قابلاستفادهٔ مجدد میسازید یا بهروزرسانی میکنید، این قواعد را از OpenAPI و /v1/schema فعلی بخوانید. اینها بخشی از رابط سرویساند، نه جزئیاتی کماهمیت در پیادهسازی.
این قرارداد سازوکاری برای جلوگیری از اجرای تکراری عملیات نوشتن منتشر نکرده است. اگر مهلت درخواست تمام شد یا پاسخش به دستتان نرسید، آن را کورکورانه دوباره اجرا نکنید. ابتدا بازهٔ مقصد را بخوانید و مشخص کنید تغییر قبلی اعمال شده یا نه.
پس از هر تغییر، دفترهای مالی را تطبیق دهید
پاسخ موفق HTTP فقط میگوید سرور درخواست را پذیرفته است. تطبیق مشخص میکند نتیجهٔ مالی درست است یا نه.
| خودکارسازی | ابتدا چه چیزی را بخوانید | بعد چه چیزی را بررسی کنید |
|---|---|---|
| واردکردن صورتحساب | حساب، بازهٔ زمانی، جابهجاییهای موجود و ماندهٔ آغازین | ردیفهای واردشده، موارد تکراری، جفتهای انتقال و ماندهٔ پایانی |
| دستهبندی ردیفها | دستهبندیهای موجود و ردیفهای مقصد | تعداد ردیفهای تغییرکرده و مجموع هر دسته |
| تغییر بودجهٔ آینده | برنامهٔ فعلی و ارقام واقعی اخیر | مقادیر جدید برنامه و جدایی آنها از ارقام واقعی |
| ساخت گزارش هزینه | کل بازهٔ زمانی و سقف تعداد نتایج | مقایسهٔ مجموعها با یک محاسبهٔ تجمیعی دیگر یا مجموع معلومِ منبع |
هنگام واردکردن صورتحساب، ماندهٔ نهایی حساب را با ماندهٔ پایانی صورتحساب مقایسه کنید. اگر برابر نبودند، متوقف شوید. پیش از افزودن ماه بعد، جابهجایی جاافتاده، تکراری یا اشتباه دستهبندیشده را پیدا کنید.
تفاوت تعداد ردیفها هم باید توضیح داشته باشد. فایل منبعی با ۶۴ ردیف لزوماً ۶۴ ردیف دفتر کل تولید نمیکند، چون ممکن است یک انتقال به دو جابهجایی پیوندخورده میان حسابها نیاز داشته باشد. تفاوت میتواند درست باشد؛ تفاوت بیدلیل مشکلساز است.
برای هر دستور بازگرداندهشده از /v1/sql، فرادادهٔ تعداد و ناقصبودن نتیجه را بررسی کنید. سپس دادههای تحتتأثیر را با پرسوجویی جداگانه دوباره بخوانید. پاسخ یک API دادههای مالی فقط یکی از شواهد است؛ دفتر کل، مجموعها و سند منبع باید با هم سازگار باشند.
اسکریپت یا عامل را بر اساس نوع ورودی انتخاب کنید
اسکریپتی با رفتار قطعی برای یک قالب ثابت CSV مناسب است. عامل هوش مصنوعی زمانی کمک میکند که فایلهای PDF، تصویر صفحه، شرح ناهماهنگ نام فروشندگان یا تصمیمهای مربوط به دستهبندی به تفسیر نیاز داشته باشند. هر دو باید همان ترتیب شناسایی، تأیید و تطبیق را دنبال کنند.
Expense Budget Tracker اتصال خودکار به بانک ندارد. شما صورتحساب، فایل خروجی، تصویر صفحه یا دادهٔ منبع دیگری را فراهم میکنید و اسکریپت یا عامل با همان ورودی کار میکند. راهنمای واردکردن صورتحساب بانکی و راهنمای بودجهبندی بدون اتصال بانکی این گردشکار را با جزئیات بیشتری توضیح میدهند.
سند شناسایی برای عاملها اهمیت ویژهای دارد: Claude Code، Codex یا هر ابزار دیگری که بتواند درخواست HTTP بفرستد، میتواند از یک نشانی شروع کند و اقدامهایی را دنبال کند که سرویس برمیگرداند. کاربر همچنان کد ایمیلی را ارائه میکند، نوشتن داده را تأیید میکند و ApiKey را بیرون از حافظهٔ گفتوگو نگه میدارد.
برای راهاندازی در ترمینال، راهنمای پیگیری هزینه با Claude Code را ببینید. برای آشنایی با کل گردشکار، راهنمای جامعتر پیگیری هزینه و بودجهبندی با هوش مصنوعی را بخوانید. توسعهدهندگانی هم که میخواهند کل پشته را خودشان کنترل کنند، میتوانند از راهنمای ردیاب بودجهٔ خودمیزبان استفاده کنند.
چکلیست نخستین خودکارسازی
برای یک کار واقعی و محدود، این ترتیب را دنبال کنید:
- سند شناسایی فعلی و مشخصات OpenAPI را بارگذاری کنید.
- احراز هویت با کد ایمیلی را کامل کنید و
ApiKeyرا بیرون از گفتوگو نگه دارید. - اطلاعات حساب را بارگذاری کنید، فضاهای کاری را فهرست کنید و فضای کاری موردنظر را برگزینید.
- پس از احراز هویت،
/v1/schemaرا همراه با عملیات مجاز و راهنماییها بررسی کنید. - حساب مقصد، بازهٔ زمانی، دستهبندیها و وضعیت بودجه را بخوانید.
- مجموعهتغییری دقیق ارائه کنید و تأیید کاربر را بگیرید.
- آزمون نمونهٔ لازم را برای شکل نوشتن اجرا کنید.
- کار تأییدشده را در دستههای پیاپیِ حداکثر ۱۰۰ رکورد ادامه دهید.
- دادههای تحتتأثیر را دوباره بخوانید و سقف تعداد نتایج را بررسی کنید.
- ماندهها، تعداد ردیفها، انتقالها و مجموع بودجه را با منبع تطبیق دهید.
یک API ثبت هزینه زمانی اعتماد به دست میآورد که معنای حسابداری را حفظ کند و تصمیمگیری مالی را در اختیار صاحب داده نگه دارد. با یک حساب و یک گردشکار شروع کنید. ابتدا بخوانید، برای تغییر دقیق تأیید بگیرید و بعد، دفاتر مالی را دوباره بررسی کنید.
سپس بخش خستهکنندهٔ بعدی را خودکار کنید.