ف فواترا

حدود الاستخدام

حدّ الطلبات في الدقيقة

الحد يُطبَّق على كل مفتاح API في نافذة ثابتة مدّتها دقيقة واحدة، ويختلف بحسب الخطة:

الخطةطلب / دقيقةفواتير حقيقية / شهرمفاتيحنقاط Webhook
البداية 30 50 1 —
النمو 120 1,000 3 1
الاحتراف 600 10,000 10 5

ترويسات المراقبة

كل ردّ (ناجحًا كان أو فاشلًا) يحمل:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1791234600
X-Fawtara-Mode: live

عند التجاوز:

HTTP/1.1 429 Too Many Requests
Retry-After: 23

{
  "error": {
    "type": "rate_limited",
    "message": "تجاوزت الحد المسموح (120 طلب في الدقيقة) لخطة النمو.",
    "limit": 120,
    "retry_after": 23
  }
}

الحصة الشهرية

تُحسب الحصة على الفواتير والإشعارات الدائنة المُنشأة بمفتاح fwt_live_ فقط، وتُصفَّر في أول يوم من كل شهر ميلادي بتوقيت عمّان. بيئة الاختبار غير محدودة.

عند النفاد:

HTTP/1.1 402 Payment Required

{
  "error": {
    "type": "quota_exceeded",
    "message": "استُنفدت حصة الخطة الشهرية (1000 فاتورة). قم بترقية الخطة أو انتظر بداية الشهر القادم.",
    "plan": "growth",
    "quota": 1000,
    "used": 1000,
    "period": "2026-10",
    "upgrade_url": "https://fawtara.codexal.co/app/dashboard/billing"
  }
}
لا توجد رسوم تجاوز مفاجئة؛ نرفض الطلب بوضوح بدل أن نُفاجئك بفاتورة. راقب GET /v1/usage ونبّه فريقك عند بلوغ 80%.

نصائح لتقليل عدد الطلبات

  • الردّ على POST /v1/invoices يحمل الحالة النهائية — لا تستعلم بعده في حلقة.
  • استخدم الـ Webhooks بدل الاستعلام الدوري.
  • عند السرد استخدم limit=100 مع ترشيح بالتاريخ بدل جلب صفحات صغيرة كثيرة.
  • خزّن qr_content وuuid عندك بدل إعادة طلبهما.

احتياجات أعلى

إن كنت مزوّد نظام ERP أو نقاط بيع وتحتاج حدودًا أعلى من خطة الاحتراف، يمكن رفع الحصة وحدّ الطلبات على حسابك بشكل مخصّص — راسلنا من صفحة الاشتراك.

→ منع التكرار والمحاولات جدول الأخطاء ←