POST
/api/v4/bulk-posts일괄 게시물 만들기
소셜 게시물 1개를 만들고 단일 요청으로 여러 사업장에 게시합니다.
매개변수
본문
필수로 표시된 중첩 필드는 상위 필드를 보낼 때만 적용됩니다. 상위 필드가 선택 사항이고 이를 생략하면 필수 하위 필드도 적용되지 않습니다.
| 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| 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. |
요청 예시
바로 붙여 넣을 수 있는 본문입니다. 예시 ID와 값을 실제 값으로 바꾸세요.
{ "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"를 설정하고 사업장 ID를 나열한 다음 사이트마다 postMessage를 1개씩 제공합니다. 정해진 기간 동안 게시물을 운영하려면 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만 허용되며, 대상 사업장에 해당 채널이 연결되어 있어야 하고, 연결되어 있지 않으면 해당 사이트는 건너뜁니다.- 검증이 일부 또는 전부 실패하면 응답은
success: false와 항목이 채워진errors배열을 포함한 HTTP 200을 반환하므로,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" } } }'