GET/api/v4/bulk-posts/{postId}

جلب منشور جماعي حسب المعرّف

يُرجع حملة منشورات جماعية واحدة (لمواقع متعددة)، مع محتواها وحالة النشر لكل موقع وتحليلات التفاعل.

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

المعلمات

المسار

الاسمالنوعمطلوبالوصف
postIdstringمطلوبBase64-encoded bulk post ID (the `id` returned by POST /bulk-posts or listed by GET /locations/{locationId}/bulk-posts).

الاستجابات

200The campaign's content, per-location publish details, and analytics.
Response
{  "data": {    "socialPostView": {      "socialPostId": "U29jaWFsUG9zdDo1MTA4OA==",      "socialPostInfo": {        "id": "U29jaWFsUG9zdDo1MTA4OA==",        "name": "Diwali Offer - All Stores",        "status": "SUCCESS",        "type": "OFFER",        "createdAt": "2026-06-20",        "scheduledStartDate": "2026-06-22",        "scheduledEndDate": "2026-07-06",        "views": 4210,        "clicks": 318,        "shares": 12,        "reactions": 87,        "comments": 4,        "sites": ["GOOGLE", "FACEBOOK"],        "message": [          { "site": "GOOGLE", "message": "Festive savings across all our stores this week." },          { "site": "FACEBOOK", "message": "Festive savings across all our stores this week!" }        ],        "cta": [          { "type": { "value": "GET_OFFER", "label": "Get offer" }, "url": "https://jennyhome.example/diwali", "site": "GOOGLE", "tinyUrl": "https://tiny.cc/jh-diwali" }        ],        "contextInfo": {          "couponCode": "DIWALI25",          "redeemUrl": "https://jennyhome.example/diwali",          "termsConditions": "Valid in-store only. Cannot be combined with other offers.",          "title": "25% off storewide",          "discount": "25%",          "startDay": "2026-06-22",          "endDay": "2026-07-06"        },        "mediaUrl": [          { "url": "https://cdn.listingsapi.com/posts/51088/diwali.jpg", "site": "GOOGLE", "type": "IMAGE" }        ],        "publishDetails": [          { "site": "GOOGLE", "status": "PUBLISHED", "createdDate": "2026-06-20", "publishedDate": "2026-06-22", "submissionError": null },          { "site": "FACEBOOK", "status": "PUBLISHED", "createdDate": "2026-06-20", "publishedDate": "2026-06-22", "submissionError": null }        ],        "postLinks": [          { "site": "GOOGLE", "link": "https://www.google.com/maps/place/?post=51088" }        ],        "locationIds": [1800289, 1800290, 1800291]      },      "publishedLocationsCount": 3,      "socialPostAnalyticsBySite": [        { "site": "GOOGLE", "views": 3120, "clicks": 240, "reactions": 61, "shares": 0, "comments": 0 },        { "site": "FACEBOOK", "views": 1090, "clicks": 78, "reactions": 26, "shares": 12, "comments": 4 }      ],      "socialPostAnalyticsByLocationId": [        {          "locationId": 1800289,          "siteStats": [            { "site": "GOOGLE", "status": "PUBLISHED", "views": 1040, "clicks": 80, "reactions": 20, "shares": 0, "comments": 0 },            { "site": "FACEBOOK", "status": "PUBLISHED", "views": 360, "clicks": 26, "reactions": 9, "shares": 4, "comments": 1 }          ]        }      ]    }  }}
401Unauthenticated, missing or invalid API key.

النظير الجماعي لـ GET /posts/{postId}. يُرجع بنية SocialPostView نفسها لحملة نُشرت في مواقع متعددة في آن واحد، لذا تكون قيمة publishedLocationsCount أكبر من 1، ويتضمن socialPostAnalyticsByLocationId صفًا لكل متجر.

حالة استخدام: تتبّع نشر حملة على مستوى سلسلة المتاجر بأكملها. بعد استدعاء POST /bulk-posts لنشر عرض احتفالي في جميع المتاجر، استدعِ GET /bulk-posts/{postId} دوريًا حتى تصبح قيمة socialPostInfo.status هي SUCCESS. ثم اقرأ socialPostAnalyticsByLocationId لمعرفة المتاجر التي حققت أكبر عدد من النقرات، وافحص publishDetails (بالإضافة إلى siteStats.status لكل موقع) للعثور على أي متجر أعادت فيه إحدى المنصات ERROR.

ملاحظات.

  • postId هو id المُرمَّز باستخدام Base64 الذي يُرجعه استدعاء الإنشاء الجماعي أو القائمة الجماعية، وليس عددًا صحيحًا خامًا.
  • يجمع socialPostAnalyticsBySite البيانات من جميع المواقع في الحملة؛ ويُفصّل socialPostAnalyticsByLocationId الأرقام نفسها لكل متجر.

أُنشئ هذا المثال استنادًا إلى مخطط API. لا يحتوي الحساب الفعلي المستخدم للبيانات الأولية (Jenny Home) على أي حملات جماعية، لذا لم يكن هناك معرّف حقيقي يمكن استخدامه للجلب؛ ويؤدي استخدام معرّف غير معروف أو غير صالح إلى إرجاع {"data":null,"errors":[{"message":"An error occurred processing your request."}]}.

Request
curl -X GET 'https://listingsapi.com/api/v4/bulk-posts/<postId>' \  -H "Authorization: API $LISTINGSAPI_KEY"