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

سجلات API

ما فعلته مفاتيح API لمساحة العمل هذه فعلًا: الطريقة والمسار والحالة ورمز الخطأ والزمن وأي مفتاح استُخدم. وهو أسرع طريق لمعرفة سبب فشل تكامل من دون إضافة تسجيل إليه.

السجل

GET/v1/api-logs

مسار واحد مُرقَّم بالمؤشر، الأحدث أولًا، ويُحفظ لنافذة محدودة. والمدخلة ليست بالضرورة لمفتاح: تكون api_key_id بقيمة null للطلب الصادر عن جلسة.

رموز الجلسة فقط

التصريح logs.read خارج مجموعة نطاقات مفاتيح API عن قصد: لا يستطيع المفتاح قراءة سجل استخدامه هو. ولا يقرؤه إلا مستخدم مسجّل يملك التصريح، حاملًا X-Workspace-Id. انظر المصادقة.

المدخلة

الحقل	النوع	الوصف
method, route, path	string	نمط المسار المطابَق — بما فيه بادئة ‎/api التي يقدّم الوسيط الخادم تحتها — والمسار الفعلي بعد إزالة سلسلة الاستعلام. والنمط هو ما تجمّع عليه.
status_code	number	حالة HTTP التي أُعيدت.
error_code	string \| null	رمز الخطأ عند فشل الطلب. وnull عند النجاح.
duration_ms	number	زمن المعالجة على الخادم بالمللي ثانية.
api_key_id	string \| null	أي مفتاح API قدّم الطلب، إن وُجد.
api_key_mode	"live" \| "test" \| null	هل كان ذلك المفتاح مفتاح إنتاج أم اختبار.
request_id	string \| null	المعرّف المعاد في ترويسة الاستجابة. وهو ما تذكره في طلب الدعم.
created_at	string	متى عولج الطلب.

لا تُسجَّل الأجسام

لا يُخزَّن جسم طلب ولا جسم استجابة ولا ترويسات ولا سلاسل استعلام. وهذا قيد مقصود لا إغفال: فهو ما يتيح قراءة السجل لكل من يملك logs.read دون كشف محتوى أي رسالة.

المرشِّحات

المعامل	القيم	الوصف
outcome	success, error	الطلبات الناجحة أو الفاشلة.
status_code	number	حالة HTTP واحدة بالضبط.
method	GET, POST, …	طريقة HTTP واحدة.
api_key_id	key_…	مفتاح API واحد. مفيد لعزل تكامل بعينه.
since, until	ISO-8601	نافذة زمنية. وكلا الطرفين بصيغة ISO-8601.
limit, after	—	ترقيم بالمؤشر.

curl

# logs.read is deliberately outside the API-key scope set.
curl "https://whats.azzamkh.sa/api/v1/api-logs?outcome=error&limit=50" \
  -H "Authorization: Bearer <access token>" \
  -H "X-Workspace-Id: ws_..."

# 200 OK — no bodies, no headers, no query strings are recorded.
# {
#   "data": [
#     {
#       "id": "log_...",
#       "method": "POST",
#       "route": "/v1/messages",
#       "path": "/v1/messages",
#       "status_code": 422,
#       "error_code": "VALIDATION_ERROR",
#       "duration_ms": 34,
#       "api_key_id": "key_...",
#       "api_key_mode": "test",
#       "request_id": "req_...",
#       "created_at": "2026-08-14T09:00:00.000Z"
#     }
#   ],
#   "page": { "next_cursor": "...", "has_more": true }
# }

الترشيح بـ outcome=error ثم التجميع على error_code هو عادةً أسرع سؤال أول. وتشرح صفحة الأخطاء معنى كل رمز.