Social

모든 Social 엔드포인트를 다룹니다. 브랜드, 호스팅된 연결 링크, 단일 및 일괄 게시, 예약, 인사이트, 그리고 이 모든 기능에 적용되는 연결 한도를 설명합니다.

Social API는 Facebook, Instagram, X, LinkedIn, Pinterest에 게시합니다. 전체 모델은 2개의 객체로 구성됩니다. 브랜드는 게시할 때 사용하는 이름, 시간대, 연결된 소셜 계정으로 구성된 게시 주체입니다. 연결은 하나의 플랫폼에서 하나의 브랜드에 연결된, 사용 승인을 받은 소셜 계정 1개입니다. API 요금제에서는 브랜드를 무제한으로 생성할 수 있으며 비용이 들지 않습니다. 요금제에서 사용량을 측정하는 대상은 연결이므로, 연결 한도를 고려하여 설계해야 합니다.

서버에서는 계정을 연결할 수 없습니다. 최종 사용자가 해당 플랫폼에서 연결을 승인해야 하므로, 호스팅된 링크를 요청한 다음 사용자를 해당 링크로 리디렉션합니다. 게시는 비동기 방식으로 처리됩니다. 모든 생성 호출은 게시물이 접수되는 즉시 반환되며, 채널별 결과는 폴링으로 확인합니다.

엔드포인트 한눈에 보기

공통으로 사용하는 값

플랫폼 값은 대문자 열거형 이름입니다. "instagram"을 보내면 거부됩니다. TWITTER는 X를 나타내며, 제품 이름이 바뀌었을 때 열거형 이름은 변경되지 않았습니다.

브랜드 생성

POST /social/brands

profileName과 timezone은 필수입니다. 시간대는 객체이며, 중요한 필드는 tzCode입니다. 이 필드는 해당 브랜드의 게시물에 있는 모든 scheduleDate와 scheduleTime을 해석하는 데 사용하는 IANA 식별자입니다. 나머지 3개의 키는 표시용 레이블입니다.

curl -X POST https://listingsapi.com/api/v4/social/brands \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "profileName": "Jenny Home",      "timezone": {        "label": "(GMT-05:00) Eastern Time",        "tzCode": "America/New_York",        "name": "Eastern Standard Time",        "utc": "-05:00"      },      "categories": ["Furniture Store"],      "siteUrl": "https://jennyhome.example"    }  }'

반환된 브랜드 id를 보관합니다. 이 값은 다른 모든 브랜드 엔드포인트에서 brandId 경로 토큰으로 사용되며, 게시할 때는 본문의 socialProfileId 필드로 사용됩니다.

브랜드 목록 및 상세 정보 조회

GET /social/brands는 브랜드 목록을 한 페이지 단위로 반환합니다. GET /social/brands/{brandId}는 브랜드 1개의 전체 상세 정보를 반환합니다.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/brands?page=1&size=25"

조회 시 SY95043이 반환되는 id는 이 계정에 속하지 않거나 이미 보관 처리된 브랜드의 id입니다.

브랜드 수정

POST /social/brands/update

브랜드 id는 경로가 아니라 본문에 input.profileId로 넣습니다. 변경할 필드만 전송하며, 생략한 필드는 현재 값을 유지합니다.

curl -X POST https://listingsapi.com/api/v4/social/brands/update \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"profileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "bio": "Handmade furniture for real homes."}}'

브랜드 보관 처리

POST /social/brands/archive

브랜드는 생성된 지 90일이 지나야 보관 처리할 수 있습니다. 그전에는 호출이 SY95051로 거부되며 아무것도 변경되지 않습니다. 브랜드가 이 기간 요건을 충족하면 보관 처리가 즉시 적용되며, 해당 브랜드의 모든 연결도 동시에 보관 처리됩니다.

해당 연결은 즉시 게시를 중단하지만, 수동으로 연결을 해제할 때와 마찬가지로 해당 슬롯은 청구 기간이 끝날 때까지 사용 중인 슬롯 수에 포함됩니다. 보관 처리는 당장 사용 가능한 용량을 확보하는 방법이 아닙니다.

curl -X POST https://listingsapi.com/api/v4/social/brands/archive \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902"}}'

연결 링크 받기

POST /social/brands/{brandId}/connections/link

연결을 추가하는 방법은 이것뿐입니다. 응답에는 expiresIn초 동안 유효한 호스팅된 url이 포함됩니다. 최종 사용자를 이 주소로 리디렉션하면 사용자가 플랫폼에서 권한을 승인한 후 쿼리 문자열에 결과가 포함된 상태로 지정한 redirectUrl로 돌아옵니다. 취소와 성공을 구분하려면 errorUrl을 전달하고, 이 왕복 과정에서 자체 상관관계 값을 유지하려면 state를 전달합니다.

이 본문은 input 래퍼가 없는 평면 구조라는 점에 유의합니다.

curl -X POST https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/connections/link \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "channel": "INSTAGRAM",    "redirectUrl": "https://app.example.com/social/connected",    "errorUrl": "https://app.example.com/social/failed"  }'

{  "data": {    "connectSocialAccount": {      "status": "success",      "url": "https://social.listingsapi.com/connect/start?token=bfac8e06-8d72-4810-9c50-ae7ee12a7b52",      "expiresIn": 900    }  }}

리디렉션하기 전에 status를 확인합니다. failed 응답은 url을 반환하지 않고 title에 사유를 제공하며, 가장 흔한 사유는 연결 수 한도(SY95042) 또는 계정에서 이용할 수 없는 플랫폼(SY95044)입니다.

브랜드의 연결 목록 조회

GET /social/brands/{brandId}/connections

브랜드에 연결된 계정을 반환하며, 각 계정에는 특정 연결로 게시하거나 해당 연결을 해제하는 데 필요한 id가 포함됩니다.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/connections

연결 해제

POST /social/connections/disconnect

위 목록에 있는 연결의 id를 사용합니다. 해당 계정은 즉시 게시를 중단하지만, 사용하던 슬롯은 청구 기간이 끝날 때까지 가용 슬롯 풀로 반환되지 않습니다. 같은 청구 기간 내에 동일한 계정을 동일한 브랜드에 다시 연결하면 해당 슬롯을 재사용하므로 비용이 발생하지 않으며, 다른 브랜드에 연결하면 두 번째 슬롯을 사용합니다.

curl -X POST https://listingsapi.com/api/v4/social/connections/disconnect \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialProfileConnectedChannelId": "b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7"}}'

게시물 게시

POST /social/posts

한 번의 호출로 platforms에 있는 모든 플랫폼에 동일한 콘텐츠를 게시합니다. 각 플랫폼은 해당 브랜드에 이미 연결되어 있어야 하며, 그렇지 않으면 호출이 SY95045를 반환합니다. Instagram과 Pinterest는 mediaUrls에 항목이 최소 1개 있어야 합니다.

게시물을 예약할 때는 2가지 방법 중 하나만 사용하며, 두 방법을 함께 사용해서는 안 됩니다. scheduledAt은 오프셋이 포함된 ISO-8601 타임스탬프입니다. scheduleDate와 scheduleTime은 함께 전송하며 브랜드의 시간대를 기준으로 해석됩니다. 두 방법을 함께 전송하거나 과거 시점으로 예약하면 SY95046이 반환됩니다.

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"],      "content": "Our autumn collection lands today.",      "mediaUrls": ["https://cdn.example.com/social/autumn-collection.jpg"],      "action": "SCHEDULE",      "scheduleDate": "2026-10-02",      "scheduleTime": "09:30",      "clientReference": "campaign-4471-slot-01"    }  }'

clientReference를 자체 식별자로 설정합니다. 이 값은 저장되고 반환되므로 UUID를 따로 보관하지 않아도 게시물을 자체 기록과 대조할 수 있습니다.

게시물 1개 조회

GET /social/posts/{postId}

이 방법으로 게시 성공 여부를 확인합니다. 게시물 자체의 status는 요약 정보이며, 실제 결과는 connectedChannels의 채널별 항목에 있고, 각 항목에는 자체 status와 함께 플랫폼이 게시물을 수락하면 liveLink가, 수락하지 않으면 reason 또는 error가 포함됩니다.

{  "connectedChannels": [    {      "platform": "INSTAGRAM",      "status": "SUCCESS",      "liveLink": "https://www.instagram.com/p/CxYz1234abc/",      "error": null    }  ]}

PUBLISH 이후에 이 조회를 폴링합니다. 다른 채널이 성공하더라도 한 채널은 실패할 수 있으므로, 최상위 status만 확인하지 말고 모든 항목을 확인합니다.

브랜드의 게시물 목록 조회

GET /social/brands/{brandId}/posts

브랜드의 게시물을 페이지 단위로 제공하며, 상태별로 범위를 좁힐 수 있는 필터를 지원합니다. id를 하나씩 폴링하는 대신 이를 사용하여 일괄적으로 상태를 대조합니다.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/posts?page=1&size=25"

예약된 게시물 취소

POST /social/posts/cancel

아직 게시되지 않은 게시물을 취소합니다. 플랫폼에 이미 게시된 게시물은 이 엔드포인트를 통해 회수할 수 없습니다.

curl -X POST https://listingsapi.com/api/v4/social/posts/cancel \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialPostId": "a3f81c62-9d4e-4a17-b5c0-2e7f6d8a9b10"}}'

인사이트 및 댓글 조회

GET /social/posts/{postId}/insights

하나의 채널에 있는 하나의 게시물에 대한 참여 수치와 댓글을 제공합니다. 3개의 플랫폼에 게시한 게시물에는 각각 별도의 수치 집합이 있으므로 채널은 필수입니다.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/posts/a3f81c62-9d4e-4a17-b5c0-2e7f6d8a9b10/insights?socialConnectedChannelId=b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7"

게시물 일괄 생성

POST /social/bulk-posts

input.posts로 1~500개의 행을 받습니다. 각 행은 POST /social/posts가 input으로 받는 것과 동일한 객체이며, 같은 요청 안에서도 행마다 서로 다른 브랜드를 대상으로 할 수 있습니다.

어떤 항목도 생성하기 전에 전체 배치를 검증합니다. 하나라도 검증에 실패한 행이 있으면 행별 오류와 함께 SY95050이 반환되고 아무것도 대기열에 추가되지 않으므로, 수정한 후 다시 전송합니다. 행이 500개를 초과하면 SY95048이 반환되며, 이 경우에도 아무것도 생성되지 않습니다. 유효한 배치는 폴링할 작업을 반환합니다.

curl -X POST https://listingsapi.com/api/v4/social/bulk-posts \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "name": "October launch batch",      "posts": [        {          "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",          "name": "Launch day",          "platforms": ["FACEBOOK"],          "content": "Doors open at nine.",          "action": "SCHEDULE",          "scheduleDate": "2026-10-02",          "scheduleTime": "09:00"        }      ]    }  }'

일괄 요청은 요청 빈도 제한에서 1개의 요청으로 계산되므로, 대규모 배치를 효율적으로 처리할 수 있습니다.

일괄 작업 폴링

GET /social/bulk-posts/{bulkJobId}

각 행에 대해 생성된 게시물 id와 대기열에 추가된 후 실패한 행을 포함하여, 행별 결과와 함께 작업 상태를 반환합니다. 작업은 영구적으로 보관되지 않으며, 보관 기간이 지난 id로 조회하면 SY95047이 반환됩니다.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/bulk-posts/f47ac10b-58cc-4372-a567-0e02b2c3d479

한도 및 사용량 확인

GET /social/limits

SY95042가 반환된 후가 아니라 연결을 생성하기 전에 이 정보를 조회합니다. usage.connections를 maxConnections와 비교합니다. 이때 과금 대상 수는 현재 연결된 수와 이번 기간에 앞서 해제된 수를 합한 값입니다. usage.connectionsActive는 현재 활성 상태인 수이며, usage.connectionsReleased는 갱신 시 복구되는 용량입니다.

brands는 null로 반환되며, 이는 무제한을 의미합니다. API 요금제에서는 브랜드 수가 과금 대상이 아닙니다.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/limits

발생할 수 있는 오류

전체 목록은 오류 코드 참조에 있습니다.

다음 단계

연결 한도, 연결 5개 단위의 팩, 90일 보관 처리 규칙이 어떻게 연관되는지 알아보려면 요금제 및 추가 기능을 읽고, 폴링 대신 social_post.* 및 social_connection.* 이벤트를 수신하려면 웹훅으로 이벤트에 대응하기를 읽습니다.

Python SDK는 이 엔드포인트를 client.social.brands, client.social.connections, client.social.posts 및 client.social.bulk로 지원하며, 자세한 내용은 Social 리소스를 참조합니다. Node SDK는 아직 Social을 지원하지 않으므로, Node에서 REST 엔드포인트를 직접 호출합니다.