اتصال نرم‌افزار حسابداری به واسط درسان
اطلاعات صورتحساب را از نرم‌افزار مالی خود در قالب JSON به واسط درسان منتقل کنید، نگاشت ستون‌ها را انتخاب کنید و پردازش گروهی را پیگیری کنید. در این راهنما، مسیر اتصال و نکات مهم مستندات API درسان را به زبان روشن می‌خوانید.
ابتدا تفاوت دو مسیر را بدانید
وب‌سرویس واسط درسان دقیقاً چیست؟
وب‌سرویس درسان یک رابط برای ارتباط نرم‌افزار حسابداری، فروشگاهی یا ERP با نرم‌افزار واسط درسان است. این رابط با API مستقیم سازمان امور مالیاتی یکسان نیست. نرم‌افزار شما اطلاعات را به واسط درسان می‌دهد و درسان با توجه به تنظیمات شرکت، نگاشت انتخابی و عملیات درخواستی، آن‌ها را پردازش می‌کند.
پاسخ 202 Accepted در ورود گروهی یعنی درخواست در صف پردازش قرار گرفته است؛ این پاسخ به‌تنهایی تأیید ثبت یا پذیرش صورتحساب در کارپوشه نیست. نتیجه پردازش را از مسیرهای اعلام‌شده در پاسخ یا وب‌هوک اختیاری پیگیری کنید.
این روش برای کسب‌وکارهایی مفید است که حجم صورتحساب بالایی دارند یا می‌خواهند ورود دستی و تکرار اطلاعات را کم کنند. انتخاب وب‌سرویس یک روش اجرایی است و جایگزین بررسی صحت داده‌ها و وضعیت نهایی صورتحساب نمی‌شود.
مسیر عملی اتصال
چهار مرحله اصلی در API واسط درسان
ورود و دریافت توکن
POST /loginبا حساب مجاز وارد شوید و access_token دریافت کنید. درخواست‌های بعدی از توکن Bearer استفاده می‌کنند.
انتخاب شرکت
GET /companiesشرکت‌های در دسترس حساب را ببینید و شناسه شرکت موردنظر را برای company_id بردارید.
انتخاب نگاشت ستون‌ها
GET /invoice-mappingsشناسه نگاشت و مقدار is_overall را بررسی کنید تا ساختار ستون‌های ورودی با الگوی انتخابی هماهنگ باشد.
ورود گروهی صورتحساب
POST /invoice/import-jsonشناسه شرکت، شناسه نگاشت و ماتریس rows را ارسال کنید؛ در صورت نیاز، ذخیره و ارسال را انتخاب کنید.
نشانی پایه در مستندات ارائه‌شده: https://tax.thdorsan.com/api. جزئیات فنی و اعتبارسنجی هر فیلد باید با نسخه جاری مستندات API کنترل شود.
انتخاب الگوی ورودی
نگاشت عادی یا نگاشت کلی؟
خروجی GET /invoice-mappings مشخص می‌کند هر نگاشت برای چه نوع ورودی است. شناسه همان نگاشت در درخواست ورود گروهی با نام invoice_mapping ارسال می‌شود.
نگاشت عادی
طرف حساب و کالا باید از قبل در شرکت ثبت شده باشند. داده‌های صورتحساب با ترتیب ستون‌های همین نگاشت فرستاده می‌شوند.
دریافت فایل نمونه عادی ←نگاشت کلی
اطلاعات تعریف طرف حساب و کالا هم در ورودی قرار می‌گیرد. مطابق مستندات، کد موجود به‌روزرسانی و کد جدید ساخته می‌شود.
دریافت فایل نمونه کلی ←مقدار is_overall را داخل ردیف‌های داده نفرستید؛ فقط شناسه نگاشت انتخابی را در invoice_mapping قرار دهید.
ورود داده با JSON
درخواست ورود گروهی چه اجزایی دارد؟
company_idشناسه شرکت متعلق به کاربر احراز هویت‌شده؛ الزامی.
invoice_mappingشناسه نگاشت دریافت‌شده از فهرست نگاشت‌ها؛ الزامی.
rowsماتریس داده؛ ردیف اول عنوان ستون‌ها و ردیف‌های بعدی صورتحساب‌ها؛ الزامی.
submit_actionsave برای ذخیره و save_send برای ذخیره و ارسال؛ مقدار پیش‌فرض save است.
webhook_urlنشانی HTTPS عمومی برای دریافت نتیجه پردازش پس‌زمینه؛ اختیاری.
تعداد و ترتیب ستون‌ها در همه ردیف‌ها باید با نگاشت انتخاب‌شده یکسان باشد. ردیف اول عنوان ستون‌هاست و پردازش نمی‌شود. برای صورتحساب اصلاحی، ابطالی و برگشت از فروش، شماره مالیاتی مرجع در tax_id لازم است. در نگاشت کلی، داده‌های طرف حساب و شناسه کالا/خدمت را هم طبق الگوی انتخابی آماده کنید.
برای آماده‌سازی اطلاعات پایه، راهنمای شناسه کالا و خدمات درسان و برای آشنایی با محیط محصول، آموزش واسط سامانه مؤدیان را ببینید.
پس از فراخوانی API
پاسخ‌ها و خطاهای مهم
پاسخ شامل شناسه همبستگی و مسیر فایل پاسخ است؛ نتیجه نهایی را پیگیری کنید.
توکن، دسترسی حساب و تعلق شرکت به کاربر را بررسی کنید.
تا پایان پردازش درخواست قبلی برای همان جریان صبر کنید.
جزئیات فیلدهای خطادار را در بخش errors پاسخ بخوانید.
برای امنیت، توکن را در صفحه عمومی یا کد سمت مرورگر قرار ندهید. ارتباط API و دریافت نتیجه را در سمت سرور نرم‌افزار خود پیاده‌سازی کنید.
برای شروع
منابع و ابزارهای مرتبط درسان
اگر سازمان شما نگاشت اختصاصی می‌خواهد، ابتدا نمونه خروجی نرم‌افزار حسابداری، ترتیب ستون‌ها و نوع صورتحساب‌ها را مشخص کنید. پس از آن می‌توان ساختار ورود را با نگاشت مناسب هماهنگ کرد.