# GET /v2/redis-accounting/documents/group

# Get Documents by Group

این اندپوینت وظیفه دارد تمام اسناد حسابداری مرتبط با یک **کد گروه (Group Code)** را از Redis بازیابی کند. داده‌ها شامل اسناد، مانده فعلی، تعداد اسناد، و در صورت درخواست، مانده تجمیعی از ابتدای سال شمسی است. استخراج داده از Redis بر اساس الگوی زیر انجام می‌شود: `accounting:docs:group:{code}`.

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

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fredis-accou"><div class="endpoint-info"><div>**URL:** `/v2/redis-accounting/documents/group`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Middleware:** authWithJwt, shamsiDate</div></div></div>## Query 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>`code`</td><td>integer</td><td>yes</td><td>کد گروه موردنظر</td></tr><tr><td>`from_year_start`</td><td>boolean</td><td>optional</td><td>اگر true باشد، ماندهٔ تجمیعی از ابتدای سال شمسی محاسبه می‌شود</td></tr><tr><td>`to_date`</td><td>string (YYYY-MM-DD)</td><td>optional</td><td>تاریخ نهایی جهت محاسبه year\_start\_balance (پیش‌فرض: امروز)</td></tr></tbody></table>

</div>## Request Example

```
GET /v2/redis-accounting/documents/group?code=10&from_year_start=true
  
```

<div class="api-docs" id="bkmrk--1"></div>## Response (Success)

ساختار خروجی دقیقاً مطابق پیاده‌سازی فعلی RedisAccountingService است.

<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>True در صورت موفقیت عملیات</td></tr><tr><td>`data.documents`</td><td>array</td><td>آرایه دوبخشی: **\[ diffProcess\[\], docs\[\] \]**  
diffProcess شامل timestamps اجرای مراحل Redis است.  
docs شامل اطلاعات کامل هر سند است.</td></tr><tr><td>`data.balance`</td><td>object</td><td>ماندهٔ فعلی گروه در Redis</td></tr><tr><td>`data.total_documents`</td><td>integer</td><td>مقدار همیشه **۲** است چون count روی آرایه دوبخشی اعمال شده (نقص منطقی در سیستم فعلی)</td></tr><tr><td>`data.year_start_balance`</td><td>object</td><td>فقط اگر from\_year\_start=true ارسال می‌شود</td></tr></tbody></table>

</div>```
{
  "success": true,
  "data": {
    "documents": [
      [
        [1733301001.102, 1733301001.105, ...],
        [
          {
            "id": "88401",
            "date": "1403-03-15",
            "debit": "150000",
            "credit": "0",
            "group": "10",
            "general": "101",
            "account": "1011",
            "subsidiary": "1011001"
          }
        ]
      ],
      "balance": {
        "debit": 150000,
        "credit": 0,
        "remaining": 150000
      },
      "total_documents": 2,
      "year_start_balance": {
        "debit": 150000,
        "credit": 0,
        "remaining": 150000,
        "year_start": "1403-01-01",
        "to_date": "1403-09-15"
      }
    }
  }
}
  
```

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

```
{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "code": [
      "The code field is required."
    ]
  }
}
  
```

<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 Redis Architecture

<div class="api-docs" id="bkmrk-key-pattern-type-des"><table class="schema-table"><thead><tr><th>Key Pattern</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>`accounting:docs:group:{code}`</td><td>Set</td><td>شناسه اسناد مرتبط با این گروه</td></tr><tr><td>`accounting:doc:{id}`</td><td>Hash</td><td>اطلاعات کامل هر سند</td></tr><tr><td>`balance:group:{code}`</td><td>Hash</td><td>مانده فعلی گروه در Redis</td></tr><tr><td>`accounting:docs:by_date`</td><td>SortedSet</td><td>برای year\_start\_balance استفاده می‌شود</td></tr></tbody></table>

</div>## Process Flow

<div class="api-docs" id="bkmrk-validate-inputs-%E2%86%93-fe"><div class="flowchart"><div class="flow-item">Validate Inputs</div><div class="flow-arrow">↓</div><div class="flow-item">Fetch IDs (accounting:docs:group:{code})</div><div class="flow-arrow">↓</div><div class="flow-item">Load Each Document (accounting:doc:{id})</div><div class="flow-arrow">↓</div><div class="flow-item">Sort by Date Field</div><div class="flow-arrow">↓</div><div class="flow-item">Get Redis Balance (balance:group:{code})</div><div class="flow-arrow">↓</div><div class="flow-item">If requested → Calculate Year-Start Balance</div><div class="flow-arrow">↓</div><div class="flow-item">Return Final JSON Payload</div></div></div>