---
sidebar:
  order: 1
title: واجهة API عبر HTTP
description: >-
  المصادقة واستكشاف الأدوات وتأكيد التغييرات باستخدام واجهة API الحالية عبر HTTP.
---

أرسل طلبات واجهة المنتج البرمجية إلى أصل Influence الموثوق، مثل `https://influence.so`. لا يقبل نطاق التوثيق طلبات واجهة API الخاصة بالمنتج. استخدم المسارات التالية كما هي ودون معاملات استعلام.

## أنشئ مفتاح API بصلاحيات محددة [#create-a-scoped-api-key]

في [إعدادات Influence](https://influence.so/sign-in?next=%2Fapp%2Fsettings%2Faccount%23settings-developer)، افتح «التطبيقات والأتمتة»، ثم «مفاتيح API». اختر الصلاحيات التي تحتاج إليها وموعد انتهاء الصلاحية. احفظ المفتاح الذي يعرض مرة واحدة في مخزن أسرارك باسم `PUBLISH_API_TOKEN`. أرسله في `Authorization: Bearer …`؛ ولا تضعه أبدا في عنوان URL أو محتوى طلب أو محادثة. ألغ المفتاح عند انتهاء حاجتك إليه.

## استكشف الأدوات واقرأ الحسابات [#discover-tools-and-make-a-read]

اضبط `PUBLISH_API_URL` على الأصل الموثوق. تفترض هذه الأمثلة توفر `PUBLISH_API_TOKEN` للعملية مسبقا. تتطلب `accountList` الصلاحية `integrations:read`؛ اتبع حقول ترقيم الصفحات التي تعيدها لاسترجاع الصفحات اللاحقة.

```sh
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":{}}'
```

## مسارات الطلبات [#request-paths]

| الطريقة | المسار | الغرض |
| --- | --- | --- |
| `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":{…}}`. احصل على مخطط مدخلات كل أداة من فهرس الأدوات الحالي.

## حضر الإجراءات وأكدها [#prepare-and-confirm-actions]

استخدم الحقل `confirmation` في الفهرس: لا تحتاج عمليات القراءة عادة إلى تأكيد، لكن تحديث الإحصاءات يحتاج إليه رغم كونه عملية قراءة. أما الاستعلام عن أجزاء الرفع وإكماله وإلغاؤه، فتتابع عملية رفع مصرحا بها مسبقا عبر `/call`.

1. أرسل مدخلات العمل المحددة إلى `/prepare`. تتضمن الاستجابة الناجحة `status: "confirmation_required"` و`confirmationCapability` و`expiresAt` و`inputDigest`، وقد تتضمن `summary`.
2. قبل انتهاء الصلاحية، أرسل المدخلات نفسها إلى `/confirm`. ضع قيمة التأكيد المعادة في `X-Publish-Confirmation` ومفتاحا جديدا ينشئه المستدعي في `Idempotency-Key`.
3. احتفظ بالمدخلات وقيمة التأكيد والمفتاح معا. بعد انقطاع التأكيد أو عدم تأكد نتيجته، أعد استخدام القيم الثلاث نفسها للطلب نفسه. لا تنشئ تحضيرا بديلا لاستعادة نتيجة غير مؤكدة.

يتكون مفتاح منع التكرار من 16–200 محرف من `A–Z` و`a–z` و`0–9` و`.` و`_` و`:` و`-`. تعامل مع قيم تأكيد الإجراءات كأسرار دون تفسير محتواها. إرسال مفتاح إلى `/call` أو `/prepare` لا يحجز عملية كتابة مؤكدة.

يختلف تأكيد الطلب عن الموافقة على النشر. عند تغيير النشر أو الجدولة، اعرض المراجعة الحالية كاملة: الحسابات والنص والإعدادات ومعاينات الوسائط الفعلية أو روابطها وموعد الجدولة والمنطقة الزمنية. يمكن للعميل الإبلاغ عن موافقة بشرية صريحة وحديثة باستخدام `approval: "approved"` لمراجعات النصوص والصور والفيديوهات المؤهلة على منصات التواصل الاجتماعي؛ ويجب ألا يختلق موافقة أو يعامل التحضير على أنه موافقة. تسجل Influence هذه الموافقة على أنها موافقة أبلغ عنها العميل. أما بطاقة المراجعة المضمنة المدعومة أو المراجعة بعد تسجيل الدخول، فتسجل الإجراء الذي اتخذه الشخص داخلها.

يقبل النشر المباشر على TikTok خيارات صريحة وموافقة عبر المحادثة من خلال [مسار المراجعة](/ar/developers/mcp#prepare-finished-content). احفظ الخيارات كاملة باستخدام `campaignReview`، ثم احصل على موافقة جديدة على المراجعة المحدثة قبل التنفيذ. بطاقة المراجعة اختيارية. لا تخصم الجدولة العادية عبر API أو واجهة سطر الأوامر من حصة الجدولة بالذكاء الاصطناعي؛ أما [حصة MCP وInfluence IQ](/ar/help/ai-assistants#scheduling-allowance) المنفصلة، فتسري على هذين المسارين حتى حين تحصل مراجعة محفوظة من أحد مسارات الذكاء الاصطناعي على الموافقة لاحقا داخل Influence. تظل المتطلبات الأخرى للخطة ولمزود الخدمة سارية. اقرأ الإيصال المحفوظ قبل أي إجراء آخر؛ وتستلزم `needs_review` التحقق من النتيجة ومعالجة أي تعارض، لا إرسالا جديدا.

## تعامل مع الأخطاء والنتائج غير المؤكدة [#handle-errors-and-uncertain-results]

تحقق من حالة HTTP ومحتوى الاستجابة معا. تعيد الأدوات الناجحة `{"ok":true,"toolName":"…","output":{…}}`. تعيد إخفاقات الأدوات `{"ok":false,"toolName":"…","error":{"code":"…","message":"…","retryable":false}}`، وقد تصل برمز HTTP 200. تستخدم إخفاقات النقل `{"error":{"code":"…","message":"…","retryable":false}}` دون `ok` أو `toolName`.

تعني 401 أن المصادقة مطلوبة؛ تحقق من انتهاء الصلاحية أو إلغاء بيانات الاعتماد. تحتاج الصلاحية الناقصة إلى منح الإذن المناسب، لا إلى تكرار الطلبات. قد تعني 503 أن الخدمة غير متاحة أو أن طلب جدولة آخر يجري تحديثا لمساحة العمل. استخدم رمز الخطأ المعاد وإرشادات إعادة المحاولة؛ ولا تكرر تنفيذ إجراء نشر تلقائيا. انتهاء المهلة لا يثبت فشل عملية الكتابة؛ احتفظ ببيانات تأكيدها واقرأ حالتها الحالية قبل إعادة إرسالها. القبول والجدولة والنشر نتائج مختلفة.

## ارفع الوسائط [#upload-media]

يفضل استخدام `uploadMedia` من SDK أو `media:upload` من واجهة سطر الأوامر للملفات المحلية. يستخدمان أدوات الرفع متعدد الأجزاء نفسها، ويحتفظان بقيمة `clientKey` ثابتة لإعادة المحاولة. لا يمكن إرفاق الوسائط إلا بعد أن تكون النتيجة جاهزة وتتضمن `assetId`. لرابط HTTPS مصرح به، استخدم `mediaImport` مع `url` و`name` اختياريا. تستخدم مراجع الملفات الحقيقية التي توفرها البيئة المضيفة كائن `file` المنفصل؛ ولا يحتاج عنوان URL عام إلى اختلاق معرف ملف في البيئة المضيفة. مسار الملف المحلي ليس عنوان URL لتنزيله. راجع [حدود الوسائط](/ar/help/media): يبلغ الحد الأقصى لاستيراد الفيديو عبر 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؛ استخدم أداة الرفع المساعدة للملفات المدعومة الأكبر. الرفع لا يمنح الموافقة على النشر أبدا.

[تصفح مرجع واجهة API](/ar/api-reference) أو [نزل مواصفة OpenAPI](/specs/influence.openapi.json).