چالش

یکپارچه‌سازی با سیستم مالیاتی ایران (مودیان / «نسخه ۱ API مالیات») به معنای مواجهه با الزامات سخت‌گیرانه بود: احراز هویت از طریق شناسه مالی، کلیدهای خصوصی، شناسه‌های اقتصادی؛ فرمت‌های پیچیده فاکتور؛ داده‌های بسیار حساس؛ و الزام به ارتباط تنها از IPهای مجاز. بسیاری از توسعه‌دهندگان و شرکت‌ها مجبور بودند کدهای تکراری و مستعد خطا برای کارهایی مانند ارسال فاکتور، بررسی وضعیت یا اعتبارسنجی شناسه‌های اقتصادی مشتریان بنویسند.

راهکار

ما taxapi را ساختیم، یک پکیج npm/TypeScript که این عملیات را پوشش می‌دهد. این پکیج متدهای واضح و تایپ‌شده‌ای برای موارد زیر ارائه می‌کند:

• گرفتن توکن (احراز هویت)

• دریافت اطلاعات سرور (کلیدهای عمومی و غیره)

• ارسال فاکتورها به‌صورت تکی یا گروهی (با منطق تلاش مجدد)

• استعلام وضعیت فاکتور بر اساس UID

• جستجوی کدهای اقتصادی یا شناسه‌های مالی مشتریان

• توابع کمکی مانند تولید شماره سریال فاکتور

همه‌چیز با TypeScript تایپ شده تا تجربه توسعه بهتری ایجاد کند. امنیت نیز در نظر گرفته شده است: این پکیج به کلید خصوصی PEM نیاز دارد، عملیات تنها از IPهای مجاز انجام می‌شود و داده‌های مالی و حساس به‌دقت مدیریت می‌شوند.

پیاده‌سازی و فناوری

• زبان و پلتفرم: Node.js + TypeScript، منتشرشده در npm به‌عنوان taxapi. npm

• معماری: پکیج ماژولار است و اندپوینت‌های خارجی API مالیات را با توابع سطح بالا پوشش می‌دهد، شامل مدیریت توکن، تلاش مجدد و پردازش خطا.

• وابستگی‌ها و توزیع: سبک با حداقل وابستگی. لایسنس MIT. طراحی‌شده فقط برای استفاده در بک‌اند. npm

• تجربه توسعه‌دهنده: شامل تایپ‌ها، مدیریت خطای واضح و ابزارهایی برای ساده‌سازی وظایف تکراری مانند تولید سریال فاکتور. مستندات کامل در README. npm

نتیجه

• یکپارچه‌سازی با API مالیات برای توسعه‌دهندگان بسیار ساده‌تر شد: کد کمتر، خطاهای کمتر.

• کاهش زمان عرضه به بازار برای ابزارهای داخلی یا محصولات مشتری که به قابلیت‌های API مالیات نیاز داشتند.

• افزایش دیده‌شدن متن‌باز و اعتبار (به لطف npm، TypeScript و مستندات خوب).

• امکان استفاده مجدد در پروژه‌های داخلی مانند Side App یا سایر محصولات، چون یک پایه قدرتمند وجود دارد.