# POST /v2/batch-accounting/process/year

# Process Batch Documents By Year

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

<div class="api-docs" id="bkmrk-"></div>## Request Overview

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fbatch-accou"><div class="endpoint-info"><div>**URL:** `/v2/batch-accounting/process/year`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Middleware:** authWithJwt, shamsiDate</div></div></div>## Body Parameters

<div class="api-docs" id="bkmrk-field-type-required-"><table class="schema-table"><thead><tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>`year`</td><td>integer</td><td>yes</td><td>سال شمسی بین 1300 تا 1500 برای پردازش اسناد</td></tr><tr><td>`batch_size`</td><td>integer</td><td>no</td><td>سایز هر Batch. حداقل 50 و حداکثر 2000. مقدار پیش‌فرض: 500.</td></tr></tbody></table>

</div>## Request Example

```
POST /v2/batch-accounting/process/year

{
  "year": 1402,
  "batch_size": 800
}
  
```

<div class="api-docs" id="bkmrk--1"></div>## Validation Rules

<div class="api-docs" id="bkmrk-year%3A-required-%2B-int">- year: required + integer + min=1300 + max=1500
- batch\_size: integer + min=50 + max=2000
- اعتبارسنجی سال و ورودی‌ها قبل از پردازش انجام می‌شود

</div>## Response (Success)

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

<div class="api-docs" id="bkmrk-field-type-descripti"><table class="schema-table"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>`success`</td><td>boolean</td><td>نتیجه کلی پردازش</td></tr><tr><td>`data.total_processed`</td><td>integer</td><td>تعداد کل اسناد پردازش‌شده در سال</td></tr><tr><td>`data.total_errors`</td><td>integer</td><td>تعداد خطاهای رخ‌داده</td></tr><tr><td>`data.batches_count`</td><td>integer</td><td>تعداد Batchهای اجراشده</td></tr><tr><td>`message`</td><td>string</td><td>پیام نهایی پردازش سال</td></tr></tbody></table>

</div>```
{
  "success": true,
  "data": {
    "success": true,
    "total_processed": 7800,
    "total_errors": 12,
    "batches_count": 16
  },
  "message": "پردازش سال 1402 کامل شد. 7800 سند پردازش شد."
}
  
```

<div class="api-docs" id="bkmrk--2"></div>## Response (Validation Error)

```
{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "year": [
      "The year must be between 1300 and 1500."
    ]
  }
}
  
```

<div class="api-docs" id="bkmrk--3"></div>## Response (Server Error)

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

<div class="api-docs" id="bkmrk--4"></div>## Internal Architecture

<div class="api-docs" id="bkmrk-component-descriptio"><table class="schema-table"><thead><tr><th>Component</th><th>Description</th></tr></thead><tbody><tr><td>`processBatchByYear()`</td><td>محاسبه تاریخ آغاز سال و انتهای سال شمسی سپس فراخوانی `processBatchByDateRange`</td></tr><tr><td>`ShamsiDateHelper::endOfYear`</td><td>استخراج آخرین روز سال شمسی بر اساس تاریخ شروع</td></tr><tr><td>`processBatchByDateRange()`</td><td>پردازش دسته‌ای شامل chunking، sleep بین batchها و محاسبه خروجی</td></tr></tbody></table>

</div>## Process Flow

<div class="api-docs" id="bkmrk-validate-jwt-token-%E2%86%93"><div class="flowchart"><div class="flow-item">Validate JWT Token</div><div class="flow-arrow">↓</div><div class="flow-item">Validate Request Body (year + batch_size)</div><div class="flow-arrow">↓</div><div class="flow-item">Compute startOfYear = {year}-01-01</div><div class="flow-arrow">↓</div><div class="flow-item">Compute endOfYear via ShamsiDateHelper::endOfYear</div><div class="flow-arrow">↓</div><div class="flow-item">Call processBatchByDateRange(startOfYear, endOfYear, batchSize)</div><div class="flow-arrow">↓</div><div class="flow-item">Execute Batch Processing (chunking + throttling + batch execution)</div><div class="flow-arrow">↓</div><div class="flow-item">Aggregate Results (processed + errors + batch_count)</div><div class="flow-arrow">↓</div><div class="flow-item">Return Final JSON Response</div></div></div>