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

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

ينشئ منشورًا اجتماعيًا من نوع OFFER يتضمن قسيمة وخصمًا وشروطًا، ويُنشر على المنصات المختارة لموقع واحد أو أكثر.

يتطلب مفتاح 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 `OFFER`. One of EVENT, OFFER, ANNOUNCEMENT, COVID19, PRODUCT.
input.postSitesarray of stringsمطلوبSites to publish to: `GOOGLE`, `FACEBOOK`.
input.postContextInfoobjectاختياريOffer details: `{ title, couponCode, discount, redeemUrl, termsConditions, startDay, endDay }`. `title` labels the offer; `startDay`/`endDay` bound its validity.
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 offer validity in `postContextInfo`.
input.postCtaarray of objectsاختياريOptional call-to-action per site: `{ site, type, url }`. The `CTAType` enum accepts BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, and GET_OFFER. There is no `REDEEM`. For offer posts, Google takes ORDER and Facebook takes 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": "Diwali 25% Off",    "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="],    "postType": "OFFER",    "postSites": ["GOOGLE"],    "postContextInfo": {      "title": "25% off storewide",      "couponCode": "DIWALI25",      "discount": "25%",      "redeemUrl": "https://jennyhome.example/diwali",      "termsConditions": "Valid in-store only through July 6. Cannot be combined with other offers.",      "startDay": "2026-06-22",      "endDay": "2026-07-06"    },    "postMessage": [      { "site": "GOOGLE", "message": "Celebrate with us: 25% off everything in store this festive week." }    ],    "postCta": [      { "site": "GOOGLE", "type": "GET_OFFER", "url": "https://jennyhome.example/diwali" }    ],    "postMediaUrl": [      { "site": "GOOGLE", "url": "https://cdn.example.com/diwali.jpg", "type": "IMAGE" }    ]  }}

الاستجابات

200Post accepted. Publishing runs asynchronously, the returned post starts as INPROGRESS.
Response
{  "data": {    "createSocialPost": {      "clientMutationId": null,      "success": true,      "errors": [],      "socialPost": {        "id": "U29jaWFsUG9zdDo0NDEyNA==",        "name": "Diwali 25% Off",        "status": "INPROGRESS",        "type": "OFFER",        "createdAt": "2026-06-20",        "scheduledStartDate": "2026-06-22",        "scheduledEndDate": "2026-07-06",        "sites": ["GOOGLE"],        "message": [          { "site": "GOOGLE", "message": "Celebrate with us: 25% off everything in store this festive week." }        ],        "cta": [          { "type": { "value": "GET_OFFER", "label": "Get offer" }, "url": "https://jennyhome.example/diwali", "site": "GOOGLE", "tinyUrl": null }        ],        "contextInfo": {          "title": "25% off storewide",          "couponCode": "DIWALI25",          "discount": "25%",          "redeemUrl": "https://jennyhome.example/diwali",          "termsConditions": "Valid in-store only through July 6. Cannot be combined with other offers.",          "startDay": "2026-06-22",          "endDay": "2026-07-06",          "startTime": null,          "endTime": null,          "locationType": null        },        "mediaUrl": [          { "url": "https://cdn.example.com/diwali.jpg", "site": "GOOGLE", "type": "IMAGE" }        ],        "publishDetails": [          { "site": "GOOGLE", "status": "PUBLISHING", "createdDate": "2026-06-20", "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.

ينشئ منشور عرض: بطاقة ترويجية تتضمن رمز قسيمة وخصمًا ورابطًا للاستفادة من العرض وشروطًا. ترد تفاصيل العرض في postContextInfo (title، couponCode، discount، redeemUrl، termsConditions، startDay، endDay). تتناسب العروض بطبيعتها مع دعوة لاتخاذ إجراء من نوع GET_OFFER.

حالة استخدام: تشغيل حملة ترويجية محددة المدة. أطلق عرض "خصم 25% بمناسبة ديوالي" لصالح Jenny Home يسري من 22 يونيو إلى 6 يوليو، مع القسيمة DIWALI25 وعنوان URL للاستفادة من العرض. اضبط postType: "OFFER"، واملأ postContextInfo، وأضف دعوة لاتخاذ إجراء من نوع GET_OFFER. يُرجع الاستدعاء status: INPROGRESS؛ تحقّق من ظهور المنشور على كل منصة باستخدام GET /posts/{postId}، واحذفه مبكرًا باستخدام DELETE /posts/{postId} إذا انتهت الحملة الترويجية.

ملاحظات.

  • يجب تغليف جسم الطلب داخل كائن input: كل حقل هو خاصية للكائن input. يُرفض الجسم المسطح غير المغلّف برمز حالة HTTP 400 (Variable "$input" of required type "CreateSocialPostMutationInput!" was not provided).
  • يحدد postContextInfo.startDay/endDay فترة سريان العرض؛ استخدم postScheduledDates إذا أردت أيضًا جدولة موعد نشر المنشور وانتهاء صلاحيته بصورة مستقلة.
  • وفّر عنصر 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": "Diwali 25% Off",      "locationIds": [        "TG9jYXRpb246MTgwMDI4OQ=="      ],      "postType": "OFFER",      "postSites": [        "GOOGLE"      ],      "postContextInfo": {        "title": "25% off storewide",        "couponCode": "DIWALI25",        "discount": "25%",        "redeemUrl": "https://jennyhome.example/diwali",        "termsConditions": "Valid in-store only through July 6. Cannot be combined with other offers.",        "startDay": "2026-06-22",        "endDay": "2026-07-06"      },      "postMessage": [        {          "site": "GOOGLE",          "message": "Celebrate with us: 25% off everything in store this festive week."        }      ],      "postCta": [        {          "site": "GOOGLE",          "type": "GET_OFFER",          "url": "https://jennyhome.example/diwali"        }      ],      "postMediaUrl": [        {          "site": "GOOGLE",          "url": "https://cdn.example.com/diwali.jpg",          "type": "IMAGE"        }      ]    }  }'
Run in playground