POST
/api/v4/bulk-postsإنشاء منشور جماعي
ينشئ منشورًا واحدًا على وسائل التواصل الاجتماعي وينشره عبر مواقع عديدة في طلب واحد.
المعلمات
النص الأساسي
ينطبق الحقل المتداخل المحدد على أنه مطلوب فقط عند إرسال الحقل الأصل. إذا كان الحقل الأصل اختياريًا وحذفته، فلا تنطبق حقوله الفرعية المطلوبة.
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| input | object | مطلوب | Wrapper object. Every field below is a property of `input`, the entire body must be nested under it. |
| input.postName | string | مطلوب | Internal name for the campaign (not shown publicly). |
| input.locationIds | array of strings | مطلوب | Base64-encoded location Relay IDs to publish to. |
| input.postType | string | مطلوب | One of `EVENT`, `OFFER`, `ANNOUNCEMENT`, `COVID19`, `PRODUCT`. |
| input.postSites | array of strings | مطلوب | Target publishers: `GOOGLE` and/or `FACEBOOK`. |
| input.postMessage | array of objects | اختياري | Per-site post body. Each entry: `site` and `message`. |
| input.postMessage[].site | string | مطلوب | Publisher for this message: `GOOGLE` or `FACEBOOK`. |
| input.postMessage[].message | string | مطلوب | Post body text for that site. |
| input.postMediaUrl | array of objects | اختياري | Per-site media. Each entry: `site`, `url`, and `type` (`IMAGE` or `VIDEO`). |
| input.postMediaUrl[].site | string | مطلوب | Publisher for this media asset. |
| input.postMediaUrl[].url | string | مطلوب | Publicly accessible media URL. |
| input.postMediaUrl[].type | string | اختياري | `IMAGE` or `VIDEO`. |
| input.postCta | array of objects | اختياري | Per-site call-to-action button. Each entry: `site`, `type`, `url`. |
| input.postScheduledDates | object | اختياري | Scheduling window: `startDatetime`, `endDatetime`, and optional `removalSites`. When provided, the post is created with status `SCHEDULED`. |
| input.postScheduledDates.startDatetime | string | مطلوب | ISO-8601 datetime the post goes live. |
| input.postScheduledDates.endDatetime | string | مطلوب | ISO-8601 datetime the post is removed. |
| input.postContextInfo | object | اختياري | Type-specific details (offer coupon/redeem/terms, or event title/times). Required by `OFFER`, `EVENT`, and `PRODUCT` posts. |
| input.products | array of objects | اختياري | Product entries for `PRODUCT` posts (name, price, photo, cta). |
| input.componentIdentifier | string | اختياري | Optional client component reference for tracking. |
| input.componentType | string | اختياري | Optional client component type for tracking. |
مثال على الطلب
نص جاهز للصق. استبدل المعرّفات والقيم النموذجية بقيمك.
{ "input": { "postName": "July Reopening Announcement", "locationIds": [ "TG9jYXRpb246MTgwMDI4OQ==", "TG9jYXRpb246MTgwMDI5MA==" ], "postType": "ANNOUNCEMENT", "postSites": ["GOOGLE", "FACEBOOK"], "postMessage": [ { "site": "GOOGLE", "message": "We're back! Visit us this week for our summer menu." }, { "site": "FACEBOOK", "message": "We're back! Swing by for the new summer menu." } ], "postMediaUrl": [ { "site": "GOOGLE", "url": "https://cdn.example.com/summer.jpg", "type": "IMAGE" } ], "postScheduledDates": { "startDatetime": "2026-07-10T09:00:00Z", "endDatetime": "2026-07-24T23:59:00Z" } }}الاستجابات
200Bulk post accepted. `success` is true and the created campaign is returned. Note the response is keyed under `createSocialPost`: the bulk endpoint returns the same response shape as `POST /posts`.
{ "data": { "createSocialPost": { "clientMutationId": null, "success": true, "errors": null, "socialPost": { "id": "U29jaWFsUG9zdDo5OTIwMQ==", "name": "July Reopening Announcement", "status": "SCHEDULED", "type": "ANNOUNCEMENT", "createdAt": "2026-07-08", "scheduledStartDate": "2026-07-10", "scheduledEndDate": "2026-07-24", "sites": ["GOOGLE", "FACEBOOK"], "locationIds": [1800289, 1800290] } } }}400Bad request, the body was not wrapped in `input` (error message: `Variable "$input" of required type ... was not provided`).
401Unauthenticated, missing or invalid API key.
ينشئ حملة بمنشور واحد ويوزّعها على كل موقع في locationIds، مع النشر على postSites المحددة. بخلاف الإنشاء لكل موقع على حدة، يستهدف استدعاء واحد جميع مواقعك، وهي طريقة فعّالة لنشر إعلان أو عرض أو فعالية على مستوى الشركة.
بنية الطلب. يجب تغليف جسم الطلب بالكامل داخل كائن input، بحيث يكون كل حقل (postName، locationIds، postType، …) خاصية من خصائص input. يُرفض جسم الطلب المسطّح غير المغلّف برمز HTTP 400 (Variable "$input" of required type ... was not provided). وهذا هو عقد الطلب نفسه المستخدم في POST /posts، وتُدرج الاستجابة الناجحة تحت المفتاح createSocialPost بدلًا من مفتاح خاص بالعملية الجماعية.
حالة استخدام: إعلان على مستوى الشركة (موضح أعلاه). اضبط postType: "ANNOUNCEMENT"، وأدرج معرّفات المواقع، وقدّم postMessage واحدًا لكل منصة. أضف postScheduledDates لتشغيل المنشور خلال فترة زمنية محددة (يُنشأ المنشور حينئذٍ بالحالة SCHEDULED)؛ أو احذفه للنشر فورًا.
حالة استخدام: عرض لفترة محدودة في جميع المتاجر. غيّر postType إلى OFFER وقدّم القسيمة في postContextInfo (مع الإبقاء على التغليف داخل input):
{ "input": { "postName": "Summer 20% Off", "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="], "postType": "OFFER", "postSites": ["GOOGLE"], "postMessage": [{ "site": "GOOGLE", "message": "20% off through July!" }], "postContextInfo": { "title": "Summer Sale", "couponCode": "SUMMER20", "redeemUrl": "https://example.com/offer", "termsConditions": "Valid through July 31", "startDay": "2026-07-10", "startTime": "09:00", "endDay": "2026-07-31", "endTime": "23:59" } }}نقاط يجب الانتباه إليها.
- يجب تغليف جسم الطلب داخل
input؛ ويؤدي إرسال الحقول في المستوى الأعلى إلى إرجاع رمز HTTP 400. - الحقول
postTypeوpostSitesوpostNameوlocationIdsمطلوبة؛ وتتطلب الأنواعEVENTوOFFERوPRODUCTأيضًا حقولpostContextInfo(أوproducts) المطابقة. - لا يقبل
postSitesإلاGOOGLEوFACEBOOK؛ ويجب أن تكون القناة المقابلة متصلة بالمواقع المستهدفة، وإلا فستُتخطّى تلك المنصة. - تُرجع الاستجابة رمز HTTP 200 مع
success: falseومصفوفةerrorsتحتوي على عناصر عند فشل التحقق جزئيًا أو كليًا، فتحقّق منsuccess، ثم تتبّع التسليم الفعلي لكل موقع باستخدام نقطة نهاية جلب المنشور الجماعي.
Request
curl -X POST 'https://listingsapi.com/api/v4/bulk-posts' \ -H "Authorization: API $LISTINGSAPI_KEY" \ -H 'Content-Type: application/json' \ -d '{ "input": { "postName": "July Reopening Announcement", "locationIds": [ "TG9jYXRpb246MTgwMDI4OQ==", "TG9jYXRpb246MTgwMDI5MA==" ], "postType": "ANNOUNCEMENT", "postSites": [ "GOOGLE", "FACEBOOK" ], "postMessage": [ { "site": "GOOGLE", "message": "We're back! Visit us this week for our summer menu." }, { "site": "FACEBOOK", "message": "We're back! Swing by for the new summer menu." } ], "postMediaUrl": [ { "site": "GOOGLE", "url": "https://cdn.example.com/summer.jpg", "type": "IMAGE" } ], "postScheduledDates": { "startDatetime": "2026-07-10T09:00:00Z", "endDatetime": "2026-07-24T23:59:00Z" } } }'