مرجع API
نظرة عامة على REST API لـ Teammates.ai. طرق المصادقة ونقاط النهاية الرئيسية لراية وآدم وسارة وحدود الاستخدام ومعالجة الأخطاء وأمثلة الكود.
نظرة عامة على API
يمنحك REST API من Teammates.ai وصولًا برمجيًا لإدارة المنظمات وزملاء الذكاء الاصطناعي والوظائف والمرشحين والمقابلات والحملات والمحادثات والفوترة. جميع نقاط النهاية تعيد استجابات JSON وتستخدم طرق HTTP القياسية (GET، POST، PUT، DELETE). الرابط الأساسي لجميع طلبات API هو https://api.teammates.ai/v1.
المصادقة
يدعم Teammates.ai طريقتي مصادقة. استخدم مفاتيح API للتكاملات بين الخوادم ورموز JWT للطلبات في سياق المستخدم.
| الطريقة | تنسيق الترويسة | الأفضل لـ | كيفية الحصول |
|---|---|---|---|
| مفتاح API | Authorization: Bearer sk_live_... | التكاملات بين الخوادم، webhooks، الأتمتة. | لوحة التحكم > إعدادات المنظمة > مفاتيح API. أنشئ مفتاحًا جديدًا وخزّنه بأمان. |
| رمز JWT | Authorization: Bearer eyJ... | طلبات سياق المستخدم، تكاملات لوحة التحكم. | POST /v1/auth/login بالبريد الإلكتروني وكلمة المرور. ينتهي الرمز بعد 24 ساعة؛ جدّده عبر /v1/auth/refresh. |
ملاحظة:لا تكشف مفاتيح API في كود الواجهة الأمامية أو المستودعات العامة. استخدم متغيرات البيئة على خادمك.
نقاط النهاية الرئيسية
تم تنظيم API حول الموارد. إليك نقاط النهاية الأكثر استخدامًا مجمّعة حسب المجال.
| المجال | نقطة النهاية | الطرق | الوصف |
|---|---|---|---|
| المنظمات | /v1/organizations | GET، PUT | استرجاع وتحديث إعدادات المنظمة. |
| الموظفون | /v1/employees | GET، POST، PUT، DELETE | إدارة زملاء الذكاء الاصطناعي (نُسخ راية، آدم، سارة). |
| الوكلاء | /v1/employees/:id/agents | GET، POST، PUT | ضبط وكلاء القنوات (دردشة، بريد، هاتف) لكل زميل ذكاء اصطناعي. |
| مصادر البيانات | /v1/data-sources | GET، POST، PUT، DELETE | إدارة محتوى قاعدة المعرفة (ملفات، روابط، أسئلة شائعة). |
| الوظائف (سارة) | /v1/jobs | GET، POST، PUT، DELETE | إنشاء وإدارة قوائم الوظائف لمقابلات سارة. |
| المرشحون (سارة) | /v1/candidates | GET، POST، PUT | إضافة المرشحين واسترجاع حالة مقابلاتهم. |
| المقابلات (سارة) | /v1/interviews | GET، POST | إنشاء المقابلات واسترجاع النتائج والدرجات والتقارير. |
| الحملات (آدم) | /v1/campaigns | GET، POST، PUT | إنشاء وإدارة حملات المبيعات الصادرة. |
| المحادثات (راية) | /v1/conversations | GET، POST | استرجاع محادثات الدعم والرسائل وحالة الحل. |
| الاستخدام والفوترة | /v1/usage | GET | التحقق من رصيد الأرصدة وسجل الاستخدام وحالة الفوترة. |
حدود الاستخدام
تمنع حدود الاستخدام في API سوء الاستخدام وتضمن أداءً ثابتًا لجميع المستخدمين.
| نوع الحد | الحد | الاستجابة عند التجاوز |
|---|---|---|
| في الدقيقة | 60 طلبًا/دقيقة لكل مفتاح API | HTTP 429 طلبات كثيرة جدًا |
| في اليوم | 10,000 طلب/يوم لكل مفتاح API | HTTP 429 طلبات كثيرة جدًا |
| نقاط النهاية الدفعية | 100 عنصر لكل طلب دفعي | HTTP 400 طلب غير صالح |
ملاحظة:إذا كنت تحتاج حدودًا أعلى، تواصل مع الدعم. استخدم webhooks بدلًا من الاستطلاع للبيانات الفورية. اجمع الطلبات في دفعات كلما أمكن لتقليل حجم المكالمات.
مثال كود: إنشاء مقابلة
إليك كيفية إنشاء مقابلة جديدة لسارة باستخدام curl:
```bash curl -X POST https://api.teammates.ai/v1/interviews \ -H "Authorization: Bearer sk_live_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "job_id": "job_abc123", "candidate": { "name": "Jane Smith", "email": "jane@example.com" }, "deadline": "2026-03-01T23:59:59Z", "language": "en" }' ```
تنشئ سارة المقابلة وتولّد الأسئلة من الوصف الوظيفي وترسل للمرشح دعوة بالبريد الإلكتروني مع رابط مقابلة فريد.
معالجة الأخطاء
يعيد API رموز حالة HTTP القياسية. تتضمن استجابات الخطأ نص JSON مع رمز الخطأ والرسالة وحقل التفاصيل للتصحيح.
| رمز الحالة | المعنى | السبب الشائع |
|---|---|---|
| 200 OK | نجح الطلب. | استجابة طبيعية. |
| 201 Created | تم إنشاء المورد. | طلب POST ناجح. |
| 400 Bad Request | نص طلب أو معلمات غير صالحة. | حقل مطلوب مفقود، JSON غير صالح، أو نوع بيانات غير صحيح. |
| 401 Unauthorized | فشلت المصادقة. | مفتاح API أو رمز JWT مفقود أو منتهي الصلاحية أو غير صالح. |
| 403 Forbidden | صلاحيات غير كافية. | مفتاح API لا يملك صلاحية الوصول إلى المورد المطلوب. |
| 404 Not Found | المورد غير موجود. | معرّف غير صالح أو مورد محذوف. |
| 429 Too Many Requests | تم تجاوز حد الاستخدام. | انتظر وأعد المحاولة. تحقق من ترويسة Retry-After للتأخير. |
| 500 Internal Server Error | خطأ في جانب الخادم. | تواصل مع الدعم مع معرّف الطلب من ترويسات الاستجابة. |
إصدارات API
جميع نقاط النهاية مُصدّرة تحت /v1. عند إدخال تغييرات جذرية، يُصدر إصدار جديد (مثلًا /v2). يبقى الإصدار السابق متاحًا لمدة 12 شهرًا على الأقل بعد إطلاق الإصدار الجديد. يعلن Teammates.ai عن إيقاف الإصدارات عبر البريد الإلكتروني وإشعارات لوحة التحكم قبل 90 يومًا على الأقل من انتهاء الدعم.
الأسئلة الشائعة
هل API متاح في الخطة المجانية؟▾
هل يمكنني استخدام API لإنشاء مقابلات لسارة برمجيًا؟▾
كيف أتعامل مع أخطاء API في تكاملي؟▾
مقالات ذات صلة
هل تحتاج مساعدة إضافية؟
تواصل معنا