برگهٔ تازه

Route Info

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

این API برای محاسبه کامل مانده‌ها استفاده می‌شود؛ یعنی:

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

روش اجرا:

هر دو محاسبه از طریق سرویس AccountHistoryService انجام می‌شوند.

ورودی (Request Body)

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

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

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

مشخصات Job

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

{
  "payload": null,
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "from": "1403-01-01",
    "to": "1403-12-29",
    "jobs": ["daily", "monthly"],
    "status": "queued",
    "timestamp": "2025-12-01T14:20:00+03:30"
  }
}

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

{
  "payload": {
    "daily": {
      "1403-01-01": { "credit": 0, "debit": 1200000, "balance": -1200000 },
      "1403-01-02": { "credit": 500000, "debit": 0, "balance": 500000 }
    },
    "monthly": {
      "1403-01": { "credit": 0, "debit": 900000, "balance": -900000 },
      "1403-02": { "credit": 500000, "debit": 0, "balance": 500000 }
    }
  },
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "from": "1403-01-01",
    "to": "1403-12-29",
    "daily_meta": { "...": "..." },
    "monthly_meta": { "...": "..." },
    "timestamp": "2025-12-01T14:20:00+03:30"
  }
}

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

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

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

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

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

خطای محاسباتی یکی از دو عملیات (400)

{
  "error": {
    "code": "CALCULATION_ERROR",
    "message": "Error in one or both calculations",
    "details": {
      "daily": null,
      "monthly": {
        "code": "INTERNAL_ERROR",
        "message": "..."
      }
    }
  },
  "meta": {
    "colleague_id": 108,
    "timestamp": "2025-12-01T14:26:00+03:30"
  }
}

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

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

Meta