الترقيم والتصفية والأخطاء وحدود المعدل

كل نقطة طرفية للقوائم تقبل page وpage_size وتعيد المغلّف نفسه. ‏total هو عدد كل ما يطابق عوامل التصفية لا حجم هذه الصفحة - فعدد الصفحات هو Math.ceil(total / page_size).

curl -sS "https://your-host/api/v1/crm/contacts?page=2&page_size=100" \
  -H "Authorization: Bearer $CLIENTO_TOKEN"

{
  "items": [ { "id": 4182, "display_name": "Sara Ahmadi", "…": "…" } ],
  "page": 2,
  "page_size": 100,
  "total": 3417
}

‏q بحث نصّي حر في الحقول التي يبحث فيها الإنسان - الأسماء والبريد والشركة. وما عداه معاملات استعلام صريحة، وكل مجموعة توثّق معاملاتها في مستند OpenAPI.

# Free-text
curl -sS "https://your-host/api/v1/crm/contacts?q=ahmadi" \
  -H "Authorization: Bearer $CLIENTO_TOKEN"

# Typed filters (tasks)
curl -sS "https://your-host/api/v1/crm/tasks?status=open&priority=high&overdue=true" \
  -H "Authorization: Bearer $CLIENTO_TOKEN"

المعامل غير المعروف يُتجاهل ولا يُرفض - فالخطأ المطبعي يعيد نتائج غير مُصفّاة بدل خطأ. راجع أسماء المعاملات في مستند OpenAPI حين يبدو أن مرشِّحًا لا يفعل شيئًا.

كل رفض، من جسم مشوَّه إلى عطل داخلي، يعيد الحقول الثلاثة نفسها. ولا شيء يعيد صفحة خطأ HTML، فلا يضطر العميل أبدًا إلى تخمين ما إذا كان الجسم قابلًا للتحليل.

{
  "error": "validation_error",
  "message": "Invalid payload",
  "details": { "email": ["Not a valid email address."] }
}

• ‏`error` - رمز آلي مستقر. تفرّع عليه وعرِّب عليه.
• ‏`message` - نص تشخيصي بالإنجليزية للمطوِّر. لا تعرضه للمستخدم النهائي ولا تطابق عليه؛ فقد تتغيّر صياغته.
• ‏`details` - بنية تختلف بحسب الخطأ: أخطاء الحقول للتحقق، وrequired لرفض الصلاحية، وreason لقاعدة عمل، وretry_after للتقييد. وقد تكون null.

النقاط الحسّاسة - تسجيل الدخول، ورموز بوابة العملاء لمرة واحدة، وإرسال النماذج العامة، وصفحات الفواتير العامة، وردود الدفع - مُقيَّدة لكل مُنادٍ. أما عمليات CRUD المُصادَق عليها فغير مُقيَّدة افتراضيًا، لكن مشغّل مساحة العمل قد يضبط حدودًا، فالعميل الحسن التصرّف يعالج 429 على أي حال.

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "Too many requests",
  "details": { "retry_after": 42 }
}

• التزم بـRetry-After (بالثواني). هو جواب الخادم نفسه - والانتظار الأقصر يُرفض مجددًا.
• تراجَع أُسّيًّا مع عشوائية عند 5xx. فالفاصل الثابت يحوّل انقطاعًا قصيرًا إلى تدافع لحظة التعافي.
• أعِد GET وDELETE بحرية - فهما مُتماثلا الأثر. أما POST فانظر القسم التالي.

لا توجد ترويسة Idempotency-Key عامة. حيث يكون التكرار ضارًّا، تحمل النقطة الطرفية هويّة تماثلها في الجسم وتجعلها مطلوبة لا اختيارية - فالهوية بيد العميل، لأن العميل وحده يعرف أن هذه إعادة محاولة.

في النقاط التي لا تملك حقل تماثل، فإن POST الذي تنتهي مهلته مجهول النتيجة. لا تُعِد الإرسال عشوائيًا: اقرأ الحالة بـGET مُصفّى على شيء تتحكم فيه أنت - مرجع خارجي خزّنته على السجل - وأنشئ فقط إن كان غائبًا فعلًا.