ساخت اسکریپت پایتون برای اعتبارسنجی و تراز خودکار فایل‌های مالیاتی و حسابداری

چرا حسابداران، تحلیلگران مالی و مدیران مالی باید ساعت‌ها وقت ارزشمند خود را صرف خیره‌شدن به نمایشگر و جستجوی یک خطای ریالی ناچیز در فایل‌های حجیم اکسل و CSV کنند؟ وقتی یک فایل مالیاتی یا اسناد حسابداری صدها هزار سطر داده دارد، پیدا کردن مغایرت میان ستون‌های بدهکار و بستانکار به کابوسی فرساینده تبدیل می‌شود. روش‌های سنتی مثل فیلتر کردن دستی یا فرمول‌نویسی‌های پیچیده در نرم‌افزارهای صفحات گسترده، در مواجهه با حجم انبوه داده‌ها کند می‌شوند و خطای انسانی در آن‌ها به شدت بالاست. پیش از این برای تحلیل‌های گزارش‌گونه، مباحثی مانند آموزش تبدیل داده‌های اکسل به گزارش و ارائه‌ جذاب با هوش مصنوعی Bricks را بررسی کرده بودیم، اما وقتی بحث بر سر صحت ریاضی و بالانس بودن اسناد است، به یک ابزار قطعی، سریع و خودکار نیاز داریم. در این مقاله قصد داریم یک اسکریپت کامل و متن‌باز پایتون بنویسیم که در کسری از ثانیه فایل‌های ساختاریافته مالی را کالبدشکافی کرده، خطاهای تراز را به سبک خطایابی بانکی استخراج کند و گزارش تمیزی تحویل دهد.

مسئله؛ کابوس مغایرت‌گیری در فایل‌های مالی حجیم

در حسابداری دوبل (دوطرفه)، اصل اساسی برابری جمع گردش بدهکار و بستانکار در سطح کلان و ریزسند است. اما هنگام خروجی گرفتن از نرم‌افزارهای مختلف ERP یا سیستم‌های مالیاتی، خطاهای فرمتی، گرد کردن اعداد اعشاری (Floating Point Errors)، یا خطاهای ورود اطلاعات توسط کاربر باعث می‌شود فایل CSV خروجی تراز نباشد. پیدا کردن اینکه دقیقاً کدام ردیف یا سند دچار اختلاف ریالی است، با ابزارهای معمولی وقت زیادی می‌برد. ما به راهکاری نیاز داریم که فایل CSV را بخواند، مقادیر مالی را پاکسازی کند، تساوی بدهکار و بستانکار را در هر سطر (یا هر سند) ارزیابی نماید و ردیف‌های معیوب را به همراه میزان اختلاف درون یک فایل گزارش مجزا ذخیره کند.

نصب کتابخانه‌ها و پیش‌نیازها

برای اجرای این اسکریپت به کتابخانه قدرتمند پردازش داده پایتون یعنی Pandas نیاز داریم. این کتابخانه استاندارد طلایی تحلیل داده در پایتون است. برای نصب آن، محیط خط فرمان سیستم خود را باز کرده و دستور زیر را وارد کنید:

pip install pandas

پس از اتمام نصب، پایتون آماده‌ی پردازش فایل‌های حجیم CSV با میلیون‌ها سطر داده خواهد بود. هیچ کتابخانه تجاری یا پولی دیگری نیاز نیست و تمامی فرآیندها در محیط محلی سیستم شما انجام می‌شود.

کد کامل و یکپارچه‌ی اسکریپت اعتبارسنجی مالی

اسکریپت زیر یک فایل CSV فرضی حاوی ستون‌های کد سند، شرح، بدهکار و بستانکار را خوانده، مغایرت‌ها را محاسبه می‌کند و در نهایت گزارش خطاهای تراز را در یک فایل جدید ذخیره می‌کند. کد را کپی کرده و در فایلی به نام accounting_validator.py ذخیره کنید:

import pandas as pd
import sys

def validate_accounting_csv(file_path, output_report_path, tolerance=0.01):
    """
    بررسی تراز بودن ستون‌های بدهکار و بستانکار در فایل‌های CSV مالیاتی و حسابداری
    """
    print(f"در حال بارگذاری فایل {file_path}...")
    
    try:
        # خواندن فایل CSV با انکودینگ استاندارد
        df = pd.read_csv(file_path, encoding='utf-8')
    except Exception as e:
        print(f"خطا در خواندن فایل: {e}")
        return

    # اطمینان از وجود ستون‌های ضروری در فایل ورودی
    required_columns = ['doc_id', 'description', 'debit', 'credit']
    for col in required_columns:
        if col not in df.columns:
            print(f"خطای ساختاری: ستون ضروری '{col}' در فایل یافت نشد.")
            return

    # پاکسازی داده‌ها و تبدیل به فرمت عددی (جلوگیری از خطای رشته‌های حاوی فاصله یا کاما)
    df['debit'] = pd.to_numeric(df['debit'].astype(str).str.replace(',', ''), errors='coerce').fillna(0.0)
    df['credit'] = pd.to_numeric(df['credit'].astype(str).str.replace(',', ''), errors='coerce').fillna(0.0)

    # محاسبه اختلاف بین بدهکار و بستانکار در هر سطر
    df['difference'] = df['debit'] - df['credit']

    # شناسایی سطرهایی که اختلاف آن‌ها بیشتر از حد آستانه (Tolerance) است
    # استفاده از abs برای پوشش دادن خطاهای منفی و مثبت
    unbalanced_rows = df[abs(df['difference']) > tolerance].copy()

    # گزارش‌دهی اولیه در کنسول
    total_rows = len(df)
    error_rows = len(unbalanced_rows)

    print("-" * 50)
    print(f"تعداد کل سطرهای بررسی‌شده: {total_rows}")
    print(f"تعداد ردیف‌های دارای مغایرت (نامتراز): {error_rows}")
    print("-" * 50)

    if error_rows > 0:
        # ذخیره مغایرت‌ها در فایل گزارش مجزا
        unbalanced_rows.to_csv(output_report_path, index=False, encoding='utf-8-sig')
        print(f"گزارش مغایرت‌ها با موفقیت در مسیر '{output_report_path}' ذخیره شد.")
    else:
        print("عالی! تمامی سطور فایل مالیاتی تراز هستند و هیچ مغایرتی یافت نشد.")

if __name__ == "__main__":
    # نام فایل ورودی و خروجی نمونه
    input_file = "financial_data.csv"
    report_file = "unbalanced_report.csv"
    
    # اجرای تابع اعتبارسنجی
    validate_accounting_csv(input_file, report_file)

در این کد، کتابخانه pandas وظیفه خواندن بهینه فایل را بر عهده دارد. بخش pd.to_numeric تضمین می‌کند که اگر اعداد درون فایل CSV به صورت رشته‌ای (همراه با کامای جداکننده هزارگان) ذخیره شده باشند، بدون ایجاد کرش در برنامه به اعداد اعشاری قابل پردازش تبدیل شوند. پارامتر tolerance نیز برای جلوگیری از خطاهای جزئی ناشی از رند کردن ممیز شناور در سیستم‌های مالی در نظر گرفته شده است.

توضیح بخش‌به‌بخش اسکریپت

برای اینکه درک بهتری از نحوه کارکرد این ابزار داشته باشید، بخش‌های کلیدی آن را بررسی می‌کنیم:

• بارگذاری ایمن داده‌ها: تابع pd.read_csv داده‌ها را به شکل یک دیتافریم (DataFrame) در حافظه بارگذاری می‌کند. بلاک try-except مانع از متوقف شدن برنامه در صورت خراب بودن فایل یا عدم دسترسی به آن می‌شود.
• اعتبارسنجی ستون‌ها: حلقه بررسی می‌کند که آیا ستون‌های doc_id، description، debit و credit حتماً در فایل وجود دارند یا خیر تا از خطاهای بعدی جلوگیری شود.
• پاکسازی و تبدیل نوع داده: مقادیر ستون‌های مالی ممکن است حاوی کاراکترهای اضافی مثل کاما (,) باشند. دستور str.replace این کاراکترها را پاک کرده و مقادیر نامعتبر را با عدد صفر جایگزین می‌کند.
• محاسبه اختلاف و اعمال آستانه: ستون جدیدی به نام difference ساخته می‌شود که تفاضل بدهکار و بستانکار است. شرط abs(df['difference']) > tolerance کمک می‌کند اختلاف‌های ناشی از گرد کردن سیستم‌های کامپیوتری خطای کاذب ایجاد نکنند.

نحوه اجرا و تست عملی

برای تست کردن این اسکریپت، کافی است یک فایل نمونه CSV به نام financial_data.csv در همان پوشه برنامه‌تان بسازید که محتوای آن به شکل زیر باشد:

doc_id,description,debit,credit
101,خرید تجهیزات اداری,5000000,5000000
102,پرداخت حقوق کارکنان,12000000,11999500
103,فروش خدمات مشاوره,3000000,3000000
104,هزینه اجاره دفتر,4500000,4400000

حالا اسکریپت را از طریق ترمینال اجرا کنید:

python accounting_validator.py

خروجی نمونه در کنسول:

در حال بارگذاری فایل financial_data.csv...
--------------------------------------------------
تعداد کل سطرهای بررسی‌شده: 4
تعداد ردیف‌های دارای مغایرت (نامتراز): 2
--------------------------------------------------
گزارش مغایرت‌ها با موفقیت در مسیر 'unbalanced_report.csv' ذخیره شد.

همان‌طور که می‌بینید، ردیف‌های ۱۰۲ و ۱۰۴ به دلیل مغایرت ریالی شناسایی شده و در فایل خروجی unbalanced_report.csv ثبت شدند تا حسابدار مستقیماً سراغ اصلاح همان دو رکورد برود.

ایده‌های توسعه و شخصی‌سازی پیشرفته

این اسکریپت پایه‌ی بسیار خوبی است که می‌توانید آن را بر اساس نیاز سازمان خود توسعه دهید:

• گروه‌بندی بر اساس شماره سند: اگر اسناد حسابداری شما شامل چندین خط بدهکار و بستانکار زیر یک شماره سند واحد هستند، می‌توانید به جای بررسی تک‌سطری، از متد df.groupby('doc_id') استفاده کنید تا جمع کل بدهکار و بستانکار هر سند مجزا بررسی شود.
• ارسال خودکار هشدار: می‌توانید ماژول ارسال ایمیل پایتون (smtplib) را به انتهای اسکریپت متصل کنید تا در صورت وجود مغایرت، فایل گزارش فوراً به ایمیل مدیر مالی ارسال شود.
• رابط گرافیکی ساده: با کتابخانه داخلی tkinter می‌توانید یک دکمه «انتخاب فایل» بسازید تا کاربران غیربرنامه‌نویس و حسابداران هم بتوانند بدون کار با خط فرمان از آن استفاده کنند.

خطاهای رایج و راه‌حل‌ها

هنگام کار با فایل‌های حسابداری بزرگ ممکن است با چند خطای متداول روبرو شوید:

• خطای UnicodeDecodeError: این خطا زمانی رخ می‌دهد که انکودینگ فایل CSV شما با سیستم‌عامل سازگار نباشد. برای حل آن، هنگام خواندن فایل در دستور pd.read_csv پارامتر encoding='cp1256' یا encoding='latin1' را امتحان کنید.
• مقادیر خالی (NaN) در ستون‌ها: اگر سلولی خالی باشد، پایتون آن را به عنوان خطا در نظر می‌گیرد. متد .fillna(0.0) در کد ما این مشکل را به طور کامل حل کرده است.
• خطای فرمت اعداد: وجود حروف فارسی یا کاراکترهای خاص در ستون‌های مالی باعث اختلال می‌شود که متد تبدیل عددی ما با تبدیل مقادیر به رشته و پاکسازی آن را مدیریت می‌کند.

پرسش‌های متداول

جمع‌بندی

صرف زمان برای جستجوی خطاهای ریالی در فایل‌های مالیاتی و حسابداری، روشی منسوخ و فرساینده است. با نوشتن این اسکریپت ساده و متن‌باز پایتون، توانستیم ابزاری دقیق و سریع برای اعتبارسنجی خودکار ستون‌های بدهکار و بستانکار بسازیم که در چند ثانیه خطاهای اسناد را بیرون می‌کشد. با استفاده از پانداس، بدون نیاز به ابزارهای تجاری گران‌قیمت، امنیت و دقت فرآیندهای مالی خود را چند برابر کنید و زمان خود را به تحلیل‌های کلان اختصاص دهید.