# POST /v2/manual-document/update

<div id="bkmrk-" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.9; text-align: justify;"></div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.9; text-align: justify;"><table border="1" style="width: 100%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f4f4f4; font-weight: bold;"><td style="padding: 10px;">Method</td><td style="padding: 10px;">Endpoint</td><td style="padding: 10px;">Controller</td></tr><tr><td style="direction: ltr; padding: 10px;">POST</td><td style="direction: ltr; padding: 10px;">/v2/manual-document/update</td><td style="direction: ltr; padding: 10px;">AccountingController@updateManualDocument</td></tr></tbody></table>

</div>### شرح عملکرد (Functionality)

این مسیر برای **ایجاد (add)** یا **ویرایش (update)** یک سند دستی (Manual Document) استفاده می‌شود. روش کار متد بطور خلاصه:

<div id="bkmrk-%D8%A7%D8%A8%D8%AA%D8%AF%D8%A7-%D8%AA%D8%A7%D8%B1%DB%8C%D8%AE-%D9%88%D8%B1%D9%88%D8%AF%DB%8C-%D8%A8%D8%A7" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.9; text-align: justify;">- ابتدا تاریخ ورودی با تنظیمات «پایان دوره مالی» در `office_config` مقایسه می‌شود.
- اگر تاریخ سند در بازه بسته مالی باشد، عملیات متوقف و پیام خطا بازگردانده می‌شود.
- در حالت `action = add`: 
    - محاسبه سال مالی از تاریخ سند
    - محاسبه سریال جدید سند دستی با `StaticController::getSerialId()`
    - ثبت رکورد جدید در جدول `manual_documents`
    - ثبت رکوردهای مرتبط در جدول `pays`
- در حالت `action = update`: 
    - به‌روزرسانی رکورد سند دستی
    - به‌روزرسانی موارد موجود در جدول `pays` یا افزودن موارد جدید
    - حذف رکوردهای پرداختی که در `data_delete` آمده‌اند

</div>در هر دو حالت، ثبت لاگ در `SystemLog` انجام می‌شود.

<div id="bkmrk--1" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.9; text-align: justify;"></div>### پارامترهای ورودی (JSON Body)

#### ساختار کلی

```
{
  "action": "add | update",
  "id": 15,                     // فقط در حالت update
  "date": "1403-05-20",
  "description": "سند دستی",
  "status": 3,
  "currency": 1,
  "currency_fee": 0,
  "sub_serial": null,
  "data": [
    {
      "preference": "colleague-42",
      "moeen": "moeen-18",
      "credit": "0",
      "debit": "250000",
      "description": "توضیحات"
    }
  ],
  "data_delete": [ ... ]         // فقط در حالت update
}
```

#### توضیحات پارامترهای کلیدی

<div id="bkmrk-action%3A-%D8%AA%D8%B9%DB%8C%DB%8C%D9%86-%D9%86%D9%88%D8%B9-%D8%B9%D9%85" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.9; text-align: justify;">- **action**: تعیین نوع عملیات. مقدار `add` برای ایجاد سند جدید و `update` برای ویرایش.
- **data\[\]**: آرایه خطوط حسابداری. هر خط شامل: 
    - preference: ترکیب نوع و شناسه؛ مثال: `colleague-42`
    - moeen: کد معین (با یا بدون پیشوند)
    - credit / debit: مبالغ با کاراکترهای فارسی/انگلیسی، که به عدد انگلیسی تبدیل می‌شوند
    - description: توضیحات خط سند
- **data\_delete**: لیست id پرداخت‌هایی که باید حذف شوند.

</div>### خروجی موفق (Success Response)

#### در حالت ایجاد (add)

```
{
  "status": true,
  "time": 1718450000,
  "message": "ثبت سند با موفقیت انجام شد. شماره: [3125, 3126]"
}
```

#### در حالت ویرایش (update)

```
{
  "status": true,
  "time": 1718450000,
  "message": "ویرایش سند با موفقیت انجام شد."
}
```

<div id="bkmrk--2" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.9; text-align: justify;"></div>### خروجی خطا (Error Response)

#### خطا در بازه زمانی بسته مالی

```
{
  "status": false,
  "time": 1718450000,
  "type": "danger",
  "code": 5007,
  "message": "ثبت و ویرایش سند دستی در بازه زمانی بسته شده امکان پذیر نمی‌باشد..."
}
```

#### خطاهای دیتابیس (Insert/Update)

```
{
  "status": false,
  "time": 1718450000,
  "code": 5006,
  "message": "SQL error message...",
  "trace": [ ... ]
}
```