Listings APIListings API
로그인
POST/api/v4/social/posts

소셜 게시물 만들기

브랜드에 연결된 Facebook, Instagram, X, LinkedIn 및 Pinterest 계정에 초안, 예약 또는 즉시 게시되는 게시물을 만듭니다.

API 키가 필요합니다. 헤더 형식과 키 교체는 인증을 참고하세요.

매개변수

본문

이름유형필수설명
inputobject필수Wrapper object. Every field below is a property of `input`, the entire body must be nested under it.
input.socialProfileIdstring필수UUID of the brand publishing the post, the same value used as the `brandId` path token elsewhere. Every platform in `platforms` must already have a connection on this brand.
input.namestring필수Internal name for the post (not shown to the audience). Used to find it again in lists.
input.platformsarray of strings필수Platforms to publish to: `FACEBOOK`, `INSTAGRAM`, `TWITTER` (X), `LINKEDIN`, `PINTEREST`.
input.contentstring필수The post body, published to every platform in `platforms`.
input.actionstring필수`DRAFT` to save without publishing, `SCHEDULE` to publish at a future time (requires a schedule), or `PUBLISH` to publish now.
input.mediaUrlsarray of strings선택Public https image URLs to attach. Instagram and Pinterest require at least one.
input.videoUrlsarray of strings선택Public https video URLs to attach.
input.linkstring선택Link to attach to the post where the platform supports one.
input.scheduledAtstring선택Publish time as an ISO-8601 timestamp with an offset, e.g. `2026-10-02T09:30:00-04:00`. Required when `action` is `SCHEDULE` unless you send `scheduleDate` + `scheduleTime`. Never send both forms.
input.scheduleDatestring선택Publish date as `YYYY-MM-DD`, interpreted in the **brand's** timezone. Must be sent together with `scheduleTime`.
input.scheduleTimestring선택Publish time as `HH:MM` (24-hour), interpreted in the **brand's** timezone. Must be sent together with `scheduleDate`.
input.connectedChannelIdsarray of strings선택Restrict publishing to specific connections by their `id` from the connections list. Defaults to the brand's active connection for each platform in `platforms`.
input.clientReferencestring선택Your own identifier for this post, stored and echoed back. Use it to reconcile the post against your own records without holding onto the returned UUID.

요청 예시

바로 붙여 넣을 수 있는 본문입니다. 예시 ID와 값을 실제 값으로 바꾸세요.

Request body
{  "input": {    "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",    "name": "Autumn collection launch",    "platforms": ["INSTAGRAM", "FACEBOOK", "LINKEDIN"],    "content": "Our autumn collection lands today. Solid oak, hand-finished, made two blocks from the shop. Come see it in person this weekend.",    "mediaUrls": ["https://cdn.example.com/social/autumn-collection.jpg"],    "link": "https://jennyhome.example/autumn",    "action": "SCHEDULE",    "scheduleDate": "2026-10-02",    "scheduleTime": "09:30",    "clientReference": "campaign-4471-slot-01"  }}

응답

200Post accepted. Publishing runs asynchronously, poll GET /social/posts/{postId} for per-channel status.
Response
{  "data": {    "createSimpleSocialMediaPost": {      "success": true,      "error": [],      "socialPostId": "c47a1e58-2b93-4f10-a6d7-58e0c9b12345",      "status": "SCHEDULED"    }  }}
200Validation failed. Nothing was created. The status is still 200: read `success` and the `error` array.
Response
{  "data": {    "createSimpleSocialMediaPost": {      "success": false,      "error": [        {          "message": "SY95045: No connected channel for PINTEREST on this brand",          "code": "SY95045",          "contextInfo": [{ "key": "platform", "value": "PINTEREST" }]        },        {          "message": "SY95046: scheduleTime must be HH:MM in the brand's timezone",          "code": "SY95046",          "contextInfo": null        }      ],      "socialPostId": null,      "status": null    }  }}
401Unauthenticated, missing or invalid API key.
404No brand with that ID on this account (`SY95043`).

브랜드 1개의 연결된 소셜 계정 중 하나 이상에 게시물 1개를 만듭니다. 동일한 호출로 DRAFT 저장, SCHEDULE 대기열 추가, 즉시 PUBLISH의 3가지 처리 방식을 모두 지원합니다.

사용 사례: 자체 캘린더에서 캠페인 예약하기. 앱은 고객이 전달하려는 내용과 시점을 이미 알고 있습니다. 각 예약 슬롯에 대해 action: "SCHEDULE"과 함께 scheduledAt 또는 scheduleDate + scheduleTime을 지정하여 이 엔드포인트를 호출하고, 반환된 UUID를 저장하지 않고도 대조할 수 있도록 자체 슬롯 식별자를 clientReference로 전달합니다. GET /social/posts/{postId}에서 모든 채널에 게시가 완료되었다고 보고할 때까지 항목을 대기 중으로 표시하고, POST /social/posts/cancel에 연결된 취소 버튼을 제공합니다.

게시는 비동기로 처리됩니다

action: "PUBLISH"는 응답을 반환하기 전에 게시를 완료하지 않습니다. 이 호출은 게시물을 접수하고 socialPostId를 반환한 다음 게시 파이프라인에 전달합니다. 실제 처리 결과를 확인하려면 GET /social/posts/{postId}를 폴링하고 채널별 channels[] 배열을 읽습니다. 각 항목의 status는 해당 플랫폼 하나의 처리 결과입니다. 동일한 요청에서도 Instagram에서는 게시에 성공하고 LinkedIn에서는 실패할 수 있으므로, channels[]가 실제 결과이며 게시물 수준의 status는 요약입니다.

예약 방식 선택

action: "SCHEDULE"에는 다음 2가지 형식 중 정확히 하나가 필요하며, 둘 다 지정할 수는 없습니다.

형식필드해석에 사용하는 기준
절대 시점scheduledAt, 오프셋이 포함된 ISO-8601(2026-10-02T09:30:00-04:00)전송한 오프셋
현지 시각scheduleDate(YYYY-MM-DD) 및 scheduleTime(HH:MM)브랜드의 시간대

두 형식을 모두 전송하거나, scheduleTime 없이 scheduleDate를 전송하거나, 오프셋 없이 scheduledAt을 전송하면 SY95046으로 거부됩니다. DRAFT와 PUBLISH에는 예약 정보를 전혀 포함해서는 안 됩니다.

참고 사항.

  • 요청 본문은 반드시 input 객체로 감싸야 합니다.
  • HTTP 상태가 아닌 success를 확인합니다. 유효성 검사에 실패하면 HTTP 200과 함께 success: false가 반환되며, error 배열에는 문제마다 항목이 1개씩 포함됩니다. success가 false이면 아무것도 생성되지 않습니다.
  • 본문에서는 socialProfileId로 브랜드를 식별합니다. brandId는 항상 URL 경로 토큰으로만 사용되며, 본문 필드로는 사용되지 않습니다.
  • platforms의 모든 플랫폼은 이미 브랜드에 연결되어 있어야 합니다. 활성 채널이 없는 플랫폼은 SY95045로 실패합니다. 먼저 브랜드의 연결 정보를 확인하고, 연결이 누락된 플랫폼은 사용자가 연결 링크를 통해 연결하도록 안내합니다.
  • 플랫폼 값은 대문자 enum 이름인 FACEBOOK, INSTAGRAM, TWITTER, LINKEDIN, PINTEREST입니다. TWITTER는 X를 나타냅니다. 값에는 이전 이름이 유지되었으며, 소문자 값은 거부됩니다.
  • Instagram과 Pinterest는 텍스트만 있는 게시물을 허용하지 않습니다. 둘 중 하나라도 platforms에 포함되어 있으면 mediaUrls 항목을 1개 이상 제공해야 합니다.
  • 게시물 ID는 일반 UUID이며, 사업장 게시물에 사용되는 Base64 relay ID가 아닙니다.
  • 한 번에 여러 게시물을 만들려면 POST /social/bulk-posts를 사용합니다. 이 엔드포인트는 동일한 행 구조를 사용하며, 전체 배치의 유효성을 사전에 검사합니다.

쓰기 작업: 실제 계정에서는 실행하지 않았습니다. 표시된 요청과 응답은 API 스키마를 바탕으로 구성했으며, 실행하면 실제 소셜 계정에 게시됩니다.

Request
curl -X POST 'https://listingsapi.com/api/v4/social/posts' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",      "name": "Autumn collection launch",      "platforms": [        "INSTAGRAM",        "FACEBOOK",        "LINKEDIN"      ],      "content": "Our autumn collection lands today. Solid oak, hand-finished, made two blocks from the shop. Come see it in person this weekend.",      "mediaUrls": [        "https://cdn.example.com/social/autumn-collection.jpg"      ],      "link": "https://jennyhome.example/autumn",      "action": "SCHEDULE",      "scheduleDate": "2026-10-02",      "scheduleTime": "09:30",      "clientReference": "campaign-4471-slot-01"    }  }'
Run in playground