Listings APIListings API
로그인
POST/api/v4/social/brands/{brandId}/connections/link

연결 링크 받기

최종 사용자가 소셜 플랫폼 1개를 브랜드에 연결하는 과정을 안내하는 유효 기간이 짧은 호스팅 URL을 반환합니다.

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

매개변수

경로

이름유형필수설명
brandIdstring필수Brand UUID the connection will be attached to.

본문

이름유형필수설명
channelstring필수Platform to connect: `FACEBOOK`, `INSTAGRAM`, `TWITTER` (X), `LINKEDIN` or `PINTEREST`.
redirectUrlstring필수Absolute https URL in your application the user is returned to when the flow finishes. Must be a URL you control.
errorUrlstring선택Absolute https URL the user is returned to if they cancel or the platform rejects the authorization. Defaults to `redirectUrl` when omitted.
statestring선택Opaque string echoed back on the return URL unchanged. Use it to correlate the return with the session that started the flow; it is not validated or interpreted.

요청 예시

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

Request body
{  "channel": "INSTAGRAM",  "redirectUrl": "https://app.example.com/social/connected",  "errorUrl": "https://app.example.com/social/connect-failed",  "state": "sess_9f2c1e64"}

응답

200Link generated. Redirect the end user to `url`; `expiresIn` is how many seconds it stays valid.
Response
{  "data": {    "connectSocialAccount": {      "status": "success",      "url": "https://social.listingsapi.com/connect/start?token=bfac8e06-8d72-4810-9c50-ae7ee12a7b52",      "title": null,      "token": null,      "expiresIn": 900    }  }}
200The link could not be issued. `status` is `failed` and `title` carries the reason: most often the account is at its connection cap (`SY95042`, counted on billable connections, so recent disconnects have not freed room) or the platform is not enabled for the account (`SY95044`).
Response
{  "data": {    "connectSocialAccount": {      "status": "failed",      "url": null,      "title": "SY95042: Connection limit reached for this account",      "token": null,      "expiresIn": null    }  }}
401Unauthenticated, missing or invalid API key.
404No brand with that ID on this account (`SY95043`).

소셜 플랫폼 1개를 브랜드 1개에 연결하는 유효 기간이 짧은 URL을 발급합니다. 플랫폼의 OAuth 자격 증명을 직접 다루는 일은 없습니다. 최종 사용자를 반환된 url로 리디렉션하면 사용자가 플랫폼의 동의 화면에서 절차를 완료하고 게시할 페이지, 보드 또는 조직을 선택한 다음 redirectUrl로 돌아옵니다.

이 작업은 본문이 평면 구조인 유일한 Social 쓰기 작업입니다. Social API의 다른 모든 쓰기 작업은 input 객체로 감싸지만, 이 작업은 그렇지 않습니다. channel, redirectUrl과 선택 사항인 errorUrl 및 state를 최상위 수준에 넣어 전송합니다.

사용 사례: 제품 내 셀프서비스 채널 연결. 사용자에게 플랫폼 5개를 표시하고, 사용자가 하나를 선택하면 해당 channel과 사용자 세션을 식별하는 state를 사용해 이 엔드포인트를 호출합니다. 사용자를 url로 리디렉션합니다. 사용자가 status=success와 함께 redirectUrl로 돌아오면 새 채널이 나타날 때까지 GET /social/brands/{brandId}/connections를 폴링한 다음, POST /social/posts를 사용해 첫 게시물을 작성할 수 있도록 합니다.

사용자가 돌아오는 위치

흐름이 끝나면 다음 쿼리 매개변수가 추가된 redirectUrl 또는 errorUrl로 사용자를 보냅니다.

매개변수항상 포함설명
status예success 또는 error입니다.
brandId예연결이 추가된 브랜드입니다. 호출 시 사용한 경로 매개변수와 일치합니다.
platform예연결된 플랫폼입니다(예: INSTAGRAM).
state값을 전송한 경우에만전송한 불투명 값이 변경 없이 그대로 반환됩니다.
connectedAccountIdstatus=success인 경우에만새 연결의 UUID이며, 연결 목록에 표시되는 id와 동일합니다.
Code
https://app.example.com/social/connected  ?status=success  &brandId=6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902  &platform=INSTAGRAM  &state=sess_9f2c1e64  &connectedAccountId=b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7

참고 사항.

  • 링크는 만료됩니다. expiresIn에는 유효 기간이 초 단위로 담겨 있습니다. 이 링크는 1회용이므로 미리 발급하지 말고 사용자가 "연결"을 클릭하는 순간에 발급하며, 절대로 저장하지 마십시오. 사용자가 흐름을 중단하면 이 엔드포인트를 다시 호출하여 새 URL을 받습니다.
  • 연결은 비동기적으로 생성됩니다. 연결 행이 생성되기 직전에 사용자가 redirectUrl로 돌아오므로, 돌아온 직후 연결 목록을 조회했을 때 해당 연결이 없어도 정상일 수 있습니다. 첫 조회 결과가 비어 있다고 실패로 간주하지 말고 몇 초 동안 연결 목록을 폴링합니다.
  • Instagram에는 Facebook 페이지에 연결된 비즈니스 또는 크리에이터 계정이 필요합니다. 개인 Instagram 계정은 연결할 수 없으며, 플랫폼의 동의 화면에도 선택 항목으로 표시되지 않습니다. 사용자가 이 문제를 겪으면 Instagram 앱에서 계정 유형을 전환하고 관리 중인 페이지에 연결하도록 안내한 다음 링크를 다시 발급합니다.
  • TWITTER는 X입니다. 하위 호환성을 위해 enum 값은 TWITTER로 유지되었으며, 제품은 X입니다. 플랫폼 값은 대문자 enum 이름이며, "instagram"을 전송하면 거부됩니다.
  • redirectUrl과 errorUrl은 절대 https URL이어야 합니다. 상대 URL 또는 http URL은 SY95049로 거부됩니다.
  • 연결은 사용량에 따라 과금되는 리소스입니다. 각 연결은 계정 전체에서 공유하는 하나의 용량 풀을 사용하며, Social Launch에서는 연결 20개, Social Growth에서는 125개가 제공되고, 월 $25의 연결 팩마다 5개가 추가되어 셀프서비스 상한인 250개까지 늘릴 수 있습니다. 브랜드 자체는 무제한이므로 용량이 부족해지는 호출은 항상 이 호출이며, 브랜드 생성 호출은 해당되지 않습니다. 풀이 가득 차면 링크 요청은 SY95042와 함께 status: "failed"를 반환합니다. 요금제 및 추가 기능을 참고하고 GET /social/limits에서 남은 용량을 확인합니다.
  • 이 기능은 사업장 수준의 Facebook 연결 링크에 해당하는 Social 기능이지만, 두 기능은 별개의 제품이며 한쪽에서 만든 연결은 다른 쪽에서 보이지 않습니다.

쓰기 작업: 실제 계정에서는 실행하지 않습니다. 표시된 요청과 응답은 API 스키마를 기반으로 구성되었습니다.

Request
curl -X POST 'https://listingsapi.com/api/v4/social/brands/<brandId>/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/connect-failed",    "state": "sess_9f2c1e64"  }'
Run in playground