مرجع API
الإصدارات عبر الرابط، وترقيم الصفحات بالمؤشر، وعدم التكرار، وأخطاء RFC 7807.
فريق ChatinFlow
دليل رسمي
نظرة عامة
واجهة HTTP API العامة لها إصدارات في الرابط ضمن `/api/v1`. التغييرات غير المتوافقة تصدر في إصدار جديد. تمر استجابات الموارد عبر API Resources محددة الأنواع، ولا تُعاد نماذج Eloquent الخام أبدًا.
تستخدم الأخطاء RFC 7807 `application/problem+json` مع `type` و`title` و`status` و`detail` و`traceId`. اربطها بترويسة الاستجابة `X-Request-Id`.
الأعراف
المسار الأساسي `/api/v1`
الإصدار ضمن عنوان URL
ترقيم الصفحات بالمؤشر
`?cursor=...&limit=50`
Idempotency-Key في عمليات الكتابة
UUIDv4، ونافذة إزالة تكرار مدتها 24 ساعة
أجسام الطلبات والاستجابات بصيغة JSON
ترويسة Accept: application/json
أنماط شائعة
قائمة بالمؤشر
تابع `meta.nextCursor` ما دام `meta.hasMore` يساوي true. لا تبنِ عملاء بترقيم يعتمد على الإزاحة.
GET /api/v1/<resource>?limit=50&cursor=<opaque>
التعامل مع problem+json
عند 4xx/5xx، حلّل مستند problem. اعرض `title`/`detail` للمشغلين، واحتفظ بـ `traceId` لتذاكر الدعم.
{
"type": "https://...",
"title": "Validation failed",
"status": 422,
"detail": "...",
"traceId": "..."
}إنشاء دون تكرار
أنشئ UUIDv4 جديدًا لكل عملية منطقية. أعد محاولة أخطاء النقل بالمفتاح نفسه، واستخدم مفتاحًا جديدًا لكل إنشاء منطقي جديد.
تشغيل مسار لجهة اتصال
أرسل مسارًا منشورًا إلى جهة اتصال واحدة من متجرك أو من نموذج أو من Zapier. يعمل المسار في آخر محادثة لجهة الاتصال؛ وتصل `variables` إلى المسار بصيغة `{{ trigger.variables.name }}`.
POST /api/v1/workspaces/<workspace>/automations/<id>/start
{ "contact_id": "<contact id>", "variables": { "coupon": "WELCOME10" } }اجعل الرمز محدودًا
يمكن حصر الرمز في جهات الاتصال أو صندوق الوارد. امنح أي تكامل ما يحتاجه فقط؛ `GET /api/v1/auth/me` يستجيب لكل رمز لاختبار الاتصال.
ملاحظات النطاق
ملاحظة
ما الذي تغطيه API
موارد المنتج داخل مساحة العمل (جهات الاتصال، والأتمتة، وقراءة صندوق الوارد والكتابة فيه ضمن ما هو متاح، وقراءة بيانات الفوترة حيث يُسمح، وغير ذلك). يتّسع النطاق الدقيق مع المنتج: المساعدة وهذا المرجع معًا يشكّلان العقد.
نصيحة
الأدلة أم API
وصفات التحويل من التعليق إلى الرسائل الخاصة ونمو صنّاع المحتوى موجودة في أدلة المساعدة. استخدم API عندما يحتاج متجرك أو الوسيط البرمجي إلى إنشاء جهات اتصال أو تشغيل الأتمتة برمجيًا.
هل كان هذا الدليل مفيدًا؟
تصفح المزيد في المكتبة
مستعد لتطبيق
ذلك عمليًا؟
ابدأ بناء أول أتمتة مجانًا. دون بطاقة ائتمان. فقط اربط قناتك وانطلق خلال دقائق.