واجهة API لحاسبة الزكاة

نقطة النهاية

• المسار: POST /api/calculator
• التوثيق: غير مطلوب (واجهة عامة)
• نوع المحتوى: application/json

حد الطلبات

• 5 طلبات لكل عنوان IP خلال دقيقة واحدة (60 ثانية).
• في حالة تجاوز الحد يتم إرجاع 429 مع ترويسة Retry-After بعدد الثواني المتبقية.

نموذج الطلب

• أرسل قيم الراتب والمصاريف والنصاب بالدرهم.
• جميع الحقول مطلوبة ويجب أن تكون أرقاماً موجبة أو صفر.

{
  "salary": 12000,
  "expenses": 6500,
  "nisab": 50000
}

استجابة ناجحة

• يعرض الحقل data.result الحفظ الشهري والسنوي وقيمة الزكاة (2.5٪) وحالة الأهلية.
• يبين الحقل meta.rateLimit الحد المتاح والمتبقي في النافذة الحالية.

{
  "ok": true,
  "data": {
    "currency": "MAD",
    "inputs": { "salary": 12000, "expenses": 6500, "nisab": 50000 },
    "result": {
      "monthlySaving": 5500,
      "annualSaving": 66000,
      "zakatAmount": 1650,
      "status": "eligible"
    }
  },
  "meta": {
    "rateLimit": { "limit": 5, "remaining": 4, "windowMs": 60000 }
  }
}

أكواد الأخطاء

• 400 invalid_json — تنسيق JSON غير صحيح.
• 400 invalid_input — الحقول مفقودة أو ليست أرقاماً.
• 400 invalid_salary / invalid_expenses / invalid_nisab — تحقق من شروط الأرقام.
• 405 method_not_allowed — استخدم POST فقط.
• 429 rate_limited — تجاوزت حد الطلبات. أعد المحاولة لاحقاً.
• 500 internal_error — خطأ غير متوقع، راجع السجلات.