POST /v2/account-history/calculate-monthly

Route Info

شرح عملکرد (Functionality)

این API وظیفه محاسبه و ذخیره مانده‌های ماهانه برای یک همکار (Colleague) را دارد. محاسبه می‌تواند بر اساس:

محاسبات می‌توانند به صورت:

در حالت async، عملیات توسط CalculateAccountHistoryJob با type = "monthly" انجام می‌شود.

ورودی (Request Body)

{
  "colleague_id": 108,
  "year": 1403,           // optional
  "from": "1403-01-01",   // optional
  "to": "1403-12-29",     // optional
  "async": false          // optional (default=false)
}

قوانین اعتبارسنجی

منطق اجرا (Execution Logic)

مشخصات Job

پاسخ موفق (Async Mode)

{
  "payload": null,
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "from": "1403-01-01",
    "to": "1403-12-29",
    "type": "monthly",
    "status": "queued",
    "timestamp": "2025-12-01T12:35:00+03:30"
  }
}

پاسخ موفق (Sync Mode)

{
  "payload": {
    "1403-01": { "credit": 0, "debit": 900000, "balance": -900000 },
    "1403-02": { "credit": 500000, "debit": 0, "balance": 500000 }
  },
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "total_months": 12,
    "timestamp": "2025-12-01T12:35:00+03:30"
  }
}

پاسخ‌های خطا (Error Responses)

اعتبارسنجی (400)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "colleague_id field is required"
  },
  "meta": {
    "timestamp": "2025-12-01T12:40:00+03:30"
  }
}

تاریخ آینده مجاز نیست (400)

{
  "error": {
    "code": "FUTURE_DATE_NOT_ALLOWED",
    "message": "Cannot calculate for future dates."
  },
  "meta": {
    "colleague_id": 108,
    "to": "1405-01-01",
    "timestamp": "2025-12-01T12:40:00+03:30"
  }
}

خطای داخلی (500)

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Unexpected error..."
  },
  "meta": {
    "colleague_id": 108,
    "timestamp": "2025-12-01T12:41:00+03:30"
  }
}

Meta