واجهة API عبر HTTP
المصادقة واستكشاف الأدوات وتأكيد التغييرات باستخدام واجهة API الحالية عبر HTTP.
أرسل طلبات واجهة المنتج البرمجية إلى أصل Influence الموثوق، مثل https://influence.so. لا يقبل نطاق التوثيق طلبات واجهة API الخاصة بالمنتج. استخدم المسارات التالية كما هي ودون معاملات استعلام.
أنشئ مفتاح API بصلاحيات محددة
في إعدادات Influence، افتح «التطبيقات والأتمتة»، ثم «مفاتيح API». اختر الصلاحيات التي تحتاج إليها وموعد انتهاء الصلاحية. احفظ المفتاح الذي يعرض مرة واحدة في مخزن أسرارك باسم PUBLISH_API_TOKEN. أرسله في Authorization: Bearer …؛ ولا تضعه أبدا في عنوان URL أو محتوى طلب أو محادثة. ألغ المفتاح عند انتهاء حاجتك إليه.
استكشف الأدوات واقرأ الحسابات
اضبط PUBLISH_API_URL على الأصل الموثوق. تفترض هذه الأمثلة توفر PUBLISH_API_TOKEN للعملية مسبقا. تتطلب accountList الصلاحية integrations:read؛ اتبع حقول ترقيم الصفحات التي تعيدها لاسترجاع الصفحات اللاحقة.
export PUBLISH_API_URL="https://influence.so"
curl "$PUBLISH_API_URL/api/v1/tools" \
-H "Authorization: Bearer $PUBLISH_API_TOKEN"
curl "$PUBLISH_API_URL/api/v1/tools/accountList/call" \
-H "Authorization: Bearer $PUBLISH_API_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"input":{}}'مسارات الطلبات
| الطريقة | المسار | الغرض |
|---|---|---|
GET |
/api/v1/tools |
سرد الأدوات المتاحة لبيانات الاعتماد هذه. |
POST |
/api/v1/tools/{tool}/call |
استدعاء أداة لا تحتاج إلى تأكيد، بما فيها متابعة عمليات الرفع المصرح بها. |
POST |
/api/v1/tools/{tool}/prepare |
تحضير عملية كتابة محددة دون تنفيذها. |
POST |
/api/v1/tools/{tool}/confirm |
تأكيد عملية الكتابة المحضرة. |
POST |
/api/v1/media/import |
تأكيد رفع صورة صغيرة كبيانات ثنائية بعد تحضيره. |
تستخدم طلبات أدوات JSON الترويسة Content-Type: application/json ومحتوى لا يتضمن سوى input: {"input":{…}}. احصل على مخطط مدخلات كل أداة من فهرس الأدوات الحالي.
حضر الإجراءات وأكدها
استخدم الحقل confirmation في الفهرس: لا تحتاج عمليات القراءة عادة إلى تأكيد، لكن تحديث الإحصاءات يحتاج إليه رغم كونه عملية قراءة. أما الاستعلام عن أجزاء الرفع وإكماله وإلغاؤه، فتتابع عملية رفع مصرحا بها مسبقا عبر /call.
- أرسل مدخلات العمل المحددة إلى
/prepare. تتضمن الاستجابة الناجحةstatus: "confirmation_required"وconfirmationCapabilityوexpiresAtوinputDigest، وقد تتضمنsummary. - قبل انتهاء الصلاحية، أرسل المدخلات نفسها إلى
/confirm. ضع قيمة التأكيد المعادة فيX-Publish-Confirmationومفتاحا جديدا ينشئه المستدعي فيIdempotency-Key. - احتفظ بالمدخلات وقيمة التأكيد والمفتاح معا. بعد انقطاع التأكيد أو عدم تأكد نتيجته، أعد استخدام القيم الثلاث نفسها للطلب نفسه. لا تنشئ تحضيرا بديلا لاستعادة نتيجة غير مؤكدة.
يتكون مفتاح منع التكرار من 16–200 محرف من A–Z وa–z و0–9 و. و_ و: و-. تعامل مع قيم تأكيد الإجراءات كأسرار دون تفسير محتواها. إرسال مفتاح إلى /call أو /prepare لا يحجز عملية كتابة مؤكدة.
يختلف تأكيد الطلب عن الموافقة على النشر. عند تغيير النشر أو الجدولة، اعرض المراجعة الحالية كاملة: الحسابات والنص والإعدادات ومعاينات الوسائط الفعلية أو روابطها وموعد الجدولة والمنطقة الزمنية. يمكن للعميل الإبلاغ عن موافقة بشرية صريحة وحديثة باستخدام approval: "approved" لمراجعات النصوص والصور والفيديوهات المؤهلة على منصات التواصل الاجتماعي؛ ويجب ألا يختلق موافقة أو يعامل التحضير على أنه موافقة. تسجل Influence هذه الموافقة على أنها موافقة أبلغ عنها العميل. أما بطاقة المراجعة المضمنة المدعومة أو المراجعة بعد تسجيل الدخول، فتسجل الإجراء الذي اتخذه الشخص داخلها.
يقبل النشر المباشر على TikTok خيارات صريحة وموافقة عبر المحادثة من خلال مسار المراجعة. احفظ الخيارات كاملة باستخدام campaignReview، ثم احصل على موافقة جديدة على المراجعة المحدثة قبل التنفيذ. بطاقة المراجعة اختيارية. لا تخصم الجدولة العادية عبر API أو واجهة سطر الأوامر من حصة الجدولة بالذكاء الاصطناعي؛ أما حصة MCP وInfluence IQ المنفصلة، فتسري على هذين المسارين حتى حين تحصل مراجعة محفوظة من أحد مسارات الذكاء الاصطناعي على الموافقة لاحقا داخل Influence. تظل المتطلبات الأخرى للخطة ولمزود الخدمة سارية. اقرأ الإيصال المحفوظ قبل أي إجراء آخر؛ وتستلزم needs_review التحقق من النتيجة ومعالجة أي تعارض، لا إرسالا جديدا.
تعامل مع الأخطاء والنتائج غير المؤكدة
تحقق من حالة HTTP ومحتوى الاستجابة معا. تعيد الأدوات الناجحة {"ok":true,"toolName":"…","output":{…}}. تعيد إخفاقات الأدوات {"ok":false,"toolName":"…","error":{"code":"…","message":"…","retryable":false}}، وقد تصل برمز HTTP 200. تستخدم إخفاقات النقل {"error":{"code":"…","message":"…","retryable":false}} دون ok أو toolName.
تعني 401 أن المصادقة مطلوبة؛ تحقق من انتهاء الصلاحية أو إلغاء بيانات الاعتماد. تحتاج الصلاحية الناقصة إلى منح الإذن المناسب، لا إلى تكرار الطلبات. قد تعني 503 أن الخدمة غير متاحة أو أن طلب جدولة آخر يجري تحديثا لمساحة العمل. استخدم رمز الخطأ المعاد وإرشادات إعادة المحاولة؛ ولا تكرر تنفيذ إجراء نشر تلقائيا. انتهاء المهلة لا يثبت فشل عملية الكتابة؛ احتفظ ببيانات تأكيدها واقرأ حالتها الحالية قبل إعادة إرسالها. القبول والجدولة والنشر نتائج مختلفة.
ارفع الوسائط
يفضل استخدام uploadMedia من SDK أو media:upload من واجهة سطر الأوامر للملفات المحلية. يستخدمان أدوات الرفع متعدد الأجزاء نفسها، ويحتفظان بقيمة clientKey ثابتة لإعادة المحاولة. لا يمكن إرفاق الوسائط إلا بعد أن تكون النتيجة جاهزة وتتضمن assetId. لرابط HTTPS مصرح به، استخدم mediaImport مع url وname اختياريا. تستخدم مراجع الملفات الحقيقية التي توفرها البيئة المضيفة كائن file المنفصل؛ ولا يحتاج عنوان URL عام إلى اختلاق معرف ملف في البيئة المضيفة. مسار الملف المحلي ليس عنوان URL لتنزيله. راجع حدود الوسائط: يبلغ الحد الأقصى لاستيراد الفيديو عبر HTTPS مقدار 250 MiB، حتى لو كان يسمح بملف MP4 جاهز أكبر حجما عند رفعه مباشرة.
تتيح نقطة النهاية POST /api/v1/media/import وسيلة النقل الحالية للصور الصغيرة: حضر mediaImport بواصف الرفع المطابق تماما، ثم أرسل البايتات نفسها بصيغة application/octet-stream. أدرج X-Publish-Confirmation وIdempotency-Key وX-Publish-Upload؛ واجعل الترويسة الأخيرة تتضمن واصف JSON المرمز وفق URI. يجب أن يطابق حجم البيانات وقيمة SHA-256 لها ما يحدده الواصف. تقتصر وسيلة النقل هذه على 3 MiB؛ استخدم أداة الرفع المساعدة للملفات المدعومة الأكبر. الرفع لا يمنح الموافقة على النشر أبدا.