مرجع API
احصل على مفتاح APIكل نقاط نهاية Sofia API v1 مع معاملاتها ونطاقاتها وأمثلتها، وساحة تجارب لتجربة كل منها بمفتاح API الخاص بك.
العنوان الأساسي https://api.sofia-post.com/api · مستند OpenAPI
OAuth
GET
/v1/oauth/authorizeابدأ تفويضًاافتحه في متصفح الشخص. عميل غير معروف أو redirect_uri غير مسجّل يعطي خطأ 400، وإلا يُعاد التوجيه إلى شاشة موافقة Sofia.GET/.well-known/oauth-authorization-server/api/v1/oauthاقرأ بيانات الخادم الوصفيةيعيد البيانات الوصفية لخادم التفويض OAuth 2.0 في Sofia API (RFC 8414)، ليكتشف العميل نقاط النهاية والخيارات المدعومة.POST/v1/oauth/tokenأصدر رمز وصوليستبدل client_credentials أو authorization_code مع PKCE أو refresh_token للاستخدام مرة واحدة برمز معتم صالح 3600 ثانية لمساحة عمل واحدة.الحساب
المنصات
المنشآت
GET
/v1/establishmentsاعرض المنشآتيسرد منشآت مساحة العمل التي يتصرف فيها الرمز. استخدم معرّفاتها كـ establishmentId عند النشر أو سرد الوسائط أو قراءة الإحصاءات.GET/v1/establishments/{id}/accountsاعرض الحسابات المتصلةيسرد الشبكات المتصلة بمنشأة، بلا رمز ولا سر شبكة، فقط ما يلزم لتسمية حساب واختياره كـ accountId في المنشورات المقبلة.POST/v1/establishments/{id}/connection-linksأنشئ رابط ربطيعيد رابطًا مستضافًا يفوّض فيه الشخص شبكة مع Sofia، فلا يصل أي رمز شبكة إلى تطبيقك. صالح 30 دقيقة، للتطبيق الفعلي فقط.GET/v1/establishments/{id}/insightsاعرض إحصاءات المنشأةيعيد أحدث الأرقام الصالحة التي جمعتها Sofia لكل حساب متصل. الحساب الذي لم يُجمع بعد يظهر awaiting، وليس صفرًا أبدًا.الوسائط
GET
/v1/mediaاعرض الوسائطيسرد مكتبة وسائط منشأة، الأحدث أولًا، صفحة بصفحة، بروابط موقّعة للنافذة الحالية. يعمل في الوضعين الاختباري والفعلي.POST/v1/mediaارفع وسائط أو استوردهايضيف ملفًا (multipart) أو رابط https تجلبه Sofia إلى مكتبة وسائط منشأة. يتطلب تطبيقًا فعليًا واشتراكًا نشطًا للحساب.GET/v1/media/{id}اعرض وسائطيعيد وسائط واحدة من المكتبة برابط موقّع صالح للنافذة الحالية، لتعيد استخدام معرّفها في منشور دون رفعها من جديد.DELETE/v1/media/{id}أزل وسائطيزيل وسائط من مكتبة منشأتها كما يفعل التطبيق. لا يُتلف الملف نفسه، ويحتفظ المنشور المجدول بصورته كما كانت من قبل.المنشورات
GET
/v1/postsاعرض المنشوراتيسرد منشورات المنشآت التي يصل إليها الرمز، الأحدث أولًا، مع تصفية حسب المنشأة والحالة والفترة والكاتب، صفحة بصفحة.POST/v1/postsانشر منشورًاتنشر التطبيقات الفعلية فورًا أو تجدول بموعد أو تحفظ مسودة، أما الاختبارية فتحاكي فقط. مع ?dry_run=true يفحص كل شيء ولا يكتب شيئًا.GET/v1/posts/{id}اعرض منشورًايعيد منشورًا مع حالة كل شبكة ورابطه بعد النشر وخطئه إن فشل. يقرأ الوضع الفعلي أي منشور في مساحة العمل، والاختباري منشورًا محاكى.PATCH/v1/posts/{id}عدّل منشورًاقبل أن تبدأ أي شبكة بالإرسال، يستبدل targets أو يضبط scheduledAt أو ينقل المنشور بين draft وscheduled. تبقى الحقول المحذوفة كما هي.DELETE/v1/posts/{id}احذف منشورًايحذف منشورًا كما يفعل التطبيق: لا يُرسل شيء مجدول ويُزال المنشور المنشور من شبكته. التطبيقات الاختبارية لا تملك شيئًا حقيقيًا لحذفه.Webhooks
GET
/v1/webhooksاعرض الـ webhooksيسرد webhooks التطبيق دون سرّ التوقيع، الذي لا يُعاد إلا مرة واحدة عند تسجيل الـ webhook، فلا يمكن استرجاعه لاحقًا.POST/v1/webhooksسجّل webhookيسجّل رابط https تستدعيه Sofia بحدث JSON موقّع، مع إعادة المحاولة حتى خمس مرات عند الفشل. يظهر السر مرة واحدة؛ 10 webhooks كحد أقصى.DELETE/v1/webhooks/{id}احذف webhookيحذف webhook. لن يتلقى شيئًا بعد ذلك، حتى عمليات التسليم التي كانت تنتظر إعادة محاولة، ولا يعيد الاستدعاء أي جسم.POST/v1/webhooks/{id}/testأرسل حدث اختباريسلّم حدث webhook.test موقّعًا كأي حدث آخر، دون انتظار المستقبِل، لتتحقق من توقيعك. خمسة أحداث كحد أقصى في الدقيقة.