POST
/api/v4/social/bulk-postsإنشاء منشورات دفعة واحدة
يتحقق من صلاحية حتى 500 منشور على وسائل التواصل الاجتماعي ويضعها في قائمة الانتظار بطلب واحد، ويعيد مهمة للاستعلام الدوري عن نتائج كل صف.
المعلمات
النص الأساسي
ينطبق الحقل المتداخل المحدد على أنه مطلوب فقط عند إرسال الحقل الأصل. إذا كان الحقل الأصل اختياريًا وحذفته، فلا تنطبق حقوله الفرعية المطلوبة.
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| input | object | مطلوب | Wrapper object. The entire request body must be nested under `input`. |
| input.posts | array of objects | مطلوب | The rows to create, 1 to 500 of them. Each row is the same object POST /social/posts takes as its `input`; the per-row fields are listed below. |
| input.name | string | اختياري | Optional label for the job itself, to identify it in your own logs. Not shown to any audience. |
| input.posts[].socialProfileId | string | مطلوب | UUID of the brand publishing this row. Rows may target different brands in one request. |
| input.posts[].name | string | مطلوب | Internal name for the post. |
| input.posts[].platforms | array of strings | مطلوب | Platforms for this row: `FACEBOOK`, `INSTAGRAM`, `TWITTER` (X), `LINKEDIN`, `PINTEREST`. Each must already have a connection on that row's brand. |
| input.posts[].content | string | مطلوب | The post body. |
| input.posts[].action | string | مطلوب | `DRAFT`, `SCHEDULE` (requires a schedule) or `PUBLISH`. |
| input.posts[].mediaUrls | array of strings | اختياري | Public https image URLs. Required when the row targets Instagram or Pinterest. |
| input.posts[].videoUrls | array of strings | اختياري | Public https video URLs. |
| input.posts[].link | string | اختياري | Link to attach where the platform supports one. |
| input.posts[].scheduledAt | string | اختياري | ISO-8601 publish instant with an offset. Alternative to `scheduleDate` + `scheduleTime`, never both. |
| input.posts[].scheduleDate | string | اختياري | `YYYY-MM-DD`, interpreted in that row's brand timezone. Send with `scheduleTime`. |
| input.posts[].scheduleTime | string | اختياري | `HH:MM`, interpreted in that row's brand timezone. Send with `scheduleDate`. |
| input.posts[].connectedChannelIds | array of strings | اختياري | Restrict this row to specific connections by ID. |
| input.posts[].clientReference | string | اختياري | Your own identifier for this row, echoed back on the matching job result. The most reliable way to reconcile a batch against your own records. |
مثال على الطلب
نص جاهز للصق. استبدل المعرّفات والقيم النموذجية بقيمك.
{ "input": { "name": "Autumn campaign load", "posts": [ { "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "name": "Autumn week 1", "platforms": ["INSTAGRAM", "FACEBOOK"], "content": "Week one of the autumn collection: the Fairfield oak sideboard, finished by hand in the workshop.", "mediaUrls": ["https://cdn.example.com/social/autumn-w1.jpg"], "action": "SCHEDULE", "scheduleDate": "2026-10-02", "scheduleTime": "09:30", "clientReference": "campaign-4471-slot-01" }, { "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "name": "Autumn week 2", "platforms": ["INSTAGRAM", "FACEBOOK", "LINKEDIN"], "content": "Week two: the Halcyon armchair. Sixty hours of work, one chair.", "mediaUrls": ["https://cdn.example.com/social/autumn-w2.jpg"], "action": "SCHEDULE", "scheduleDate": "2026-10-09", "scheduleTime": "09:30", "clientReference": "campaign-4471-slot-02" }, { "socialProfileId": "a90f7c22-5db1-4e83-9f40-2b7c6a1e5d33", "name": "Eastside autumn teaser", "platforms": ["INSTAGRAM"], "content": "Something solid is arriving next week. Stay tuned.", "mediaUrls": ["https://cdn.example.com/social/eastside-teaser.jpg"], "action": "SCHEDULE", "scheduledAt": "2026-10-01T08:00:00-04:00", "clientReference": "campaign-4471-slot-03" } ] }}الاستجابات
200The whole batch validated. A job was queued, poll GET /social/bulk-posts/{bulkJobId} for per-row results.
{ "data": { "createBulkSocialMediaPosts": { "success": true, "error": [], "job": { "id": "9b3f18d0-7a26-4c51-8e94-1f0d5c6b7a82", "status": "QUEUED", "totalCount": 3, "processedCount": 0, "successCount": 0, "failureCount": 0, "createdAt": "2026-09-28T14:04:52Z", "updatedAt": "2026-09-28T14:04:52Z", "results": [] } } }}200At least one row failed validation, so **nothing was created**. `success` is `false`, no job is returned, and each rejected row is reported with its 0-based `index`.
{ "data": { "createBulkSocialMediaPosts": { "success": false, "error": [ { "message": "SY95050: Bulk validation failed, no posts were created", "code": "SY95050", "contextInfo": null } ], "job": { "id": null, "status": "FAILED", "totalCount": 3, "processedCount": 0, "successCount": 0, "failureCount": 2, "createdAt": "2026-09-28T14:04:52Z", "updatedAt": "2026-09-28T14:04:52Z", "results": [ { "index": 1, "clientReference": "campaign-4471-slot-02", "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "platforms": ["INSTAGRAM", "FACEBOOK", "LINKEDIN"], "status": "INVALID", "socialPostId": null, "postStatus": null, "errors": [ { "message": "SY95045: No connected channel for LINKEDIN on this brand", "code": "SY95045", "contextInfo": [{ "key": "platform", "value": "LINKEDIN" }] } ] }, { "index": 2, "clientReference": "campaign-4471-slot-03", "socialProfileId": "a90f7c22-5db1-4e83-9f40-2b7c6a1e5d33", "platforms": ["INSTAGRAM"], "status": "INVALID", "socialPostId": null, "postStatus": null, "errors": [ { "message": "SY95046: scheduledAt must carry a UTC offset", "code": "SY95046", "contextInfo": null } ] } ] } } }}401Unauthenticated, missing or invalid API key.
ينشئ عدة منشورات على وسائل التواصل الاجتماعي في طلب واحد. تُرسَل الصفوف ضمن حمولة الطلب — لا يوجد رفع ملفات ولا CSV، بل مجرد مصفوفة من الكائنات نفسها التي يقبلها POST /social/posts واحدًا في كل مرة. بحد أقصى 500 صف لكل طلب.
حالة استخدام: تحميل محتوى ربع سنة في استدعاء واحد. تحتوي أداة التخطيط لديك على تقويم المحتوى الكامل للعميل. أنشئ صفًا لكل موعد نشر، وميّز كل صف بقيمة clientReference الخاصة بك، وأرسلها معًا. إما أن تنجح الدفعة كوحدة واحدة أو أن تحدد لك بدقة الصفوف التي تحتاج إلى إصلاح. خزّن job.id المُعاد واستعلم دوريًا عن GET /social/bulk-posts/{bulkJobId} حتى يصل status إلى حالة نهائية، ثم طابق كل نتيجة باستخدام clientReference الخاص بها.
يجري التحقق من صلاحية الدفعة بأكملها مسبقًا
يجري التحقق من صلاحية كل صف قبل إنشاء أي شيء، وتُعامل الدفعة كوحدة غير قابلة للتجزئة في تلك المرحلة:
- إذا كان أي صف غير صالح، فلن يُنشأ أي شيء. تكون قيمة
successهيfalse، ويُعادSY95050فيerror، ويظهر كل صف غير صالح فيjob.results[]معindexالخاص به الذي يبدأ ترقيمه من 0، وclientReferenceالخاص به، والسبب فيerrors[]. أصلح تلك الصفوف وأعد إرسال الدفعة بأكملها. - إذا كانت جميع الصفوف صالحة، تُدرَج مهمة في قائمة الانتظار، وتكون قيمة
successهيtrue، وتحصل علىjob.id. قد تظل بعض الصفوف تفشل لاحقًا عندما ترفضها المنصة وقت النشر؛ ويظهر ذلك في المهمة، وليس هنا.
طابق النتائج باستخدام clientReference حيثما أمكن، وباستخدام index فيما عدا ذلك — لا تُعاد الصفوف نفسها في الاستجابة، لذا فإن هذين الحقلين هما الرابط الوحيد ببياناتك.
ملاحظات.
- يجب تغليف جسم الطلب داخل كائن
input، مع وضع الصفوف فيinput.posts. - تحقق من
success، وليس من حالة HTTP. يُعاد رفض الدفعة بأكملها على هيئةHTTP 200معsuccess: falseوSY95050فيerror. - الحد الأقصى هو 500 صف لكل طلب. تُرفض أي مصفوفة أكبر من ذلك مباشرةً مع
SY95048ولا يُنشأ أي شيء؛ قسّمها وأرسلها على عدة دفعات. - تُحدَّد العلامة التجارية في كل صف بواسطة
socialProfileId. لا يُستخدمbrandIdإلا كرمز في مسار URL، ولا يحتوي هذا المسار على أي رمز مسار أصلًا. - يمكن أن تستهدف الصفوف علامات تجارية مختلفة. يجري التحقق من
platformsلكل صف بالرجوع إلى العلامة التجارية الخاصة بذلك الصف، لذا فإن اتصال منصة بعلامة تجارية وعدم اتصالها بأخرى يؤدي إلى فشل الصفوف التي تحتاج إليها فقط. - يتبع كل صف قواعد الجدولة نفسها المتبعة لمنشور واحد:
scheduledAtأوscheduleDate+scheduleTime، ولا يجوز الجمع بينهما مطلقًا، وتُقرأ قيمscheduleDate/scheduleTimeوفق المنطقة الزمنية للعلامة التجارية الخاصة بذلك الصف. يمكن استخدام الصيغتين في صفوف مختلفة ضمن دفعة واحدة. - تنطبق حدود معدل الطلبات على الطلب، وليس على الصفوف: تُحتسب دفعة من 500 صف كطلب واحد من حصتك. راجع حدود معدل الطلبات.
عملية كتابة: لم تُنفَّذ على الحساب الفعلي. بُني الطلب والاستجابة المعروضان استنادًا إلى مخطط API؛ وتؤدي هذه العملية عند تشغيلها إلى النشر على حسابات فعلية على وسائل التواصل الاجتماعي.
Request
curl -X POST 'https://listingsapi.com/api/v4/social/bulk-posts' \ -H "Authorization: API $LISTINGSAPI_KEY" \ -H 'Content-Type: application/json' \ -d '{ "input": { "name": "Autumn campaign load", "posts": [ { "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "name": "Autumn week 1", "platforms": [ "INSTAGRAM", "FACEBOOK" ], "content": "Week one of the autumn collection: the Fairfield oak sideboard, finished by hand in the workshop.", "mediaUrls": [ "https://cdn.example.com/social/autumn-w1.jpg" ], "action": "SCHEDULE", "scheduleDate": "2026-10-02", "scheduleTime": "09:30", "clientReference": "campaign-4471-slot-01" }, { "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "name": "Autumn week 2", "platforms": [ "INSTAGRAM", "FACEBOOK", "LINKEDIN" ], "content": "Week two: the Halcyon armchair. Sixty hours of work, one chair.", "mediaUrls": [ "https://cdn.example.com/social/autumn-w2.jpg" ], "action": "SCHEDULE", "scheduleDate": "2026-10-09", "scheduleTime": "09:30", "clientReference": "campaign-4471-slot-02" }, { "socialProfileId": "a90f7c22-5db1-4e83-9f40-2b7c6a1e5d33", "name": "Eastside autumn teaser", "platforms": [ "INSTAGRAM" ], "content": "Something solid is arriving next week. Stay tuned.", "mediaUrls": [ "https://cdn.example.com/social/eastside-teaser.jpg" ], "action": "SCHEDULE", "scheduledAt": "2026-10-01T08:00:00-04:00", "clientReference": "campaign-4471-slot-03" } ] } }'