Listings APIListings API
تسجيل الدخول
POST/api/v4/posts

إنشاء منشور فعالية

ينشئ منشورًا اجتماعيًا من نوع EVENT بعنوان وفترة زمنية محددة للبداية والنهاية، ويُنشر على المنصات المختارة لموقع واحد أو أكثر.

يتطلب مفتاح API. راجع المصادقة لمعرفة تنسيق الترويسة وتدوير المفاتيح.

المعلمات

النص الأساسي

الاسمالنوعمطلوبالوصف
inputobjectمطلوبWrapper object. Every field below is a property of `input`, the entire body must be nested under it.
input.postNamestringمطلوبInternal name for the campaign (not shown to customers).
input.locationIdsarray of stringsمطلوبBase64-encoded location IDs to publish to (e.g. `TG9jYXRpb246MTgwMDI4OQ==`).
input.postTypestringمطلوبMust be `EVENT`. One of EVENT, OFFER, ANNOUNCEMENT, COVID19, PRODUCT.
input.postSitesarray of stringsمطلوبSites to publish to: `GOOGLE`, `FACEBOOK`.
input.postContextInfoobjectاختياريEvent details: `{ title, startDay, startTime, endDay, endTime }`. `title` is required by Google for events; `startDay`/`endDay` are dates, `startTime`/`endTime` are display strings like `10:00am`.
input.postMessagearray of objectsاختياريPer-site body text: `{ site, message }`. One entry per site in `postSites`.
input.postScheduledDatesobjectاختياريWhen to publish/expire the post itself: `{ startDatetime, endDatetime, removalSites }`. Distinct from the event's own dates in `postContextInfo`.
input.postCtaarray of objectsاختياريOptional call-to-action per site: `{ site, type, url }`. `type` is one of BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, GET_OFFER.
input.postMediaUrlarray of objectsاختياريOptional media per site: `{ site, url, type }` where `type` is IMAGE or VIDEO.
input.clientMutationIdstringاختياريOptional client token returned unchanged in the response for correlation.

مثال على الطلب

نص جاهز للصق. استبدل المعرّفات والقيم النموذجية بقيمك.

Request body
{  "input": {    "postName": "Summer Sale Kickoff Event",    "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="],    "postType": "EVENT",    "postSites": ["GOOGLE"],    "postContextInfo": {      "title": "Summer Sale Kickoff",      "startDay": "2026-07-15",      "startTime": "10:00am",      "endDay": "2026-07-15",      "endTime": "06:00pm"    },    "postMessage": [      { "site": "GOOGLE", "message": "Join us for the Summer Sale kickoff, refreshments, giveaways, and up to 40% off in store." }    ],    "postCta": [      { "site": "GOOGLE", "type": "LEARN_MORE", "url": "https://jennyhome.example/summer-event" }    ],    "postMediaUrl": [      { "site": "GOOGLE", "url": "https://cdn.example.com/summer-event.jpg", "type": "IMAGE" }    ]  }}

الاستجابات

200Post accepted. Publishing runs asynchronously, the returned post starts as INPROGRESS.
Response
{  "data": {    "createSocialPost": {      "clientMutationId": null,      "success": true,      "errors": [],      "socialPost": {        "id": "U29jaWFsUG9zdDo0NDEyMw==",        "name": "Summer Sale Kickoff Event",        "status": "INPROGRESS",        "type": "EVENT",        "createdAt": "2026-07-01",        "scheduledStartDate": "2026-07-15",        "scheduledEndDate": "2026-07-15",        "sites": ["GOOGLE"],        "message": [          { "site": "GOOGLE", "message": "Join us for the Summer Sale kickoff, refreshments, giveaways, and up to 40% off in store." }        ],        "cta": [          { "type": { "value": "LEARN_MORE", "label": "Learn more" }, "url": "https://jennyhome.example/summer-event", "site": "GOOGLE", "tinyUrl": null }        ],        "contextInfo": {          "title": "Summer Sale Kickoff",          "startDay": "2026-07-15",          "startTime": "10:00am",          "endDay": "2026-07-15",          "endTime": "06:00pm",          "couponCode": null,          "redeemUrl": null,          "termsConditions": null,          "discount": null,          "locationType": null        },        "mediaUrl": [          { "url": "https://cdn.example.com/summer-event.jpg", "site": "GOOGLE", "type": "IMAGE" }        ],        "publishDetails": [          { "site": "GOOGLE", "status": "PUBLISHING", "createdDate": "2026-07-01", "submissionError": null }        ],        "postLinks": [],        "locationIds": [1800289]      }    }  }}
400Bad request, the body was not wrapped in `input` (error message: `Variable "$input" of required type "CreateSocialPostMutationInput!" was not provided`).
401Unauthenticated, missing or invalid API key.

ينشئ منشور فعالية: إعلانًا مؤرخًا يتضمن title وفترة زمنية محددة للبداية والنهاية، ويظهر كبطاقة فعالية على Google. يُحدَّد الجدول الزمني للفعالية نفسها في postContextInfo (title، startDay، startTime، endDay، endTime)؛ أما postScheduledDates الاختياري فيتحكم في موعد نشر المنشور نفسه وإزالته، وتكون فترة نشره عادةً خلال الفترة التي تسبق الفعالية.

حالة استخدام: الترويج لفعالية داخل المتجر. أعلن عن "انطلاق تخفيضات الصيف" لدى Jenny Home مع تحديد فترة الفعالية في 15 يوليو وإضافة دعوة لاتخاذ إجراء من نوع LEARN_MORE تؤدي إلى صفحة الفعالية. اضبط postType: "EVENT" واملأ postContextInfo.title، إذ يرفض Google الفعاليات التي ليس لها عنوان. يُرجع الاستدعاء status: INPROGRESS؛ تحقّق باستخدام GET /posts/{postId} من وصوله إلى SUCCESS.

ملاحظات.

  • يجب تغليف جسم الطلب داخل كائن input: كل حقل هو خاصية من خصائص input. يُرفض جسم الطلب المسطح وغير المغلَّف برمز حالة HTTP 400 (Variable "$input" of required type "CreateSocialPostMutationInput!" was not provided).
  • يحتوي postContextInfo على تواريخ الفعالية؛ ويحتوي postScheduledDates على تواريخ النشر. استخدم postScheduledDates.startDatetime/endDatetime لجدولة المنشور مسبقًا وإنهاء صلاحيته تلقائيًا بعد الفعالية.
  • قدّم عنصرًا في postMessage لكل منصة في postSites.
  • لرسالة عادية بلا تواريخ، استخدم الإعلانات؛ وللقسائم أو الخصومات، استخدم العروض.

عملية كتابة: لم تُنفَّذ على الحساب الفعلي. أُنشئ الطلب والاستجابة المعروضان استنادًا إلى مخطط API؛ وعند تنفيذ هذا الطلب، فإنه ينشر على ملفات تعريف حقيقية على Google/Facebook.

Request
curl -X POST 'https://listingsapi.com/api/v4/posts' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "postName": "Summer Sale Kickoff Event",      "locationIds": [        "TG9jYXRpb246MTgwMDI4OQ=="      ],      "postType": "EVENT",      "postSites": [        "GOOGLE"      ],      "postContextInfo": {        "title": "Summer Sale Kickoff",        "startDay": "2026-07-15",        "startTime": "10:00am",        "endDay": "2026-07-15",        "endTime": "06:00pm"      },      "postMessage": [        {          "site": "GOOGLE",          "message": "Join us for the Summer Sale kickoff, refreshments, giveaways, and up to 40% off in store."        }      ],      "postCta": [        {          "site": "GOOGLE",          "type": "LEARN_MORE",          "url": "https://jennyhome.example/summer-event"        }      ],      "postMediaUrl": [        {          "site": "GOOGLE",          "url": "https://cdn.example.com/summer-event.jpg",          "type": "IMAGE"        }      ]    }  }'
Run in playground