Skip to main content
#P1641

POST /v2/batch-accounting/process/month

Process Batch Documents By Month

این اندپوینت اسناد حسابداری را بر اساس یک ماه شمسی مشخص دریافت کرده و آن‌ها را به صورت دسته‌ای (Batch Processing) پردازش می‌کند. ابتدا از تاریخ ورودی برای تعیین محدودهٔ کامل ماه استفاده می‌شود سپس عملیات پردازش دسته‌ای بر اساس منطق processBatchByDateRange اجرا می‌گردد. خروجی شامل تعداد کل اسناد پردازش‌شده، اطلاعات هر Batch و پیام نهایی مربوط به نام فارسی ماه است.

Request Overview

URL: /v2/batch-accounting/process/month
Method: POST
Middleware: authWithJwt, shamsiDate

Body Parameters

Field Type Required Description
month_date string (YYYY-MM-DD) yes تاریخ شمسی داخل ماه مورد نظر. فقط برای تشخیص شماره ماه استفاده می‌شود.
batch_size integer no سایز هر Batch. حداقل 10، حداکثر 1000. مقدار پیش‌فرض: 100.

Request Example

POST /v2/batch-accounting/process/month

{
  "month_date": "1403-05-01",
  "batch_size": 200
}

Validation Rules

  • month_date: required + regex YYYY-MM-DD
  • batch_size: integer + min=10 + max=1000
  • month_date باید با shamsiDate middleware معتبر تشخیص داده شود

Response (Success)

ساختار خروجی بر اساس BatchAccountingService::processBatchByDateRange است.

Field Type Description
success boolean نتیجه نهایی پردازش
data.total_processed integer تعداد کل اسناد پردازش‌شده
data.total_errors integer تعداد خطاهای رخ‌داده در Batchها
data.batches_count integer تعداد کل Batchهای اجراشده
message string پیام نهایی شامل نام ماه فارسی استخراج‌شده با getMonthName 
{
  "success": true,
  "data": {
    "success": true,
    "total_processed": 450,
    "total_errors": 0,
    "batches_count": 3
  },
  "message": "پردازش ماه مرداد کامل شد. 450 سند پردازش شد."
}

Response (Validation Error)

{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "month_date": [
      "The month_date format is invalid."
    ]
  }
}

Response (Server Error)

{
  "success": false,
  "message": "خطا در پردازش ماه: Internal server error..."
}

Internal Architecture

Component Description
ShamsiDateHelper::startOfMonth استخراج اولین روز ماه شمسی به فرمت YYYY-MM-DD
ShamsiDateHelper::endOfMonth استخراج آخرین روز ماه شمسی
processBatchByDateRange() منطق اصلی Batch Processing روی بازهٔ تاریخ
getMonthName() تبدیل شماره ماه به نام فارسی (فروردین تا اسفند)

Process Flow

Validate JWT Token
↓
Validate Shamsi Date (middleware)
↓
Validate Request Body (month_date + batch_size)
↓
Extract startOfMonth & endOfMonth (ShamsiDateHelper)
↓
Call processBatchByDateRange(start, end, batchSize)
↓
Execute Batch Processing (chunking + processing + throttling)
↓
Aggregate Results (processed + errors)
↓
Get Month Name (getMonthName)
↓
Return Final Response
Back to top