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

إنشاء منشور إعلان

ينشئ منشورًا اجتماعيًا من النوع ANNOUNCEMENT وينشره على المنصات المختارة لموقع واحد أو أكثر.

يتطلب مفتاح 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 `ANNOUNCEMENT`. One of EVENT, OFFER, ANNOUNCEMENT, COVID19, PRODUCT.
input.postSitesarray of stringsمطلوبSites to publish to: `GOOGLE`, `FACEBOOK`.
input.postMessagearray of objectsاختياريPer-site body text: `{ site, message }`. Provide one entry per site in `postSites`.
input.postCtaarray of objectsاختياريOptional call-to-action button 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": "Grand Opening Announcement",    "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="],    "postType": "ANNOUNCEMENT",    "postSites": ["GOOGLE"],    "postMessage": [      { "site": "GOOGLE", "message": "We are now open! Visit Jenny Home this week for our grand opening." }    ],    "postCta": [      { "site": "GOOGLE", "type": "LEARN_MORE", "url": "https://jennyhome.example/opening" }    ],    "postMediaUrl": [      { "site": "GOOGLE", "url": "https://cdn.example.com/opening.jpg", "type": "IMAGE" }    ]  }}

الاستجابات

200Post accepted. Publishing runs asynchronously, the returned post starts as INPROGRESS.
Response
{  "data": {    "createSocialPost": {      "clientMutationId": null,      "success": true,      "errors": [],      "socialPost": {        "id": "U29jaWFsUG9zdDo0NDEyMg==",        "name": "Grand Opening Announcement",        "status": "INPROGRESS",        "type": "ANNOUNCEMENT",        "createdAt": "2026-06-28",        "sites": ["GOOGLE"],        "message": [          { "site": "GOOGLE", "message": "We are now open! Visit Jenny Home this week for our grand opening." }        ],        "cta": [          { "type": { "value": "LEARN_MORE", "label": "Learn more" }, "url": "https://jennyhome.example/opening", "site": "GOOGLE", "tinyUrl": null }        ],        "contextInfo": null,        "mediaUrl": [          { "url": "https://cdn.example.com/opening.jpg", "site": "GOOGLE", "type": "IMAGE" }        ],        "publishDetails": [          { "site": "GOOGLE", "status": "PUBLISHING", "createdDate": "2026-06-28", "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.

ينشئ إعلانًا: وهو أبسط أنواع المنشورات. يتضمن الإعلان رسالة نصية بسيطة (مع دعوة اختيارية لاتخاذ إجراء وصورة اختيارية) دون تواريخ فعاليات أو تفاصيل عروض. مرّر postType: "ANNOUNCEMENT" ومدخل postMessage واحدًا لكل منصة في postSites.

حالة استخدام: الإعلان عن "بدء العمل" في متاجرك. أعلن عن افتتاح رسمي أو ساعات عمل جديدة على Google (وFacebook) لمجموعة من المواقع في استدعاء واحد. قدّم دعوة لاتخاذ إجراء من النوع LEARN_MORE ترتبط بموقعك الإلكتروني وصورة لإثراء بطاقة المنشور. يعيد الاستدعاء النتيجة فورًا مع status: INPROGRESS؛ استعلم دوريًا عن GET /posts/{postId} باستخدام socialPost.id المُعاد حتى تصبح قيمته SUCCESS، واقرأ publishDetails[].submissionError إذا فشل النشر على أي منصة.

ملاحظات.

  • يجب تغليف جسم الطلب داخل كائن input: كل حقل (postName، locationIds، postType، postSites، …) هو خاصية من خصائص input. يُرفض الجسم المسطح غير المغلّف بحالة HTTP 400 (Variable "$input" of required type "CreateSocialPostMutationInput!" was not provided).
  • يستخدم postSites وكل postMessage.site التعداد الخاص بالمنصة (GOOGLE، FACEBOOK)؛ قدّم مدخل رسالة لكل منصة تستهدفها.
  • لنشر الإعلان نفسه لمواقع عديدة، مرّر جميع المعرّفات في locationIds هنا، أو استخدم POST /bulk-posts لعمليات النشر الواسعة عبر مواقع متعددة.
  • للمنشورات المرتبطة بتواريخ، استخدم الفعاليات؛ وللقسائم/الخصومات، استخدم العروض.

عملية كتابة: لم تُنفَّذ على الحساب الفعلي. أُنشئ الطلب والاستجابة المعروضان استنادًا إلى مخطط 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": "Grand Opening Announcement",      "locationIds": [        "TG9jYXRpb246MTgwMDI4OQ=="      ],      "postType": "ANNOUNCEMENT",      "postSites": [        "GOOGLE"      ],      "postMessage": [        {          "site": "GOOGLE",          "message": "We are now open! Visit Jenny Home this week for our grand opening."        }      ],      "postCta": [        {          "site": "GOOGLE",          "type": "LEARN_MORE",          "url": "https://jennyhome.example/opening"        }      ],      "postMediaUrl": [        {          "site": "GOOGLE",          "url": "https://cdn.example.com/opening.jpg",          "type": "IMAGE"        }      ]    }  }'
Run in playground