Leads API
اقرأ العملاء المحتملين وحدّث حالتهم من أنظمتك الخاصة بمفتاح API محدّد النطاق.
تُرجمت هذه الصفحة من الإنجليزية. وفي حال وجود أي اختلاف، تسري النسخة الإنجليزية. اقرأ بالإنجليزية
تتيح Leads API لنظام CRM أو مستودع البيانات أو أداة الأتمتة لديك قراءة العملاء المحتملين وتحديث حالتهم.
المفاتيح
Section titled “المفاتيح”أنشئ المفاتيح في Studio ضمن Integrations → Leads API → New key. لكل مفتاح:
- اسم؛
- صلاحيات:
leads:read(Read leads) واختياريًاleads:write-status(Change lead status)؛ - مدة صلاحية 30 أو 90 أو 180 يومًا أو سنة.
تبدو المفاتيح بالشكل atl_lead_ يليه 43 حرفًا. تُعرض مرة واحدة، وتُخزَّن كبصمة فقط، ويجري التحقق منها في كل طلب، ويمكن إلغاؤها في أي وقت (Revoke key). يمكن أن تضم بيئة الموقع الواحدة حتى 20 مفتاحًا نشطًا. وقد يتطلب إنشاء مفتاح تأكيدًا ثانيًا على هاتفك.
عنوان URL الأساسي والمصادقة
Section titled “عنوان URL الأساسي والمصادقة”https://<delivery host>/v1/leads-api/environments/{environmentId}Authorization: Bearer atl_lead_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXالاستجابات بترويسة Cache-Control: private, no-store. وتستخدم الأخطاء صيغة RFC 9457 application/problem+json.
سرد العملاء المحتملين
Section titled “سرد العملاء المحتملين”GET /leads?since=2026-10-01T00:00:00Z&limit=50&cursor=…
| المعامل | ملاحظات |
|---|---|
since |
العملاء المحتملون المحدَّثون في هذا الوقت أو بعده فقط. ISO 8601 مع منطقة زمنية |
limit |
من 1 إلى 200، والافتراضي 50 |
cursor |
قيمة nextCursor من الاستجابة السابقة |
يأتي العملاء المحتملون مرتبين من أقدم تغيير. الاستجابة هي { "leads": [ … ], "nextCursor": "…" | null }. واصل التصفح حتى يصبح nextCursor هو null، واحفظ آخر updatedAt لجلب التغييرات فقط في المرة التالية.
تتضمن القائمة العملاء المحتملين المدموجين والمجهَّلين والتجريبيين. تحقق من mergedInto وanonymisedAt وisTest.
جلب عميل محتمل واحد
Section titled “جلب عميل محتمل واحد”GET /leads/{leadId}
| الحقل | ملاحظات |
|---|---|
id, source |
المصدر هو النموذج أو روبوت الدردشة الذي جاء منه العميل المحتمل |
form |
{ key, name }، أو null لعملاء روبوت الدردشة المحتملين |
name, email, phone, company, message |
تكون فارغة بعد أن أزال الاحتفاظ البيانات الشخصية |
details |
أي إجابات أخرى |
status |
new أو contacted أو qualified أو won أو lost أو spam |
isTest |
عمليات الإرسال التجريبية من Studio |
version |
أرسله مرة أخرى عند تغيير الحالة |
mergedInto, anonymisedAt |
تُضبط عندما دُمج العميل المحتمل أو جُهِّل |
createdAt, updatedAt |
طوابع زمنية بصيغة ISO 8601 |
تغيير حالة عميل محتمل
Section titled “تغيير حالة عميل محتمل”PATCH /leads/{leadId}/status مع { "status": "qualified", "expectedVersion": 4 }. يتطلب صلاحية Change lead status. يظهر التغيير في سجل العميل المحتمل بوصفه من إجراء المفتاح.
الأخطاء والحدود
Section titled “الأخطاء والحدود”| الحالة | الرمز | المعنى |
|---|---|---|
| 401 | CP_UNAUTHENTICATED |
مفتاح مفقود أو خاطئ أو منتهي الصلاحية أو ملغى |
| 403 | CP_FORBIDDEN |
ينقص المفتاح التصريح المطلوب لهذا الطلب |
| 404 | CP_NOT_FOUND |
لا يوجد عميل محتمل بهذا المعرّف في هذه البيئة |
| 409 | CP_VERSION_CONFLICT |
تغيّر العميل المحتمل منذ قرأته. اقرأه مرة أخرى |
| 422 | REQUEST_SCHEMA_INVALID |
متن الطلب أو أحد المعاملات غير صالح |
| 422 | CURSOR_INVALID |
تعذّرت قراءة المؤشر |
| 429 | RATE_LIMITED |
أكثر من 300 طلب في الدقيقة. انتظر وأعد المحاولة |
يُطبَّق حد المعدل لكل خادم Atlas API، لذا تعامل مع 300 طلب في الدقيقة بوصفها سقفًا، لا ضمانًا.