POST
/api/v4/posts혜택 게시물 만들기
쿠폰, 할인, 이용 약관이 포함된 OFFER 소셜 게시물을 생성하여 하나 이상의 사업장에 대해 선택한 사이트에 게시합니다.
매개변수
본문
| 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| 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 to customers). |
| input.locationIds | array of strings | 필수 | Base64-encoded location IDs to publish to (e.g. `TG9jYXRpb246MTgwMDI4OQ==`). |
| input.postType | string | 필수 | Must be `OFFER`. One of EVENT, OFFER, ANNOUNCEMENT, COVID19, PRODUCT. |
| input.postSites | array of strings | 필수 | Sites to publish to: `GOOGLE`, `FACEBOOK`. |
| input.postContextInfo | object | 선택 | Offer details: `{ title, couponCode, discount, redeemUrl, termsConditions, startDay, endDay }`. `title` labels the offer; `startDay`/`endDay` bound its validity. |
| input.postMessage | array of objects | 선택 | Per-site body text: `{ site, message }`. One entry per site in `postSites`. |
| input.postScheduledDates | object | 선택 | When to publish/expire the post itself: `{ startDatetime, endDatetime, removalSites }`. Distinct from the offer validity in `postContextInfo`. |
| input.postCta | array 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.postMediaUrl | array of objects | 선택 | Optional media per site: `{ site, url, type }` where `type` is IMAGE or VIDEO. |
| input.clientMutationId | string | 선택 | Optional client token returned unchanged in the response for correlation. |
요청 예시
바로 붙여 넣을 수 있는 본문입니다. 예시 ID와 값을 실제 값으로 바꾸세요.
{ "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.
{ "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 CTA를 함께 사용합니다.
사용 사례: 기간 한정 프로모션 진행하기. _Jenny Home_을 대상으로 6월 22일부터 7월 6일까지 유효한 "디왈리 25% 할인" 혜택을 쿠폰 DIWALI25 및 사용 URL과 함께 게시합니다. postType: "OFFER"를 설정하고, postContextInfo를 작성하고, GET_OFFER CTA를 추가합니다. 호출은 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를 사용합니다.postSites에 있는 각 사이트에 대해postMessage항목을 제공합니다.- 일반적인 업데이트에는 공지를 사용하고, 날짜가 정해진 행사에는 이벤트를 사용합니다.
쓰기 작업: 실제 계정에서는 실행되지 않았습니다. 표시된 요청과 응답은 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" } ] } }'