Shoplive Developers
한국어KOEnglishEN日本語JA

Shoplive API 레퍼런스

이 페이지는 공식 문서와 같은 원본에서 생성된, Shoplive External API v2 의 전체 엔드포인트 레퍼런스입니다. API 가 처음이신가요? 인증과 세 가지 End-to-End 주제를 다루는 시작 가이드부터 확인해 보세요.

요청 헤더

JWT 토큰 발행

JWT 페이로드를 생성할 때

  1. exp는 충분히 먼 시점으로 설정합니다 (아래 예시는 3년 뒤로 설정합니다)

  2. 페이로드에 accessKey를 넣습니다. 값은 {accessKey} 경로 파라미터와 같습니다.

  3. HS256으로 JWT에 서명합니다. 서명 키는 비밀 키(secret key)를 Base64 디코딩한 값을 사용합니다.

JWT는 HTTP 요청의 헤더에 담아 전달해야 합니다.

java
import io.jsonwebtoken.JwtBuilder;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import java.util.Date;
public class JwtAuthorizationGeneratorSample {
    public static void main(String[] args) {

        String algorithm = "HS256";
        String base64EncodedSecretKey = "{secretKey}";
        long expiration = System.currentTimeMillis() + 3 * 365 * 24 * (60 * 60 * 1000L);
        String accessKey = "{accessKey}";

        JwtBuilder builder = Jwts.builder()
            .signWith(SignatureAlgorithm.forName(algorithm), base64EncodedSecretKey)
            .setExpiration(new Date(expiration))
            .setIssuedAt(new Date())
            .claim("accessKey", accessKey);
      
        String jwt = builder.compact();
        System.out.printf("jwt: " + jwt);
    }
}

다음은 헤더에 JWT를 담아 보내는 예시입니다.

bash
curl --location --request GET 'https://private.shopliveapi.com/v2/{accessKey}/campaign/{campaignKey}' \ 
--header 'Authorization: Bearer {JWT_TOKEN}'

토큰이 없거나 올바르지 않으면 401(_s: -824), 만료되었으면 401(_s: -412)이 반환됩니다.

다음 → Campaign 객체

방송 API

Campaign 객체

속성 이름

타입

설명

campaignMeta

CampaignMeta!

방송의 메타 정보

stream

Stream!

방송의 송출 정보

campaignProductList

List<CampaignProduct>?

CampaignProduct 객체의 목록입니다.

seller

Seller?

방송의 셀러 정보

CampaignMeta 객체

속성 이름

타입

읽기 전용

설명

campaignId

String!

O

자동 생성되는 방송의 식별자입니다. (숫자로 이루어진 문자열)

campaignKey

String!

O

자동 생성되는 키입니다(최대 32바이트, 영숫자). API 호출 시 방송을 지정하는 데 사용됩니다.

accessKey

String!

O

고객사마다 부여되는 고유 키입니다. 대부분의 Shoplive API에서 이 accessKey가 필요합니다.

shoplivePlayerUrl

String!

O

테스트 시청을 위해 Shoplive에서 제공하는 플레이어 URL

title

String!

방송의 제목

description

String?

방송에 대한 설명

campaignStatus

String!

O

RESERVED, READY, REHEARSAL, ONAIR, ENDED

rerun

Boolean!

O

해당 방송이 재방송인지 여부를 나타내는 불리언 플래그입니다.

userCount

Integer?

O

방송 상태가 ONAIR 또는 REHEARSAL일 때 실시간 시청자 수입니다.

방송이 종료됐을 때(방송 상태가 ENDED일 때)의 총 시청자 수입니다.

* 방송 상태가 READY일 때는 null입니다.

concurrentUserCount

Integer?

O

방송 상태가 ONAIR 또는 REHEARSAL일 때 실시간 동시 시청자 수입니다.

* 방송 상태가 READY 또는 ENDED일 때는 null입니다.

likeCount

Integer?

O

campaignStatus READY: null campaignStatus REHEARSAL: 실시간 좋아요 수 campaignStatus ONAIR: 실시간 좋아요 수 campaignStatus ENDED: 총 좋아요 수

rehearsalPasscode

String!

리허설 모드에서 라이브 스트리밍에 입장하기 위한 패스코드

serveReplay

Boolean!

방송 종료 후 리플레이를 제공할지 여부입니다.

logoImageUrl

String?

O

로고 이미지 URL

brand

Brand?

Brand 객체

preCampaignVideoUrl

String?

방송 시작 전 영상 URL

preCampaignImageUrl

String?

방송 시작 전 이미지 URL

postCampaignImageUrl

String?

방송 종료 후 이미지 URL

backgroundImageUrl

String?

배경 이미지 URL

ieUnsupportImageUrl

String?

IE 브라우저용 이미지

tags

List?

방송에 설정된 태그 정보 (최대 10개까지 설정 가능)

scheduledStartAt

String!

방송의 예정된 시작 일시 (형식: YYYY-MM-DD'T'HH:mm:ss'Z')

scheduledEndAt

String?

방송의 예정된 종료 일시 (형식: YYYY-MM-DD'T'HH:mm:ss'Z')

campaignStartedAt

String?

O

방송의 실제 시작 일시 (형식: YYYY-MM-DD'T'HH:mm:ss'Z')

campaignEndedAt

String?

O

방송의 실제 종료 일시 (형식: YYYY-MM-DD'T'HH:mm:ss'Z')

createdAt

String!

O

방송 생성 일시 (UTC) (형식: YYYY-MM-DD'T'HH:mm:ss'Z')

updatedAt

String!

O

방송 마지막 수정 일시 (UTC) (형식: YYYY-MM-DD'T'HH:mm:ss'Z')

Stream 객체

속성 이름

타입

설명

streamUrl

String!

스트리밍 소프트웨어(예: OBS)에 사용할 RTMP 스트림 URL 정보

streamKey

String!

스트리밍 소프트웨어(예: OBS)에 사용할 RTMP 스트림 키 정보

videoAspectRatio

String!

영상의 화면 비율입니다. 9:16(세로) 또는 16:9(가로)

liveUrl

String!

라이브 스트리밍의 마스터 m3u8 URL입니다.

liveUrls

Map<String, String>?

해상도별(320p, 480p, 720p, 1080p) 라이브 스트리밍 m3u8 URL 모음입니다.

previewLiveUrl

String!

미리보기 영상의 m3u8 URL(320p 해상도)입니다. 미리보기는 웹 브라우저에서 영상 썸네일을 구현하기 위한 영상 포맷입니다.

replayLiveUrl

String?

리플레이 스트리밍의 마스터 m3u8 URL입니다. 이 값은 방송이 종료된 후에만 설정됩니다.

replayLiveUrls

Map<String, String>?

해상도별(320p, 480p, 720p, 1080p) 리플레이 스트리밍 m3u8 URL 모음입니다.

previewReplayLiveUrl

String?

리플레이 미리보기 영상의 m3u8 URL(320p 해상도)입니다. 미리보기는 웹 브라우저에서 영상 썸네일을 구현하기 위한 영상 포맷입니다. 이 값은 방송이 종료된 후에만 설정됩니다. URL의 쿼리 스트링에 preview 파라미터 값이 1로 지정된 경우, 리플레이 미리보기 영상 재생에 사용된 데이터가 사용량 할당량에 포함된다는 것을 의미합니다.

CampaignProduct 객체

속성 이름

타입

설명

productId

String!

자동 생성되는 고유 상품 ID

customerProductId

String?

고객사의 상품 ID이며 고유해야 합니다(고객사가 직접 정의). customerProductId는 Product API로만 설정할 수 있으며, Shoplive 어드민 도구에는 이 필드의 입력란이 없습니다.

name

String!

상품명

brand

String?

브랜드명

description

String?

상품에 대한 설명

brandIdentifier

String?

브랜드 키

url

String!

상품 URL입니다. Shoplive Player에서 상품 정보를 클릭했을 때 이동하는 목적지 URL입니다.

sku

String?

상품 SKU 정보 (고객사가 정의)

imageUrl

String?

상품 썸네일 이미지 URL입니다. Shoplive는 상품 객체 생성 시 자동으로 썸네일 URL을 생성합니다.

currency

String!

가격의 통화

showPrice

Boolean!

가격을 표시할지 여부입니다.

originalPrice

Double?

예: 20.00 (통화가 USD인 경우 $20.00)

discountPrice

Double?

예: 15.00 (통화가 USD인 경우 $15.00)

discountRate

Double?

예: 25.00 (할인율이 25%인 경우)

enableAuction

Boolean!

경매 상품 여부입니다.

bidStartingPrice

Double?

경매의 시작 가격 (예: 0.99)

bidDuration

Integer?

경매의 입찰 시간 (초)

bidIncrementalAmount

Double?

입찰 시 증가하는 금액

extendBidDuration

Boolean?

경매 종료 직전에 입찰이 들어오면 남은 입찰 시간을 연장할지 여부입니다. 연장 시간은 고객사의 경매 설정을 따릅니다.

ctaButtonTitle

String?

상품에 표시되는 CTA(행동 유도) 버튼의 제목입니다. UI 커스터마이징이 필요하므로 Shoplive와 협의가 필요합니다.

seller

Seller?

상품을 소유한 셀러 정보입니다.

createdAt

String!

상품이 생성된 일시입니다 (형식: YYYY-MM-DD'T'HH:mm:ss'Z')

updatedAt

String!

상품이 수정된 일시입니다 (형식: YYYY-MM-DD'T'HH:mm:ss'Z')

campaignId

String!

자동 생성되는 방송 식별자입니다. (숫자로 이루어진 문자열)

visible

Boolean?

상품의 'visible'(노출) 상태입니다.

purchasable

Boolean?

상품의 'purchasable'(구매 가능) 상태입니다.

showingNow

Boolean!

상품의 'Now' 표시 상태입니다. (=pin)

sortOrder

Integer!

상품이 노출되는 순서입니다. (=listOrder)

stockStatus

String!

IN_STOCK, LOW_IN_STOCK , SOLD_OUT

auction

Auction?

상품의 경매 정보입니다.

Auction 객체

속성 이름

타입

설명

productId

String!

자동 생성되는 고유 상품 ID

auctionStatus

String!

READY, ONGOING, ENDING, ENDED

startingPrice

Double!

경매의 시작 가격

bidRound

Integer!

경매의 입찰 회차

currentPrice

Double!

경매의 현재 가격

winningPrice

Double?

경매의 낙찰 가격

recommendedPrices

List<Double>?

경매의 추천 입찰 가격

winner

Bidder?

경매의 낙찰자입니다.

leader

Bidder?

경매의 최고 입찰자입니다.

winnerCheckoutScheme

String?

낙찰자가 상품을 구매할 수 있는 앱 스킴입니다.

startedAt

Number?

경매의 실제 시작 일시입니다 (형식: 밀리초 단위 타임스탬프)

endingAt

Number?

경매의 예상 종료 일시입니다 (형식: 밀리초 단위 타임스탬프)

endedAt

Number?

경매의 실제 종료 일시입니다 (형식: 밀리초 단위 타임스탬프)

Bidder 객체

속성 이름

타입

설명

uid

String!

자동 생성되는 사용자 식별자입니다. (숫자 형태의 문자열)

userId

String?

사용자 식별자입니다. (고객사가 정의)

name

String!

사용자의 이름입니다.

예시

json
{
    "campaignMeta": {
        "campaignId": "1234",
        "campaignKey": "{campaignKey}",
        "accessKey": "{accessKey}",
        "shoplivePlayerUrl": "https://www.shoplive.show/v1/player.html?ak={accessKey}&ck={campaignKey}",
        "title": "Shoplive Liveshow",
        "description": "Liveshow description",
        "tags": [ "tag1", "tag2" ],
        "campaignStatus": "READY",
        "userCount": null,
        "likeCount": null,
        "rehearsalPasscode": "9876",
        "serveReplay": false,
        "logoImageUrl": null,
        "preCampaignVideoUrl": null,
        "preCampaignImageUrl": "https://image.shoplive.cloud/14352cf2-ef40-4ba9-93af-279a104cb3c8.png",
        "postCampaignImageUrl": "https://image.shoplive.cloud/6da19c2d-8d53-4cea-801f-7b39913f7c35.png",
        "backgroundImageUrl": "https://image.shoplive.cloud/0b1bd566-4087-40ef-b376-fb863a888d72.png",
        "ieUnsupportImageUrl": "https://image.shoplive.cloud/5a0fd01c-8889-4d28-8a15-8b7661a422a2.png",
        "scheduledStartAt": "2026-11-01T09:00:00Z",
        "scheduledEndAt": "2026-11-01T10:00:00Z",
        "campaignStartedAt": null,
        "campaignEndedAt": null,
        "createdAt": "2026-11-01T08:15:00Z",
        "updatedAt": "2026-11-01T08:29:09Z"
    },
    "stream": {
        "streamUrl": "rtmp://stream.shoplive.cloud:1935/stream",
        "streamKey": "{streamKey}",
        "videoAspectRatio": "9:16",
        "liveUrl": "https://live.shoplive.cloud/live/{streamKey}.m3u8",
        "liveUrls": {
            "720p": "https://live.shoplive.cloud/live/{streamKey}_720p/playlist.m3u8",
            "480p": "https://live.shoplive.cloud/live/{streamKey}_480p/playlist.m3u8" 
        },
        "previewLiveUrl": "https://live.shoplive.cloud/live/{streamKey}_480p/index.m3u8",
        "replayLiveUrl": null,
        "replayLiveUrls": null,
        "previewReplayLiveUrl": "https://api.shoplive.cloud/v1/replay/{accessKey}/{campaignKey}/replay_320p/ORIGINAL/index.m3u8?preview=1"
    },
    "campaignProductList": [
        {
            "productId": "1001",
            "customerProductId": "SHOPLIVE_PRODUCT_1",
            "name": "Keyring",
            "brand": "SHOPLIVE",
            "description": null,
            "url": "https://www.shoplive.cloud/en",
            "sku": "SKU001",
            "imageUrl": "https://image.shoplive.cloud/e05d1464-1942-4e4e-bb0b-c4310167d465.jpeg",
            "currency": "USD",
            "showPrice": true,
            "originalPrice": 20.0,
            "discountPrice": 10.0,
            "discountRate": 50.0,
            "enableAuction": false,
            "bidStartingPrice": null,
            "bidDuration": null,
            "bidIncrementalAmount": null,
            "extendBidDuration": null,
            "seller": {
                "sellerId": "1",
                "name": "Shoplive Product Store",
                "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
                "storeUrl": "https://shoplive.cloud",
                "description": "Description of the seller",
                "schemes": null
            },
            "createdAt": "2026-05-20T08:01:05Z",
            "updatedAt": "2026-05-20T11:27:34Z",
            "campaignId": "1234",
            "showingNow": true,
            "sortOrder": 1,
            "stockStatus": "IN_STOCK",
            "auction": null
        },
        {
            "productId": "1002",
            "customerProductId": "SHOPLIVE_PRODUCT_2",
            "name": "Hoodie",
            "brand": "SHOPLIVE",
            "description": null,
            "url": "https://www.shoplive.cloud/en",
            "sku": "SKU002",
            "imageUrl": "https://image.shoplive.cloud/40afe353-0d23-47b6-acdf-10d1fca10c57.jpeg",
            "currency": "USD",
            "showPrice": true,
            "originalPrice": 50.0,
            "discountPrice": 37.0,
            "discountRate": 26.0,
            "enableAuction": false,
            "bidStartingPrice": null,
            "bidDuration": null,
            "bidIncrementalAmount": null,
            "extendBidDuration": null,
            "seller": {
                "sellerId": "1",
                "name": "Shoplive Product Store",
                "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
                "storeUrl": "https://shoplive.cloud",
                "description": "Description of the seller",
                "schemes": null
            },
            "createdAt": "2026-05-20T08:01:05Z",
            "updatedAt": "2026-05-20T11:27:34Z",
            "campaignId": "1234",
            "showingNow": true,
            "sortOrder": 2,
            "stockStatus": "LOW_IN_STOCK",
            "auction": null
        },
        {
            "productId": "1003",
            "customerProductId": "SHOPLIVE_PRODUCT_3",
            "name": "T-Shirts",
            "brand": "SHOPLIVE",
            "description": null,
            "url": "https://www.shoplive.cloud/en",
            "sku": "SKU003",
            "imageUrl": "https://image.shoplive.cloud/67129efb-d859-48b6-94b9-d411fb6de550.jpeg",
            "currency": "USD",
            "showPrice": true,
            "originalPrice": 30.0,
            "discountPrice": 28.0,
            "discountRate": 6.0,
            "enableAuction": false,
            "bidStartingPrice": null,
            "bidDuration": null,
            "bidIncrementalAmount": null,
            "extendBidDuration": null,
            "seller": {
                "sellerId": "1",
                "name": "Shoplive Product Store",
                "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
                "storeUrl": "https://shoplive.cloud",
                "description": "Description of the seller",
                "schemes": null
            },
            "createdAt": "2026-05-20T08:01:05Z",
            "updatedAt": "2026-05-20T11:27:34Z",
            "campaignId": "1234",
            "showingNow": false,
            "sortOrder": 3,
            "stockStatus": "SOLD_OUT",
            "auction": null
        },
        {
            "productId": "1004",
            "customerProductId": "SHOPLIVE_PRODUCT_4",
            "name": "Mug",
            "brand": "SHOPLIVE",
            "description": null,
            "url": "https://www.shoplive.cloud/en",
            "sku": "SKU004",
            "imageUrl": "https://image.shoplive.cloud/b22c72c7-d2f8-49c3-83f0-314c59740649.jpeg",
            "currency": "USD",
            "showPrice": true,
            "originalPrice": 10.0,
            "discountPrice": 7.0,
            "discountRate": 30.0,
            "enableAuction": true,
            "bidStartingPrice": 7.0,
            "bidDuration": 120,
            "bidIncrementalAmount": 1.0,
            "extendBidDuration": true,
            "seller": {
                "sellerId": "1",
                "name": "Shoplive Product Store",
                "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
                "storeUrl": "https://shoplive.cloud",
                "description": "Description of the seller",
                "schemes": null
            },
            "createdAt": "2026-05-20T08:01:05Z",
            "updatedAt": "2026-05-20T11:27:34Z",
            "campaignId": "1234",
            "showingNow": false,
            "sortOrder": 4,
            "stockStatus": "IN_STOCK",
            "auction": {
                "productId": "1004",
                "auctionStatus": "READY",
                "startingPrice": 7.0,
                "bidRound": 1,
                "currentPrice": 7.0,
                "winningPrice": null,
                "recommendedPrices": null,
                "winner": null,
                "leader": null,
                "winnerCheckoutScheme": null,
                "startedAt": null,
                "endingAt": null,
                "endedAt": null
            }
        },
        {
            "productId": "1005",
            "customerProductId": "SHOPLIVE_PRODUCT_5",
            "name": "Ballcap",
            "brand": "SHOPLIVE",
            "description": null,
            "url": "https://www.shoplive.cloud/en",
            "sku": "SKU005",
            "imageUrl": "https://image.shoplive.cloud/ae4d67b6-9d92-4a19-a457-6566420c5b9b.jpeg",
            "currency": "USD",
            "showPrice": true,
            "originalPrice": 18.0,
            "discountPrice": 14.0,
            "discountRate": 22.0,
            "enableAuction": false,
            "bidStartingPrice": null,
            "bidDuration": null,
            "bidIncrementalAmount": null,
            "extendBidDuration": null,
            "seller": {
                "sellerId": "1",
                "name": "Shoplive Product Store",
                "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
                "storeUrl": "https://shoplive.cloud",
                "description": "Description of the seller",
                "schemes": null
            },
            "createdAt": "2026-05-20T08:01:05Z",
            "updatedAt": "2026-05-20T11:27:34Z",
            "campaignId": "1234",
            "showingNow": false,
            "sortOrder": 5,
            "stockStatus": "IN_STOCK",
            "auction": null
        }
    ],
    "seller": {
        "sellerId": "1",
        "name": "Shoplive Product Store",
        "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
        "storeUrl": "https://shoplive.cloud",
        "description": "Description of the seller",
        "schemes": null,
        "sellerIdentifier": "seller_identifier"
    }
}

 

campaignStatus가 ONAIR인 경우

json
{
    "campaignMeta": {
        "campaignId": "1234",
        "campaignKey": "{campaignKey}",
        "accessKey": "{accessKey}",
        "shoplivePlayerUrl": "https://www.shoplive.show/v1/player.html?ak={accessKey}&ck={campaignKey}",
        "title": "Shoplive Liveshow",
        "description": "Liveshow description",
        "tags": [ "tag1", "tag2" ],
        "campaignStatus": "ONAIR",
        "userCount": 123,
        "likeCount": 3132,
        "rehearsalPasscode": "9876",
        "serveReplay": false,
        "logoImageUrl": null,
        "preCampaignVideoUrl": null,
        "preCampaignImageUrl": "https://image.shoplive.cloud/14352cf2-ef40-4ba9-93af-279a104cb3c8.png",
        "postCampaignImageUrl": "https://image.shoplive.cloud/6da19c2d-8d53-4cea-801f-7b39913f7c35.png",
        "backgroundImageUrl": "https://image.shoplive.cloud/0b1bd566-4087-40ef-b376-fb863a888d72.png",
        "ieUnsupportImageUrl": "https://image.shoplive.cloud/5a0fd01c-8889-4d28-8a15-8b7661a422a2.png",
        "scheduledStartAt": "2026-11-01T09:00:00Z",
        "scheduledEndAt": "2026-11-01T10:00:00Z",
        "campaignStartedAt": "2026-11-01T09:10:05Z",
        "campaignEndedAt": null,
        "createdAt": "2026-11-01T08:15:00Z",
        "updatedAt": "2026-11-01T08:29:09Z"
    },
    "stream": {
        "streamUrl": "rtmp://stream.shoplive.cloud:1935/stream",
        "streamKey": "{streamKey}",
        "videoAspectRatio": "9:16",
        "liveUrl": "https://live.shoplive.cloud/live/{streamKey}.m3u8",
        "liveUrls": {
            "720p": "https://live.shoplive.cloud/live/{streamKey}_720p/playlist.m3u8" 
        },
        "previewLiveUrl": "https://live.shoplive.cloud/live/{streamKey}_320p/index.m3u8",
        "replayLiveUrl": null,
        "replayLiveUrls": null,
        "previewReplayLiveUrl": "https://api.shoplive.cloud/v1/replay/{accessKey}/{campaignKey}/replay_320p/ORIGINAL/index.m3u8?preview=1"
    },
    "campaignProductList": [
        {
            "productId": "1001",
            "customerProductId": "SHOPLIVE_PRODUCT_1",
            "name": "Keyring",
            "brand": "SHOPLIVE",
            "description": null,
            "url": "https://www.shoplive.cloud/en",
            "sku": "SKU001",
            "imageUrl": "https://image.shoplive.cloud/e05d1464-1942-4e4e-bb0b-c4310167d465.jpeg",
            "currency": "USD",
            "showPrice": true,
            "originalPrice": 20.0,
            "discountPrice": 10.0,
            "discountRate": 50.0,
            "enableAuction": false,
            "bidStartingPrice": null,
            "bidDuration": null,
            "bidIncrementalAmount": null,
            "extendBidDuration": null,
            "seller": {
                "sellerId": "1",
                "name": "Shoplive Product Store",
                "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
                "storeUrl": "https://shoplive.cloud",
                "description": "Description of the seller",
                "schemes": null
            },
            "createdAt": "2026-05-20T08:01:05Z",
            "updatedAt": "2026-05-20T11:27:34Z",
            "campaignId": "1234",
            "showingNow": true,
            "sortOrder": 1,
            "stockStatus": "SOLD_OUT",
            "auction": null
        },
        {
            "productId": "1002",
            "customerProductId": "SHOPLIVE_PRODUCT_2",
            "name": "Hoodie",
            "brand": "SHOPLIVE",
            "description": null,
            "url": "https://www.shoplive.cloud/en",
            "sku": "SKU002",
            "imageUrl": "https://image.shoplive.cloud/40afe353-0d23-47b6-acdf-10d1fca10c57.jpeg",
            "currency": "USD",
            "showPrice": true,
            "originalPrice": 50.0,
            "discountPrice": 37.0,
            "discountRate": 26.0,
            "enableAuction": false,
            "bidStartingPrice": null,
            "bidDuration": null,
            "bidIncrementalAmount": null,
            "extendBidDuration": null,
            "seller": {
                "sellerId": "1",
                "name": "Shoplive Product Store",
                "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
                "storeUrl": "https://shoplive.cloud",
                "description": "Description of the seller",
                "schemes": null
            },
            "createdAt": "2026-05-20T08:01:05Z",
            "updatedAt": "2026-05-20T11:27:34Z",
            "campaignId": "1234",
            "showingNow": true,
            "sortOrder": 2,
            "stockStatus": "LOW_IN_STOCK",
            "auction": null
        },
        {
            "productId": "1003",
            "customerProductId": "SHOPLIVE_PRODUCT_3",
            "name": "T-Shirts",
            "brand": "SHOPLIVE",
            "description": null,
            "url": "https://www.shoplive.cloud/en",
            "sku": "SKU003",
            "imageUrl": "https://image.shoplive.cloud/67129efb-d859-48b6-94b9-d411fb6de550.jpeg",
            "currency": "USD",
            "showPrice": true,
            "originalPrice": 30.0,
            "discountPrice": 28.0,
            "discountRate": 6.0,
            "enableAuction": false,
            "bidStartingPrice": null,
            "bidDuration": null,
            "bidIncrementalAmount": null,
            "extendBidDuration": null,
            "seller": {
                "sellerId": "1",
                "name": "Shoplive Product Store",
                "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
                "storeUrl": "https://shoplive.cloud",
                "description": "Description of the seller",
                "schemes": null
            },
            "createdAt": "2026-05-20T08:01:05Z",
            "updatedAt": "2026-05-20T11:27:34Z",
            "campaignId": "1234",
            "showingNow": false,
            "sortOrder": 3,
            "stockStatus": "IN_STOCK",
            "auction": null
        },
        {
            "productId": "1004",
            "customerProductId": "SHOPLIVE_PRODUCT_4",
            "name": "Mug",
            "brand": "SHOPLIVE",
            "description": null,
            "url": "https://www.shoplive.cloud/en",
            "sku": "SKU004",
            "imageUrl": "https://image.shoplive.cloud/b22c72c7-d2f8-49c3-83f0-314c59740649.jpeg",
            "currency": "USD",
            "showPrice": true,
            "originalPrice": 10.0,
            "discountPrice": 7.0,
            "discountRate": 30.0,
            "enableAuction": true,
            "bidStartingPrice": 7.0,
            "bidDuration": 120,
            "bidIncrementalAmount": 1.0,
            "extendBidDuration": true,
            "seller": {
                "sellerId": "1",
                "name": "Shoplive Product Store",
                "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
                "storeUrl": "https://shoplive.cloud",
                "description": "Description of the seller",
                "schemes": null
            },
            "createdAt": "2026-05-20T08:01:05Z",
            "updatedAt": "2026-05-20T11:27:34Z",
            "campaignId": "1234",
            "showingNow": true,
            "sortOrder": 4,
            "stockStatus": "IN_STOCK",
            "auction": {
                "productId": "1004",
                "auctionStatus": "ONGOING",
                "startingPrice": 7.0,
                "bidRound": 3,
                "currentPrice": 9.0,
                "winningPrice": null,
                "recommendedPrices": [
                    10.0
                ],
                "winner": null,
                "leader": {
                    "uid": "350964901054939144",
                    "userId": "test@shoplive.cloud",
                    "name": "ShopliveUser-1"
                },
                "winnerCheckoutScheme": null,
                "startedAt": 1793524830000,
                "endingAt": 1793524950000,
                "endedAt": null
            }
        },
        {
            "productId": "1005",
            "customerProductId": "SHOPLIVE_PRODUCT_5",
            "name": "Ballcap",
            "brand": "SHOPLIVE",
            "description": null,
            "url": "https://www.shoplive.cloud/en",
            "sku": "SKU005",
            "imageUrl": "https://image.shoplive.cloud/ae4d67b6-9d92-4a19-a457-6566420c5b9b.jpeg",
            "currency": "USD",
            "showPrice": true,
            "originalPrice": 18.0,
            "discountPrice": 14.0,
            "discountRate": 22.0,
            "enableAuction": false,
            "bidStartingPrice": null,
            "bidDuration": null,
            "bidIncrementalAmount": null,
            "extendBidDuration": null,
            "seller": {
                "sellerId": "1",
                "name": "Shoplive Product Store",
                "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
                "storeUrl": "https://shoplive.cloud",
                "description": "Description of the seller",
                "schemes": null
            },
            "createdAt": "2026-05-20T08:01:05Z",
            "updatedAt": "2026-05-20T11:27:34Z",
            "campaignId": "1234",
            "showingNow": false,
            "sortOrder": 5,
            "stockStatus": "IN_STOCK",
            "auction": null
        }
    ],
    "seller": {
        "sellerId": "1",
        "name": "Shoplive Product Store",
        "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
        "storeUrl": "https://shoplive.cloud",
        "description": "Description of the seller",
        "schemes": null
    }
}

 

campaignStatus가 ENDED인 경우

json
{
    "campaignMeta": {
        "campaignId": "1234",
        "campaignKey": "{campaignKey}",
        "accessKey": "{accessKey}",
        "shoplivePlayerUrl": "https://www.shoplive.show/v1/player.html?ak={accessKey}&ck={campaignKey}",
        "title": "Shoplive Liveshow",
        "description": "Liveshow description",
        "tags": [ "tag1", "tag2" ],
        "campaignStatus": "ENDED",
        "userCount": 15923,
        "likeCount": 102683,
        "rehearsalPasscode": "9876",
        "serveReplay": false,
        "logoImageUrl": null,
        "preCampaignVideoUrl": null,
        "preCampaignImageUrl": "https://image.shoplive.cloud/14352cf2-ef40-4ba9-93af-279a104cb3c8.png",
        "postCampaignImageUrl": "https://image.shoplive.cloud/6da19c2d-8d53-4cea-801f-7b39913f7c35.png",
        "backgroundImageUrl": "https://image.shoplive.cloud/0b1bd566-4087-40ef-b376-fb863a888d72.png",
        "ieUnsupportImageUrl": "https://image.shoplive.cloud/5a0fd01c-8889-4d28-8a15-8b7661a422a2.png",
        "scheduledStartAt": "2026-11-01T09:00:00Z",
        "scheduledEndAt": "2026-11-01T10:00:00Z",
        "campaignStartedAt": "2026-11-01T09:10:05Z",
        "campaignEndedAt": "2026-11-01T10:05:05Z",
        "createdAt": "2026-11-01T08:15:00Z",
        "updatedAt": "2026-11-01T08:29:09Z"
    },
    "stream": {
        "streamUrl": "rtmp://stream.shoplive.cloud:1935/stream",
        "streamKey": "{streamKey}",
        "videoAspectRatio": "9:16",
        "liveUrl": "https://live.shoplive.cloud/live/{streamKey}.m3u8",
        "liveUrls": {
            "720p": "https://live.shoplive.cloud/live/{streamKey}_720p/playlist.m3u8" 
        },
        "previewLiveUrl": "https://live.shoplive.cloud/live/{streamKey}_320p/index.m3u8",
        "replayLiveUrl": "https://private.shopliveapi.com/v1/replay/{accessKey}/{campaignKey}/replay.m3u8?replayMode=ORIGINAL",
        "replayLiveUrls": {
            "720p": "https://private.shopliveapi.com/v1/replay/{accessKey}/{campaignKey}/ORIGINAL/720p/index.m3u8"
        },
        "previewReplayLiveUrl": "https://api.shoplive.cloud/v1/replay/{accessKey}/{campaignKey}/replay_320p/ORIGINAL/index.m3u8?preview=1"
    },
    "campaignProductList": [
        {
            "productId": "1001",
            "customerProductId": "SHOPLIVE_PRODUCT_1",
            "name": "Keyring",
            "brand": "SHOPLIVE",
            "description": null,
            "url": "https://www.shoplive.cloud/en",
            "sku": "SKU001",
            "imageUrl": "https://image.shoplive.cloud/e05d1464-1942-4e4e-bb0b-c4310167d465.jpeg",
            "currency": "USD",
            "showPrice": true,
            "originalPrice": 20.0,
            "discountPrice": 10.0,
            "discountRate": 50.0,
            "enableAuction": false,
            "bidStartingPrice": null,
            "bidDuration": null,
            "bidIncrementalAmount": null,
            "extendBidDuration": null,
            "seller": {
                "sellerId": "1",
                "name": "Shoplive Product Store",
                "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
                "storeUrl": "https://shoplive.cloud",
                "description": "Description of the seller",
                "schemes": null
            },
            "createdAt": "2026-05-20T08:01:05Z",
            "updatedAt": "2026-05-20T11:27:34Z",
            "campaignId": "1234",
            "showingNow": true,
            "sortOrder": 1,
            "stockStatus": "SOLD_OUT",
            "auction": null
        },
        {
            "productId": "1002",
            "customerProductId": "SHOPLIVE_PRODUCT_2",
            "name": "Hoodie",
            "brand": "SHOPLIVE",
            "description": null,
            "url": "https://www.shoplive.cloud/en",
            "sku": "SKU002",
            "imageUrl": "https://image.shoplive.cloud/40afe353-0d23-47b6-acdf-10d1fca10c57.jpeg",
            "currency": "USD",
            "showPrice": true,
            "originalPrice": 50.0,
            "discountPrice": 37.0,
            "discountRate": 26.0,
            "enableAuction": false,
            "bidStartingPrice": null,
            "bidDuration": null,
            "bidIncrementalAmount": null,
            "extendBidDuration": null,
            "seller": {
                "sellerId": "1",
                "name": "Shoplive Product Store",
                "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
                "storeUrl": "https://shoplive.cloud",
                "description": "Description of the seller",
                "schemes": null
            },
            "createdAt": "2026-05-20T08:01:05Z",
            "updatedAt": "2026-05-20T11:27:34Z",
            "campaignId": "1234",
            "showingNow": true,
            "sortOrder": 2,
            "stockStatus": "LOW_IN_STOCK",
            "auction": null
        },
        {
            "productId": "1003",
            "customerProductId": "SHOPLIVE_PRODUCT_3",
            "name": "T-Shirts",
            "brand": "SHOPLIVE",
            "description": null,
            "url": "https://www.shoplive.cloud/en",
            "sku": "SKU003",
            "imageUrl": "https://image.shoplive.cloud/67129efb-d859-48b6-94b9-d411fb6de550.jpeg",
            "currency": "USD",
            "showPrice": true,
            "originalPrice": 30.0,
            "discountPrice": 28.0,
            "discountRate": 6.0,
            "enableAuction": false,
            "bidStartingPrice": null,
            "bidDuration": null,
            "bidIncrementalAmount": null,
            "extendBidDuration": null,
            "seller": {
                "sellerId": "1",
                "name": "Shoplive Product Store",
                "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
                "storeUrl": "https://shoplive.cloud",
                "description": "Description of the seller",
                "schemes": null
            },
            "createdAt": "2026-05-20T08:01:05Z",
            "updatedAt": "2026-05-20T11:27:34Z",
            "campaignId": "1234",
            "showingNow": true,
            "sortOrder": 3,
            "stockStatus": "SOLD_OUT",
            "auction": null
        },
        {
            "productId": "1004",
            "customerProductId": "SHOPLIVE_PRODUCT_4",
            "name": "Mug",
            "brand": "SHOPLIVE",
            "description": null,
            "url": "https://www.shoplive.cloud/en",
            "sku": "SKU004",
            "imageUrl": "https://image.shoplive.cloud/b22c72c7-d2f8-49c3-83f0-314c59740649.jpeg",
            "currency": "USD",
            "showPrice": true,
            "originalPrice": 10.0,
            "discountPrice": 7.0,
            "discountRate": 30.0,
            "enableAuction": true,
            "bidStartingPrice": 7.0,
            "bidDuration": 120,
            "bidIncrementalAmount": 1,
            "extendBidDuration": true,
            "seller": {
                "sellerId": "1",
                "name": "Shoplive Product Store",
                "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
                "storeUrl": "https://shoplive.cloud",
                "description": "Description of the seller",
                "schemes": null
            },
            "createdAt": "2026-05-20T08:01:05Z",
            "updatedAt": "2026-05-20T11:27:34Z",
            "campaignId": "1234",
            "showingNow": true,
            "sortOrder": 4,
            "stockStatus": "SOLD_OUT",
            "auction": {
                "productId": "1004",
                "auctionStatus": "ENDED",
                "startingPrice": 7.0,
                "bidRound": 3,
                "currentPrice": 0.0,
                "winningPrice": 9.0,
                "recommendedPrices": null,
                "winner": {
                    "uid": "350964901054939144",
                    "userId": "test@shoplive.cloud",
                    "name": "ShopliveUser-1"
                },
                "leader": null,
                "winnerCheckoutScheme": null,
                "startedAt": 1793524830000,
                "endingAt": null,
                "endedAt": 1793524950000
            }
        },
        {
            "productId": "1005",
            "customerProductId": "SHOPLIVE_PRODUCT_5",
            "name": "Ballcap",
            "brand": "SHOPLIVE",
            "description": null,
            "url": "https://www.shoplive.cloud/en",
            "sku": "SKU005",
            "imageUrl": "https://image.shoplive.cloud/ae4d67b6-9d92-4a19-a457-6566420c5b9b.jpeg",
            "currency": "USD",
            "showPrice": true,
            "originalPrice": 18.0,
            "discountPrice": 14.0,
            "discountRate": 22.0,
            "enableAuction": false,
            "bidStartingPrice": null,
            "bidDuration": null,
            "bidIncrementalAmount": null,
            "extendBidDuration": null,
            "seller": {
                "sellerId": "1",
                "name": "Shoplive Product Store",
                "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
                "storeUrl": "https://shoplive.cloud",
                "description": "Description of the seller",
                "schemes": null
            },
            "createdAt": "2026-05-20T08:01:05Z",
            "updatedAt": "2026-05-20T11:27:34Z",
            "campaignId": "1234",
            "showingNow": true,
            "sortOrder": 5,
            "stockStatus": "SOLD_OUT",
            "auction": null
        }
    ],
    "seller": {
        "sellerId": "1",
        "name": "Shoplive Product Store",
        "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
        "storeUrl": "https://shoplive.cloud",
        "description": "Description of the seller",
        "schemes": null
    }
}

이전 ← JWT 토큰 발행다음 → 방송 검색

방송 API

방송 검색

GET/v2/{accessKey}/campaign

방송 검색

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey

쿼리 파라미터

from
string
방송을 검색할 scheduledStartAt 범위의 시작 (형식: YYYY-MM-DD'T'HH:mm:ss'Z', 예: 2026-05-20T08:00:00Z)
to
string
방송을 검색할 scheduledStartAt 범위의 끝 (형식: YYYY-MM-DD'T'HH:mm:ss'Z', 예: 2026-05-20T09:00:00Z)
keyword
string
방송의 제목과 설명을 검색할 키워드
tags
string
검색할 태그를 쉼표로 구분하여 입력합니다. AND 또는 OR 쿼리를 지정하려면 tagSearchOperator를 사용하세요.
tagSearchOperator
stringenum
ANDOR
태그로 검색할 때 검색 연산자를 지정하세요.
기본값OR
campaignStatus
string
상태(RESERVED, READY, REHEARSAL, ONAIR, ENDED). 대소문자를 구분하지 않습니다.
sellerId
integer (int64)
검색할 셀러의 ID입니다.
campaignIds
string
방송 ID로 검색합니다. 쉼표로 구분하여 여러 ID를 입력할 수 있습니다. 예: 1234,1235,1236.
campaignKeys
string
campaignId 대신 방송 키로 검색합니다. 쉼표로 구분하여 여러 방송 키를 입력할 수 있습니다. 예: c7671aa83bd2,6229da3b75d4.
sortAscending
boolean
예약 시작 시각 순으로 정렬합니다. 기본값은 false(최신 예약부터)입니다.
기본값false
page
integer (int32)
페이지네이션을 위한 파라미터입니다. 기본값은 1입니다.
기본값1
count
integer (int32)
한 페이지에 표시할 결과 개수를 지정합니다 (최대: 20)
기본값10

응답

200 OKapplication/json

results 의 각 항목은 Campaign 객체입니다.

객체
results객체 배열
campaignMeta객체
campaignId
string
campaignKey
string
accessKey
string
shoplivePlayerUrl
string
title
string
description
string
tags
array
campaignStatus
string
rerun
boolean
다른 방송을 복제해 만든 재방송인지 여부입니다.
userCount
integer (int32)
방송의 시청자 수입니다. 방송 중에는 고객사에 설정된 집계 방식(동시 시청자 수, 페이지뷰 또는 누적 시청자 수)을 따르며, 방송 종료 후에는 최종 집계된 값입니다. 방송 시작 전에는 null입니다.
concurrentUserCount
integer (int32)
동시 시청자 수입니다. 방송 중일 때만 제공되며, 그 외에는 null입니다.
likeCount
integer (int32)
좋아요 수입니다. 방송 중이거나 종료된 후에 제공되며, 시작 전에는 null입니다.
rehearsalPasscode
string
serveReplay
boolean
기본값true
logoImageUrl
brand객체
방송에 설정된 브랜드입니다.
brandId
string
name
string
identifier
string
description
string
imageUrl
string
imageWidth
integer
기본값0
imageHeight
integer
기본값0
createdAt
string
updatedAt
string
preCampaignVideoUrl
preCampaignImageUrl
string
postCampaignImageUrl
string
backgroundImageUrl
string
ieUnsupportImageUrl
string
scheduledStartAt
string
scheduledEndAt
string
campaignStartedAt
campaignEndedAt
createdAt
string
updatedAt
string
stream객체
streamUrl
string
streamKey
string
videoAspectRatio
string
liveUrl
string
liveUrls객체
480p
string
720p
string
previewLiveUrl
string
replayLiveUrl
replayLiveUrls
previewReplayLiveUrl
string
seller객체
sellerId
string
name
string
sellerIdentifier
string
고객사가 정의한 셀러 식별자입니다.
profileUrl
string
storeUrl
string
description
string
셀러에 대한 설명
schemes
totalCount
integer
기본값0
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← Campaign 객체다음 → 방송 생성

방송 API

방송 생성

POST/v2/{accessKey}/campaign

요청 본문 예시입니다.

{
  "campaignMeta": {
    "title": "New campaign name here",
    "description": "Description of the campaign here",
    "tags": ["tag1", "tag2"],
    "rehearsalPasscode": "1234",
    "serveReplay": true
  }
}

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey

본문 파라미터

application/json
객체
campaignMeta객체필수
title
string필수
방송의 제목
description
string
방송에 대한 설명 (방송 설정의 메모)
tags
array[string]
방송에 설정된 태그 정보 (최대 10개까지 설정 가능)
rehearsalPasscode
string
방송이 리허설 상태일 때 입장하기 위한 패스코드
serveReplay
boolean
리플레이를 공개할지 여부
brand객체
brandId
integer (int64)필수
브랜드 ID
scheduledStartAt
string
시간대 오프셋을 포함한 ISO 8601 날짜·시각(YYYY-MM-DDTHH:mm:ss±HH:MM, UTC는 Z)입니다. 응답은 UTC입니다.
scheduledEndAt
string
시간대 오프셋을 포함한 ISO 8601 날짜·시각(YYYY-MM-DDTHH:mm:ss±HH:MM, UTC는 Z)입니다. 응답은 UTC입니다.
seller객체
sellerId
integer (int64)필수
셀러 ID

응답

200 OKapplication/json

응답 본문은 Campaign 객체입니다.

객체
campaignMeta객체
campaignId
string
campaignKey
string
accessKey
string
shoplivePlayerUrl
string
title
string
description
string
campaignStatus
string
rehearsalPasscode
string
serveReplay
boolean
logoImageUrl
null
brand객체
brandId
string
name
string
identifier
string
description
string
imageUrl
string
imageWidth
integer
imageHeight
integer
createdAt
string
updatedAt
string
preCampaignVideoUrl
null
preCampaignImageUrl
string
postCampaignImageUrl
string
backgroundImageUrl
string
ieUnsupportImageUrl
string
scheduledStartAt
string
scheduledEndAt
string
campaignStartedAt
null
campaignEndedAt
null
createdAt
string
updatedAt
string
stream객체
streamUrl
string
streamKey
string
videoAspectRatio
string
liveUrl
string
liveUrls객체
480p
string
720p
string
previewLiveUrl
string
replayLiveUrl
null
replayLiveUrls
null
previewReplayLiveUrl
string
campaignProductList
array
seller객체
sellerId
string
name
string
profileUrl
string
storeUrl
string
description
string
schemes
객체
4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 방송 검색다음 → 재방송 생성

방송 API

재방송 생성

POST/v2/{accessKey}/campaign/{campaignKeyOrId}/rerun

종료된 방송을 복제하여 재방송을 생성합니다.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

본문 파라미터

application/json
객체
campaignMeta객체필수
title
string
재방송의 제목
scheduledStartAt
string필수
재방송 시작 예정 시각입니다(필수). 시간대 오프셋을 포함한 ISO 8601 날짜·시각(YYYY-MM-DDTHH:mm:ss±HH:MM, UTC는 Z)입니다. 응답은 UTC입니다.
copyPopups
boolean
원본 방송의 팝업을 복사할지 여부입니다. 기본값은 true입니다.
기본값true
copyProducts
boolean
원본 방송의 상품을 복사할지 여부입니다. 기본값은 true입니다.
기본값true

응답

200 OKapplication/json

응답 본문은 Campaign 객체입니다.

객체
campaignMeta객체
campaignId
string
campaignKey
string
accessKey
string
shoplivePlayerUrl
string
title
string
description
string
campaignStatus
string
rehearsalPasscode
string
serveReplay
boolean
logoImageUrl
null
brand객체
brandId
string
name
string
identifier
string
description
string
imageUrl
string
imageWidth
integer
imageHeight
integer
createdAt
string
updatedAt
string
preCampaignVideoUrl
null
preCampaignImageUrl
string
postCampaignImageUrl
string
backgroundImageUrl
string
ieUnsupportImageUrl
string
scheduledStartAt
string
scheduledEndAt
string
campaignStartedAt
null
campaignEndedAt
null
createdAt
string
updatedAt
string
stream객체
streamUrl
string
streamKey
string
videoAspectRatio
string
liveUrl
string
liveUrls객체
480p
string
720p
string
previewLiveUrl
string
replayLiveUrl
null
replayLiveUrls
null
previewReplayLiveUrl
string
campaignProductList
array
seller객체
sellerId
string
name
string
profileUrl
string
storeUrl
string
description
string
schemes
객체
4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 방송 생성다음 → 방송 정보 조회

방송 API

방송 정보 조회

GET/v2/{accessKey}/campaign/{campaignKeyOrId}

방송 키 또는 방송 ID로 방송을 조회합니다.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

쿼리 파라미터

includeAuctionDetail
boolean
이 파라미터를 true로 설정하면 campaignProductList의 경매 상품에 경매 상세 정보가 포함됩니다.
기본값false
resolutionLevel
integer (int32)
이 파라미터는 미리보기 영상 URL의 해상도를 결정하며, 1(최저)부터 4(최고)까지 지정할 수 있습니다.
기본값1

응답

200 OKapplication/json

응답 본문은 Campaign 객체입니다.

객체
campaignMeta객체
campaignId
string
campaignKey
string
accessKey
string
shoplivePlayerUrl
string
title
string
tags
array
description
string
campaignStatus
string
rerun
boolean
다른 방송을 복제해 만든 재방송인지 여부입니다.
userCount
integer (int32)
방송의 시청자 수입니다. 방송 중에는 고객사에 설정된 집계 방식(동시 시청자 수, 페이지뷰 또는 누적 시청자 수)을 따르며, 방송 종료 후에는 최종 집계된 값입니다. 방송 시작 전에는 null입니다.
concurrentUserCount
integer (int32)
동시 시청자 수입니다. 방송 중일 때만 제공되며, 그 외에는 null입니다.
likeCount
integer (int32)
좋아요 수입니다. 방송 중이거나 종료된 후에 제공되며, 시작 전에는 null입니다.
rehearsalPasscode
string
serveReplay
boolean
기본값true
logoImageUrl
brand객체
방송에 설정된 브랜드입니다.
brandId
string
name
string
identifier
string
description
string
imageUrl
string
imageWidth
integer
기본값0
imageHeight
integer
기본값0
createdAt
string
updatedAt
string
preCampaignVideoUrl
preCampaignImageUrl
string
postCampaignImageUrl
string
backgroundImageUrl
string
ieUnsupportImageUrl
string
scheduledStartAt
string
scheduledEndAt
string
campaignStartedAt
string
campaignEndedAt
string
createdAt
string
updatedAt
string
stream객체
streamUrl
string
streamKey
string
videoAspectRatio
string
liveUrl
string
liveUrls객체
480p
string
720p
string
previewLiveUrl
string
replayLiveUrl
string
replayLiveUrls객체
480p
string
720p
string
previewReplayLiveUrl
string
campaignProductList객체 배열
productId
string
customerProductId
string
name
string
brand
string
brandIdentifier
string
상품의 브랜드 키(식별자)입니다.
description
string
url
string
sku
string
imageUrl
string
currency
string
showPrice
boolean
기본값true
originalPrice
number
기본값0
discountPrice
number
기본값0
discountRate
number
기본값0
enableAuction
boolean
기본값true
bidStartingPrice
number
bidDuration
integer (int32)
bidIncrementalAmount
number
extendBidDuration
boolean
ctaButtonTitle
string
상품에 표시되는 CTA(call-to-action) 버튼의 제목입니다.
seller객체
sellerId
string
name
string
sellerIdentifier
string
고객사가 정의한 셀러 식별자입니다.
profileUrl
string
storeUrl
string
description
string
schemes
createdAt
string
updatedAt
string
campaignId
string
showingNow
boolean
기본값true
sortOrder
integer
기본값0
stockStatus
string
auction
seller객체
sellerId
string
name
string
sellerIdentifier
string
고객사가 정의한 셀러 식별자입니다.
profileUrl
string
storeUrl
string
description
string
schemes
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 재방송 생성다음 → 방송 삭제

방송 API

방송 삭제

DELETE/v2/{accessKey}/campaign/{campaignKeyOrId}

방송을 삭제합니다. 방송의 campaignStatus가 READY 또는 RESERVED일 때만 삭제할 수 있으며, 그 외에는 403(_s: -114)이 반환됩니다. 재방송의 원본인 방송은 삭제할 수 없습니다(403, _s: -706). 재방송을 먼저 삭제하세요.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

응답

200 OKapplication/json

응답 본문 없음

4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 방송 정보 조회다음 → 방송 복제

방송 API

방송 복제

POST/v2/{accessKey}/campaign/{campaignKeyOrId}/duplicate

기존 방송을 복제하여 새 방송을 생성합니다.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

쿼리 파라미터

duplicatePopups
boolean
방송의 팝업을 복제할지 여부
기본값true
duplicateProducts
boolean
방송의 상품을 복제할지 여부
기본값true

응답

200 OKapplication/json

응답 본문은 Campaign 객체입니다.

객체
campaignMeta객체
campaignId
string
campaignKey
string
accessKey
string
shoplivePlayerUrl
string
title
string
tags
array
description
string
campaignStatus
string
rerun
boolean
다른 방송을 복제해 만든 재방송인지 여부입니다.
userCount
integer (int32)
방송의 시청자 수입니다. 방송 중에는 고객사에 설정된 집계 방식(동시 시청자 수, 페이지뷰 또는 누적 시청자 수)을 따르며, 방송 종료 후에는 최종 집계된 값입니다. 방송 시작 전에는 null입니다.
concurrentUserCount
integer (int32)
동시 시청자 수입니다. 방송 중일 때만 제공되며, 그 외에는 null입니다.
likeCount
integer (int32)
좋아요 수입니다. 방송 중이거나 종료된 후에 제공되며, 시작 전에는 null입니다.
rehearsalPasscode
string
serveReplay
boolean
기본값true
logoImageUrl
brand객체
방송에 설정된 브랜드입니다.
brandId
string
name
string
identifier
string
description
string
imageUrl
string
imageWidth
integer
기본값0
imageHeight
integer
기본값0
createdAt
string
updatedAt
string
preCampaignVideoUrl
preCampaignImageUrl
string
postCampaignImageUrl
string
backgroundImageUrl
string
ieUnsupportImageUrl
string
scheduledStartAt
string
scheduledEndAt
string
campaignStartedAt
string
campaignEndedAt
string
createdAt
string
updatedAt
string
stream객체
streamUrl
string
streamKey
string
videoAspectRatio
string
liveUrl
string
liveUrls객체
480p
string
720p
string
previewLiveUrl
string
replayLiveUrl
string
replayLiveUrls객체
480p
string
720p
string
previewReplayLiveUrl
string
seller객체
sellerId
string
name
string
sellerIdentifier
string
고객사가 정의한 셀러 식별자입니다.
profileUrl
string
storeUrl
string
description
string
schemes
campaignProductCount
integer
방송에 포함된 상품 수
4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 방송 삭제다음 → 방송 수정

방송 API

방송 수정

PUT/v2/{accessKey}/campaign/{campaignKeyOrId}

CampaignMeta 객체의 수정 가능한 필드

필드 이름 타입 설명
title string 방송의 제목
description string 방송에 대한 설명
rehearsalPasscode string 리허설 모드에서 라이브 스트리밍에 입장하기 위한 패스코드
serveReplay boolean 리플레이를 공개할지 여부
scheduledStartAt string 방송 시작 예정 시각. 시간대 오프셋을 포함한 ISO 8601 (YYYY-MM-DDTHH:mm:ss±HH:MM, UTC는 Z). 응답은 UTC
scheduledEndAt string 방송 종료 예정 시각. 시간대 오프셋을 포함한 ISO 8601 (YYYY-MM-DDTHH:mm:ss±HH:MM, UTC는 Z). 응답은 UTC
tags array of string 방송 태그. []를 보내면 모두 제거, 생략하면 유지
brand object 방송 브랜드({"brandId": …}). {}를 보내면 연결 해제, 생략하면 유지

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

본문 파라미터

application/json
객체
campaignMeta객체필수
title
string
방송의 제목
description
string
방송에 대한 설명 (방송 설정의 메모)
tags
array[string]
방송에 설정된 태그 정보 (최대 10개까지 설정 가능)
rehearsalPasscode
string
방송이 리허설 상태일 때 입장하기 위한 패스코드
serveReplay
boolean
리플레이를 공개할지 여부
brand객체
방송의 브랜드
brandId
integer (int64)
브랜드 ID
scheduledStartAt
string
시간대 오프셋을 포함한 ISO 8601 날짜·시각(YYYY-MM-DDTHH:mm:ss±HH:MM, UTC는 Z)입니다. 응답은 UTC입니다.
scheduledEndAt
string
시간대 오프셋을 포함한 ISO 8601 날짜·시각(YYYY-MM-DDTHH:mm:ss±HH:MM, UTC는 Z)입니다. 응답은 UTC입니다.

응답

200 OKapplication/json

응답 본문은 Campaign 객체입니다.

객체
campaignMeta객체
campaignId
string
campaignKey
string
accessKey
string
shoplivePlayerUrl
string
title
string
description
string
campaignStatus
string
rehearsalPasscode
string
serveReplay
boolean
logoImageUrl
null
brand객체
brandId
string
name
string
identifier
string
description
string
imageUrl
string
imageWidth
integer
imageHeight
integer
createdAt
string
updatedAt
string
preCampaignVideoUrl
null
preCampaignImageUrl
string
postCampaignImageUrl
string
backgroundImageUrl
string
ieUnsupportImageUrl
string
scheduledStartAt
string
scheduledEndAt
string
campaignStartedAt
null
campaignEndedAt
null
createdAt
string
updatedAt
string
stream객체
streamUrl
string
streamKey
string
videoAspectRatio
string
liveUrl
string
liveUrls객체
480p
string
720p
string
previewLiveUrl
string
replayLiveUrl
null
replayLiveUrls
null
previewReplayLiveUrl
string
campaignProductList
array
seller
null
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 방송 복제다음 → 방송 내 상품 검색

방송 API

방송 내 상품 검색

GET/v2/{accessKey}/campaign/{campaignKeyOrId}/product

방송 내 상품 검색

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

응답

200 OKapplication/json

results 의 각 항목은 CampaignProduct 객체입니다.

객체
results객체 배열
productId
string
customerProductId
string
name
string
brand
string
brandIdentifier
string
상품의 브랜드 키(식별자)입니다.
description
string
url
string
sku
string
imageUrl
string
currency
string
showPrice
boolean
기본값true
originalPrice
number
기본값0
discountPrice
number
기본값0
discountRate
number
기본값0
enableAuction
boolean
기본값true
bidStartingPrice
number
bidDuration
integer (int32)
bidIncrementalAmount
number
extendBidDuration
boolean
ctaButtonTitle
string
상품에 표시되는 CTA(call-to-action) 버튼의 제목입니다.
seller객체
sellerId
string
name
string
sellerIdentifier
string
고객사가 정의한 셀러 식별자입니다.
profileUrl
string
storeUrl
string
description
string
schemes
createdAt
string
updatedAt
string
campaignId
string
showingNow
boolean
기본값true
sortOrder
integer
기본값0
stockStatus
string
auction
totalCount
integer
기본값0
4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 방송 수정다음 → 방송에 상품 추가

방송 API

방송에 상품 추가

POST/v2/{accessKey}/campaign/{campaignKeyOrId}/product

방송에 상품 추가

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

본문 파라미터

항목이 최소 1개 필요합니다. 각 항목은 productId 또는 customerProductId 중 하나를 지정해야 하며, 한 요청의 모든 항목에는 같은 종류의 식별자를 사용하세요.

application/json
객체 배열
productId
integer (int64)
자동으로 생성되는 고유 상품 ID
customerProductId
string
고객사의 상품 ID로, 고유해야 합니다(고객사가 정의).

응답

200 OKapplication/json
객체
results객체 배열
productId
string
message
status
string
successCount
integer
기본값0
warnCount
integer
기본값0
failCount
integer
기본값0
totalCount
integer
기본값0
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 방송 내 상품 검색다음 → 방송에서 상품 제거

방송 API

방송에서 상품 제거

DELETE/v2/{accessKey}/campaign/{campaignKeyOrId}/product

방송에서 상품 제거

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

본문 파라미터

항목이 최소 1개 필요합니다. 각 항목은 productId 또는 customerProductId 중 하나를 지정해야 하며, 한 요청의 모든 항목에는 같은 종류의 식별자를 사용하세요.

application/json
객체 배열
productId
integer (int64)
자동으로 생성되는 고유 상품 ID
customerProductId
string
고객사의 상품 ID로, 고유해야 합니다(고객사가 정의).

응답

200 OKapplication/json
객체
results객체 배열
productId
string
message
null
status
string
successCount
integer
warnCount
integer
failCount
integer
totalCount
integer
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 방송에 상품 추가다음 → 상위 계정으로 방송 이관

방송 API

상위 계정으로 방송 이관

PUT/v2/{accessKey}/campaign/{campaignKeyOrId}/transferToParent

셀러로부터 상위(부모) 계정으로 방송을 이관합니다.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

쿼리 파라미터

withProduct
boolean
상품도 함께 상위 계정으로 이동할지 여부
기본값false

응답

200 OKapplication/json

응답 본문은 Campaign 객체입니다.

객체
campaignMeta객체
campaignId
string
campaignKey
string
accessKey
string
shoplivePlayerUrl
string
title
string
description
string
campaignStatus
string
rehearsalPasscode
string
serveReplay
boolean
logoImageUrl
null
preCampaignVideoUrl
null
preCampaignImageUrl
string
postCampaignImageUrl
string
backgroundImageUrl
string
ieUnsupportImageUrl
string
scheduledStartAt
string
scheduledEndAt
string
campaignStartedAt
null
campaignEndedAt
null
createdAt
string
updatedAt
string
stream객체
streamUrl
string
streamKey
string
videoAspectRatio
string
liveUrl
string
liveUrls객체
480p
string
720p
string
previewLiveUrl
string
replayLiveUrl
null
replayLiveUrls
null
previewReplayLiveUrl
string
campaignProductList
array
seller
null
4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 방송에서 상품 제거다음 → 방송의 경매 상품 검색

방송 API

방송의 경매 상품 검색

GET/v2/{accessKey}/campaign/{campaignKeyOrId}/product/auction

방송의 경매 상품 검색

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

쿼리 파라미터

groupId
integer (int64)
콘솔에서 설정한 상품 그룹 ID입니다.

응답

200 OKapplication/json

results 의 각 항목은 CampaignProduct 객체입니다.

객체
results객체 배열
productId
string
customerProductId
string
name
string
brand
string
brandIdentifier
string
상품의 브랜드 키(식별자)입니다.
description
string
url
string
sku
string
imageUrl
string
currency
string
showPrice
boolean
기본값true
originalPrice
number
기본값0
discountPrice
number
기본값0
discountRate
number
기본값0
enableAuction
boolean
기본값true
bidStartingPrice
number
기본값0
bidDuration
integer
기본값0
bidIncrementalAmount
number
기본값0
extendBidDuration
boolean
기본값true
ctaButtonTitle
string
상품에 표시되는 CTA(call-to-action) 버튼의 제목입니다.
seller객체
sellerId
string
name
string
sellerIdentifier
string
고객사가 정의한 셀러 식별자입니다.
profileUrl
string
storeUrl
string
description
string
schemes
createdAt
string
updatedAt
string
campaignId
string
showingNow
boolean
기본값true
sortOrder
integer
기본값0
stockStatus
string
auction객체
productId
string
auctionStatus
stringenum
READYONGOINGENDINGENDED
startingPrice
number
기본값0
bidRound
integer
기본값0
currentPrice
number
기본값0
winningPrice
number
recommendedPrices
winner객체
경매에서 낙찰받은 입찰자입니다. 낙찰자가 정해진 채로 경매가 종료되기 전까지는 null입니다.
uid
string
userId
string
입찰자의 사용자 ID입니다.
name
string
leader객체
현재 최고가를 입찰한 입찰자입니다.
uid
string
userId
string
입찰자의 사용자 ID입니다.
name
string
winnerCheckoutScheme
startedAt
integer (int64)
밀리초 단위 Unix 타임스탬프(UTC)입니다.
endingAt
integer (int64)
밀리초 단위 Unix 타임스탬프(UTC)입니다.
endedAt
integer (int64)
밀리초 단위 Unix 타임스탬프(UTC)입니다.
totalCount
integer
기본값0
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 상위 계정으로 방송 이관다음 → 방송에서 모든 상품 제거

방송 API

방송에서 모든 상품 제거

DELETE/v2/{accessKey}/campaign/{campaignKeyOrId}/product/all

방송에서 모든 상품 제거

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

응답

200 OKapplication/json

응답 본문 없음

4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 방송의 경매 상품 검색다음 → 방송 내 상품 순서 변경

방송 API

방송 내 상품 순서 변경

PUT/v2/{accessKey}/campaign/{campaignKeyOrId}/product/order

이 API는 먼저 요청 본문에 지정된 순서대로 상품을 정렬한 다음, 방송에 등록된 나머지 상품을 원래 순서대로 뒤에 추가합니다.


customerProductId를 이용한 정렬 예시

방송에 등록된 customerProductId 값의 원래 순서: sl09, sl08, sl07, sl06, sl05, sl04
요청 처리 후 customerProductId 값의 순서: sl04, sl05, sl07, sl09, sl08, sl06

 curl --location --request PUT 
'https://private.shopliveapi.com/v2/{accessKey}/campaign/{campaignKeyOrId}/product/order'
 --header 'Accept: application/json'
 --header 'Authorization: Bearer {JWT_TOKEN}'
 --header 'Content-Type: application/json'
 --data-raw
 '[
    {"customerProductId": "sl04"},
    {"customerProductId": "sl05"},
    {"customerProductId": "sl07"}
]'

에러 코드

HTTP 상태 코드 에러 코드(_s) 에러 메시지(_e)
404 -710 방송이 존재하지 않습니다.
404 -848 방송에서 정렬할 상품을 찾을 수 없습니다.
400 -840 목록이 존재하지 않거나 데이터가 존재하지 않습니다.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

본문 파라미터

항목이 최소 1개 필요합니다. 각 항목은 productId 또는 customerProductId 중 하나를 지정해야 하며, 한 요청의 모든 항목에는 같은 종류의 식별자를 사용하세요.

application/json
객체 배열
productId
integer (int64)
자동으로 생성되는 고유 상품 ID
customerProductId
string
고객사의 상품 ID로, 고유해야 합니다(고객사가 정의).

응답

200 OKapplication/json

응답 본문 없음

4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 방송에서 모든 상품 제거다음 → 진행 중인 경매 조회

방송 API

진행 중인 경매 조회

GET/v2/{accessKey}/campaign/{campaignKeyOrId}/product/auction/inprogress

진행 중인 경매 조회

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

응답

200 OKapplication/json

응답 본문은 CampaignProduct 객체입니다.

객체
productId
string
customerProductId
string
name
string
brand
string
brandIdentifier
string
상품의 브랜드 키(식별자)입니다.
description
string
url
string
sku
string
imageUrl
string
currency
string
showPrice
boolean
기본값true
originalPrice
number
기본값0
discountPrice
number
기본값0
discountRate
number
기본값0
enableAuction
boolean
기본값true
bidStartingPrice
number
기본값0
bidDuration
integer
기본값0
bidIncrementalAmount
number
기본값0
extendBidDuration
boolean
기본값true
ctaButtonTitle
string
상품에 표시되는 CTA(call-to-action) 버튼의 제목입니다.
seller객체
sellerId
string
name
string
sellerIdentifier
string
고객사가 정의한 셀러 식별자입니다.
profileUrl
string
storeUrl
string
description
string
schemes
createdAt
string
updatedAt
string
campaignId
string
showingNow
boolean
기본값true
sortOrder
integer
기본값0
stockStatus
string
auction객체
productId
string
auctionStatus
stringenum
READYONGOINGENDINGENDED
startingPrice
number
기본값0
bidRound
integer
기본값0
currentPrice
number
기본값0
winningPrice
number
recommendedPrices
array[number]
winner객체
경매에서 낙찰받은 입찰자입니다. 낙찰자가 정해진 채로 경매가 종료되기 전까지는 null입니다.
uid
string
userId
string
입찰자의 사용자 ID입니다.
name
string
leader객체
현재 최고가를 입찰한 입찰자입니다.
uid
string
userId
string
입찰자의 사용자 ID입니다.
name
string
winnerCheckoutScheme
startedAt
integer
밀리초 단위 Unix 타임스탬프(UTC)입니다.
기본값0
endingAt
integer
밀리초 단위 Unix 타임스탬프(UTC)입니다.
기본값0
endedAt
integer (int64)
밀리초 단위 Unix 타임스탬프(UTC)입니다.
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 방송 내 상품 순서 변경다음 → 셀러에게 방송 이관

방송 API

셀러에게 방송 이관

PUT/v2/{accessKey}/campaign/{campaignKeyOrId}/transferToSeller/{sellerId}

셀러에게 방송 이관

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID
sellerId
integer (int64)필수

쿼리 파라미터

withProduct
boolean
상품도 함께 셀러로 이동할지 여부
기본값false

응답

200 OKapplication/json

응답 본문은 Campaign 객체입니다.

객체
campaignMeta객체
campaignId
string
campaignKey
string
accessKey
string
shoplivePlayerUrl
string
title
string
description
string
campaignStatus
string
rehearsalPasscode
string
serveReplay
boolean
logoImageUrl
null
preCampaignVideoUrl
null
preCampaignImageUrl
string
postCampaignImageUrl
string
backgroundImageUrl
string
ieUnsupportImageUrl
string
scheduledStartAt
string
scheduledEndAt
string
campaignStartedAt
null
campaignEndedAt
null
createdAt
string
updatedAt
string
stream객체
streamUrl
string
streamKey
string
videoAspectRatio
string
liveUrl
string
liveUrls객체
480p
string
720p
string
previewLiveUrl
string
replayLiveUrl
null
replayLiveUrls
null
previewReplayLiveUrl
string
campaignProductList
array
seller객체
sellerId
string
name
string
profileUrl
string
storeUrl
string
description
string
schemes
객체
4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 진행 중인 경매 조회다음 → Popup 객체

팝업 API

방송 내 팝업 검색

GET/v2/{accessKey}/campaign/{campaignKeyOrId}/popup

방송에 등록된 팝업 목록을 조회합니다. 응답은 팝업 항목의 JSON 배열입니다.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

응답

200 OKapplication/json

배열의 각 항목은 팝업 목록 항목입니다.

객체 배열
popupResourceId
string
팝업 식별자
title
string
팝업 제목
description
string
팝업 설명
contents객체필수
팝업 콘텐츠입니다. 아래 필드는 COUPON 팝업을 설명합니다. 다른 타입 팝업의 콘텐츠는 필드가 달라 여기에 문서화되어 있지 않습니다.
popupType
string필수
콘텐츠의 팝업 타입입니다. 최상위 popupType과 같습니다(쿠폰 팝업은 COUPON)
title
string
팝업 콘텐츠 제목
description
string
팝업 콘텐츠 설명
couponDeliveryType
stringenum
INSTANTDWELL_TIME
쿠폰 발급 방식. INSTANT(즉시) 또는 DWELL_TIME(체류 시간 경과 후). 값이 없으면 INSTANT와 같습니다.
couponDeliverySeconds
integer
couponDeliveryType이 DWELL_TIME일 때만 적용됩니다.
imageUrl
string
쿠폰 이미지 URL. 생성/수정 요청으로 보낸 외부 URL은 Shoplive CDN URL(image.shoplive.cloud)로 변환됩니다.
imageWidth
integer
노출 너비(px). 0(기본값)이면 플레이어가 기본 너비인 164px로 렌더링합니다.
기본값0
textImageListTitle
string
텍스트+이미지 목록 제목
textImageList객체 배열
텍스트+이미지 항목 목록
imageUrl
string
이미지 URL
text
string
표시할 텍스트
popupType
stringenum
TEXT_IMAGE
TEXT_IMAGE 고정
기본값TEXT_IMAGE
action
string
클릭 시 동작. 자유 형식 문자열입니다.
payload
string
클릭 시 동작의 페이로드. 자유 형식 문자열입니다.
action
stringenum
CUSTOM_ACTION
CUSTOM_ACTION 또는 null(생략)만 허용됩니다. 그 외 값을 보내면 400이 반환됩니다.
payload
string
JSON으로 직렬화된 문자열입니다. 유효한 JSON이 아니면 400이 반환됩니다. 쿠폰을 매칭하려면 {"coupon":"<couponId>"}를 포함하세요.
link
string
더 이상 권장하지 않습니다(Deprecated). 신규 연동에는 사용하지 마세요.
dismissType
stringenum
KEEPAUTOMANUAL
popupType
string
팝업 타입입니다. 목록에는 콘솔에서 만든 다른 타입의 팝업도 포함될 수 있으니, COUPON이 아닌 팝업은 건너뛰세요.
dimmed
boolean
duration
integer
showingNow
boolean
현재 라이브에 노출 중인지 여부
clickCount
integer
누적 클릭 수
usedAt
integer (int64)
팝업이 처음 노출된 시각입니다(밀리초 단위 Unix 타임스탬프, UTC). 한 번도 노출되지 않았다면 null입니다.
createdAt
integer (int64)
팝업이 생성된 시각입니다(밀리초 단위 Unix 타임스탬프, UTC).
updatedAt
integer (int64)
팝업이 마지막으로 수정된 시각입니다(밀리초 단위 Unix 타임스탬프, UTC).

이전 ← Popup 객체다음 → 쿠폰 팝업 생성

팝업 API

쿠폰 팝업 생성

POST/v2/{accessKey}/campaign/{campaignKeyOrId}/popup/coupon

쿠폰 팝업 1건을 생성하고 방송에 연결합니다. 단일 트랜잭션으로 원자적으로 처리되며, 응답은 생성된 팝업의 식별자만 반환합니다 — 전체 상태를 확인하려면 팝업 목록 조회(GET) 엔드포인트를 사용하세요.

검증 규칙: popupType은 최상위와 contents 내부 모두 COUPON이어야 합니다. contents.action은 CUSTOM_ACTION 또는 생략만 허용하며, 그 외 값을 보내면 400이 반환됩니다. contents.payload는 값이 있으면 유효한 JSON 문자열이어야 하며, 아니면 400이 반환됩니다. 쿠폰을 매칭하려면 contents.payload에 {"coupon":"<couponId>"}를 포함하세요. contents.imageUrl 또는 contents.imageBase64 중 하나만 보낼 수 있으며(둘 다 보내면 400), 외부 이미지는 서버가 동기적으로 내려받아 Shoplive CDN(image.shoplive.cloud)으로 변환한 뒤 저장합니다. Base64 이미지가 디코딩된 바이트 기준 5MB를 초과하면 400이 반환됩니다.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

본문 파라미터

application/json
객체
title
string
팝업 제목(관리용 라벨). 선택 사항입니다.
description
string
팝업 설명(관리용 메모)
popupType
string필수enum
COUPON
COUPON 고정. 다른 값을 보내면 400이 반환됩니다.
기본값COUPON
contents객체필수
팝업 콘텐츠. popupType은 COUPON 고정입니다.
popupType
string필수enum
COUPON
COUPON 고정. 최상위 popupType과 일치해야 합니다.
기본값COUPON
title
string
팝업 콘텐츠 제목
description
string
팝업 콘텐츠 설명
couponDeliveryType
stringenum
INSTANTDWELL_TIME
쿠폰 발급 방식. INSTANT(즉시) 또는 DWELL_TIME(체류 시간 경과 후). 선택 사항이며, 생략하면 INSTANT처럼 동작합니다.
couponDeliverySeconds
integer
couponDeliveryType이 DWELL_TIME일 때만 적용됩니다.
imageUrl
string
쿠폰 이미지 URL. imageBase64와 함께 사용할 수 없습니다(400). PNG·JPEG·GIF, 5MB 이하만 지원하며 리다이렉트되는 URL은 사용할 수 없습니다. 외부 URL은 Shoplive CDN URL(image.shoplive.cloud)로 자동 변환됩니다.
imageBase64
string
Base64로 인코딩된 이미지(data: 접두어 없이). PNG·JPEG·GIF, 5MB 이하만 지원합니다. imageUrl과 함께 사용할 수 없습니다(400).
imageContentType
string
이미지의 MIME 타입. 선택 사항입니다.
imageWidth
integer
노출 너비(px). 0(기본값)이면 플레이어가 기본 너비인 164px로 렌더링합니다.
기본값0
textImageListTitle
string
텍스트+이미지 목록 제목
textImageList객체 배열
텍스트+이미지 항목 목록
imageUrl
string
이미지 URL
text
string
표시할 텍스트
popupType
stringenum
TEXT_IMAGE
TEXT_IMAGE 고정
기본값TEXT_IMAGE
action
string
클릭 시 동작. 자유 형식 문자열입니다.
payload
string
클릭 시 동작의 페이로드. 자유 형식 문자열입니다.
action
stringenum
CUSTOM_ACTION
CUSTOM_ACTION 또는 null(생략)만 허용됩니다. 그 외 값을 보내면 400이 반환됩니다.
payload
string
JSON으로 직렬화된 문자열입니다. 유효한 JSON이 아니면 400이 반환됩니다. 쿠폰을 매칭하려면 {"coupon":"<couponId>"}를 포함하세요.
link
string
더 이상 권장하지 않습니다(Deprecated). 신규 연동에는 사용하지 마세요.
dismissType
stringenum
KEEPAUTOMANUAL
클릭 시 동작. 기본값은 AUTO입니다.
기본값AUTO
dimmed
boolean
배경 딤(dim) 적용 여부. 기본값은 false입니다. COUPON 팝업에는 적용되지 않습니다.
기본값false
duration
integer
노출 지속 시간(초). 기본값은 0(제한 없음)입니다.
기본값0
broadcastStrategy객체
전송 전략. 기본값은 {"type":"ALL_AT_ONCE"}입니다.
type
stringenum
ALL_AT_ONCECOUNT_PER_SECONDTERM_DISTRIBUTED
전송 전략 타입
기본값ALL_AT_ONCE
tags
array[string]
팝업에 부여된 태그 목록

응답

200 OKapplication/json
객체
popupResourceId
string
생성된 팝업의 식별자
4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 방송 내 팝업 검색다음 → 쿠폰 팝업 수정

팝업 API

쿠폰 팝업 수정

PUT/v2/{accessKey}/campaign/{campaignKeyOrId}/popup/coupon/{popupResourceId}

방송에 등록된 쿠폰 팝업의 메타데이터/콘텐츠를 수정합니다. 요청 형태는 생성(create)과 동일합니다. id/customerId/seller/adminId/adminName/createdAt/updatedAt은 서버가 설정하므로 보내지 않아도 됩니다. 쿠폰(COUPON) 타입의 팝업만 수정할 수 있습니다. 대상 {popupResourceId}가 이 방송에 등록되어 있지 않거나 COUPON 타입이 아니면 404가 반환됩니다. 응답 본문은 없습니다 — 수정된 상태는 팝업 목록 조회(GET) 엔드포인트로 확인하세요.

검증 규칙은 생성(create)과 동일합니다: contents.action은 CUSTOM_ACTION 또는 생략만 허용하고, contents.payload는 값이 있으면 유효한 JSON 문자열이어야 하며, contents.imageUrl/contents.imageBase64는 동시에 사용할 수 없고(400), 5MB 제한이 적용됩니다.

이 팝업이 다른 방송에도 연결되어 있다면, contents/dismissType/duration 변경은 연결된 모든 방송에 한꺼번에 반영됩니다.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID
popupResourceId
integer필수
팝업 리소스 ID

본문 파라미터

application/json
객체
title
string
팝업 제목(관리용 라벨). 선택 사항입니다.
description
string
팝업 설명(관리용 메모)
popupType
string필수enum
COUPON
COUPON 고정. 다른 값을 보내면 400이 반환됩니다.
기본값COUPON
contents객체필수
팝업 콘텐츠. popupType은 COUPON 고정입니다.
popupType
string필수enum
COUPON
COUPON 고정. 최상위 popupType과 일치해야 합니다.
기본값COUPON
title
string
팝업 콘텐츠 제목
description
string
팝업 콘텐츠 설명
couponDeliveryType
stringenum
INSTANTDWELL_TIME
쿠폰 발급 방식. INSTANT(즉시) 또는 DWELL_TIME(체류 시간 경과 후). 선택 사항이며, 생략하면 INSTANT처럼 동작합니다.
couponDeliverySeconds
integer
couponDeliveryType이 DWELL_TIME일 때만 적용됩니다.
imageUrl
string
쿠폰 이미지 URL. imageBase64와 함께 사용할 수 없습니다(400). PNG·JPEG·GIF, 5MB 이하만 지원하며 리다이렉트되는 URL은 사용할 수 없습니다. 외부 URL은 Shoplive CDN URL(image.shoplive.cloud)로 자동 변환됩니다.
imageBase64
string
Base64로 인코딩된 이미지(data: 접두어 없이). PNG·JPEG·GIF, 5MB 이하만 지원합니다. imageUrl과 함께 사용할 수 없습니다(400).
imageContentType
string
이미지의 MIME 타입. 선택 사항입니다.
imageWidth
integer
노출 너비(px). 0(기본값)이면 플레이어가 기본 너비인 164px로 렌더링합니다.
기본값0
textImageListTitle
string
텍스트+이미지 목록 제목
textImageList객체 배열
텍스트+이미지 항목 목록
imageUrl
string
이미지 URL
text
string
표시할 텍스트
popupType
stringenum
TEXT_IMAGE
TEXT_IMAGE 고정
기본값TEXT_IMAGE
action
string
클릭 시 동작. 자유 형식 문자열입니다.
payload
string
클릭 시 동작의 페이로드. 자유 형식 문자열입니다.
action
stringenum
CUSTOM_ACTION
CUSTOM_ACTION 또는 null(생략)만 허용됩니다. 그 외 값을 보내면 400이 반환됩니다.
payload
string
JSON으로 직렬화된 문자열입니다. 유효한 JSON이 아니면 400이 반환됩니다. 쿠폰을 매칭하려면 {"coupon":"<couponId>"}를 포함하세요.
link
string
더 이상 권장하지 않습니다(Deprecated). 신규 연동에는 사용하지 마세요.
dismissType
stringenum
KEEPAUTOMANUAL
클릭 시 동작. 기본값은 AUTO입니다.
기본값AUTO
dimmed
boolean
배경 딤(dim) 적용 여부. 기본값은 false입니다. COUPON 팝업에는 적용되지 않습니다.
기본값false
duration
integer
노출 지속 시간(초). 기본값은 0(제한 없음)입니다.
기본값0
broadcastStrategy객체
전송 전략. 기본값은 {"type":"ALL_AT_ONCE"}입니다.
type
stringenum
ALL_AT_ONCECOUNT_PER_SECONDTERM_DISTRIBUTED
전송 전략 타입
기본값ALL_AT_ONCE
tags
array[string]
팝업에 부여된 태그 목록

응답

204 No Contentapplication/json

응답 본문 없음

4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 쿠폰 팝업 생성다음 → 방송에서 팝업 연결 해제

팝업 API

팝업 활성화

PUT/v2/{accessKey}/campaign/{campaignKeyOrId}/popup/{popupResourceId}/activate

팝업을 라이브 시청자에게 즉시 노출합니다. 호출 후 해당 팝업의 showingNow는 true입니다(팝업 목록 응답 기준).

멱등(Idempotent): showingNow가 이미 true일 때 다시 호출해도 아무것도 바뀌지 않고 204가 반환됩니다(재시도하거나 여러 번 호출해도 안전합니다).

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID
popupResourceId
integer필수
팝업 리소스 ID

쿼리 파라미터

broadcastDelay
integer
브로드캐스트 지연 시간(밀리초). 기본값은 0입니다. 음수를 보내면 400이 반환됩니다.
기본값0

응답

204 No Contentapplication/json

응답 본문 없음

4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 방송에서 팝업 연결 해제다음 → 팝업 비활성화

팝업 API

팝업 비활성화

PUT/v2/{accessKey}/campaign/{campaignKeyOrId}/popup/{popupResourceId}/deactivate

팝업을 라이브 시청자에게서 즉시 숨깁니다. 호출 후 해당 팝업의 showingNow는 false입니다(팝업 목록 응답 기준).

멱등(Idempotent): showingNow가 이미 false일 때 다시 호출해도 아무것도 바뀌지 않고 204가 반환됩니다(재시도하거나 여러 번 호출해도 안전합니다).

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID
popupResourceId
integer필수
팝업 리소스 ID

쿼리 파라미터

broadcastDelay
integer
브로드캐스트 지연 시간(밀리초). 기본값은 0입니다. 음수를 보내면 400이 반환됩니다.
기본값0

응답

204 No Contentapplication/json

응답 본문 없음

4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 팝업 활성화다음 → Product 객체

상품 API

Product 객체

속성 이름

타입

설명

productId

String!

자동으로 생성되는 고유한 상품 ID입니다.

customerProductId

String?

고객사의 상품 ID이며 고유해야 합니다(고객사가 직접 정의). customerProductId는 Product API로만 설정할 수 있으며, Shoplive 어드민 도구에는 이 필드의 입력란이 없습니다.

name

String!

상품 이름입니다.

brand

String?

브랜드 이름입니다.

brandIdentifier

String?

고객사가 설정한 상품의 브랜드 키(식별자)입니다.

description

String?

상품에 대한 설명입니다.

url

String!

상품 URL입니다. Shoplive Player에서 상품 정보를 클릭했을 때 이동하는 대상 URL입니다.

sku

String?

상품의 SKU 정보입니다 (고객사가 정의)

imageUrl

String?

상품 이미지 URL입니다.

currency

String!

가격의 통화입니다.

showPrice

Boolean!

Shoplive Player에서 가격을 표시할지 여부입니다.

originalPrice

Double?

예: 20.00 (통화가 USD인 경우 $20.00)

discountPrice

Double?

예: 15.00 (통화가 USD인 경우 $15.00)

discountRate

Double?

예: 25.00 (할인율이 25%인 경우)

enableAuction

Boolean!

상품이 경매를 지원하는지 여부입니다.

bidStartingPrice

Double?

경매 시작 가격입니다(예: 0.99). enableAuction이 true이면 필수입니다.

bidDuration

Integer?

경매의 입찰 지속 시간(초)입니다. 이 값은 enableAuction이 true일 때 필수입니다.

bidIncrementalAmount

Double?

입찰 증가 단위 금액입니다(예: 1.00). enableAuction이 true이면 필수입니다.

extendBidDuration

Boolean?

경매 종료 직전에 입찰이 들어오면 남은 입찰 시간을 연장할지 여부입니다. 연장 시간은 고객사의 경매 설정을 따릅니다.

ctaButtonTitle

String?

상품의 CTA(call-to-action) 제목을 커스터마이즈할 수 있습니다. UI 커스터마이즈가 필요하므로 Shoplive와 상의가 필요합니다. 이 기능을 사용하고 싶으시면 ask@shoplive.cloud로 문의해 주세요.

locked

Boolean!

상품이 방송이나 숏폼에 등록되어 있으면 true입니다. 잠긴 상품을 force=true(기본값)로 삭제하면 방송에서 분리된 뒤 삭제됩니다. force=false이면 삭제되지 않습니다. 숏폼에 등록된 상품은 삭제되지 않습니다.

seller

Seller?

상품을 소유한 셀러 정보입니다.

createdAt

String!

상품이 생성된 일시입니다 (형식: YYYY-MM-DD'T'HH:mm:ss'Z')

updatedAt

String!

상품이 수정된 일시입니다 (형식: YYYY-MM-DD'T'HH:mm:ss'Z')

예시

일반 상품

json
{
    "productId": "1001",
    "customerProductId": "SHOPLIVE_PRODUCT_1",
    "name": "Keyring",
    "brand": "SHOPLIVE",
    "brandIdentifier": "SHOPLIVE_BRAND_IDENTIFIER",
    "description": null,
    "url": "https://www.shoplive.cloud/en",
    "sku": "SKU001",
    "imageUrl": "https://image.shoplive.cloud/e05d1464-1942-4e4e-bb0b-c4310167d465.jpeg",
    "currency": "USD",
    "showPrice": true,
    "originalPrice": 20.0,
    "discountPrice": 10.0,
    "discountRate": 50.0,
    "enableAuction": false,
    "bidStartingPrice": null,
    "bidDuration": null,
    "bidIncrementalAmount": null,
  	"extendBidDuration": null,
    "ctaButtonTitle": "Buy It Now",
    "locked": false,
    "seller": {
        "sellerId": "1",
        "name": "Shoplive Product Store",
        "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
        "storeUrl": "https://shoplive.cloud",
        "description": "Description of the seller",
        "schemes": null
    },
    "createdAt": "2026-05-20T08:01:05Z",
    "updatedAt": "2026-05-20T11:27:34Z"
}

경매 상품

json
{
    "productId": "1004",
    "customerProductId": "SHOPLIVE_PRODUCT_4",
    "name": "Mug",
    "brand": "SHOPLIVE",
    "brandIdentifier": "SHOPLIVE_BRAND_IDENTIFIER",
    "description": null,
    "url": "https://www.shoplive.cloud/en",
    "sku": "SKU004",
    "imageUrl": "https://image.shoplive.cloud/b22c72c7-d2f8-49c3-83f0-314c59740649.jpeg",
    "currency": "USD",
    "showPrice": true,
    "originalPrice": 10.0,
    "discountPrice": 7.0,
    "discountRate": 30.0,
    "enableAuction": true,
    "bidStartingPrice": 7.0,
    "bidDuration": 120,
    "bidIncrementalAmount": 1.0,
    "extendBidDuration": true,
    "ctaButtonTitle": "Bid",
    "locked": false,
    "seller": {
        "sellerId": "1",
        "name": "Shoplive Product Store",
        "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
        "storeUrl": "https://shoplive.cloud",
        "description": "Description of the seller",
        "schemes": null
    },
    "createdAt": "2026-05-20T08:01:05Z",
    "updatedAt": "2026-05-20T11:27:34Z"
}

이전 ← 팝업 비활성화다음 → 상품 검색

상품 API

상품 검색

GET/v2/{accessKey}/product

상품 검색

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey

쿼리 파라미터

name
string
상품 이름을 검색할 키워드
brand
string
상품 브랜드를 검색할 키워드
description
string
상품 설명을 검색할 키워드
sellerId
integer (int64)
검색할 셀러의 ID입니다.
sku
string
상품 sku를 검색할 키워드
url
string
상품 url을 검색할 키워드
sortAscending
boolean
생성 순(상품 ID)으로 정렬합니다. 기본값은 false(최근 생성부터)입니다.
기본값false
page
integer (int32)
페이지네이션을 위한 파라미터입니다. 기본값은 1입니다.
기본값1
count
integer (int32)
한 페이지에 표시할 결과 개수를 지정합니다 (최대: 100)
기본값30

응답

200 OKapplication/json

results 의 각 항목은 Product 객체입니다.

객체
results객체 배열
productId
string
customerProductId
string
name
string
brand
string
brandIdentifier
string
상품의 브랜드 키(식별자)입니다.
description
string
url
string
sku
string
imageUrl
string
currency
string
showPrice
boolean
기본값true
originalPrice
number
기본값0
discountPrice
number
기본값0
discountRate
number
기본값0
enableAuction
boolean
기본값true
bidStartingPrice
number
bidDuration
integer (int32)
bidIncrementalAmount
number
extendBidDuration
boolean
ctaButtonTitle
string
상품에 표시되는 CTA(call-to-action) 버튼의 제목입니다.
locked
boolean
기본값true
seller객체
sellerId
string
name
string
sellerIdentifier
string
고객사가 정의한 셀러 식별자입니다.
profileUrl
string
storeUrl
string
description
string
schemes
createdAt
string
updatedAt
string
totalCount
integer
기본값0
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← Product 객체다음 → 상품 생성

상품 API

상품 생성

POST/v2/{accessKey}/product

상품을 등록합니다. upsert가 아니므로 이미 있는 customerProductId 항목은 status: FAIL로 돌아옵니다. 각 항목의 status는 CREATE, WARN(등록됐지만 이미지를 불러오지 못함), FAIL 중 하나입니다.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey

본문 파라미터

항목이 최소 1개 필요합니다.

application/json
객체 배열
customerProductId
string
고객사의 상품 ID로, 고유해야 합니다(고객사가 정의).
name
string필수
상품 이름(필수). 값이 없는 항목은 status가 FAIL로 반환됩니다.
brand
string
브랜드 이름
brandIdentifier
string
브랜드 키
description
string
상품에 대한 설명
url
string필수
상품 URL(필수). Shoplive Player에서 상품 정보를 클릭했을 때 이동하는 대상 URL입니다. 값이 없으면 해당 항목이 실패(status가 FAIL)합니다.
sku
string
상품의 SKU 정보입니다 (고객사가 정의)
imageUrl
string
상품 썸네일 이미지 URL
currency
string
가격의 통화
showPrice
boolean
가격을 표시할지 여부입니다.
originalPrice
number (double)
예: 20.00 (통화가 USD인 경우 $20.00)
discountPrice
number (double)
예: 15.00 (통화가 USD인 경우 $15.00)
discountRate
number (double)
예: 25.00 (할인율이 25%인 경우)
enableAuction
boolean
상품이 경매를 지원하는지 여부
bidStartingPrice
number (double)
경매 시작 가격입니다(예: 0.99). enableAuction이 true이면 필수입니다.
bidDuration
integer (int32)
경매의 입찰 시간(초)입니다. 이 값은 enableAuction이 true일 때 필수입니다.
bidIncrementalAmount
number (double)
입찰 증가 단위 금액입니다(예: 1.00). enableAuction이 true이면 필수입니다.
extendBidDuration
boolean
경매 종료 직전에 입찰이 들어오면 남은 입찰 시간을 연장할지 여부입니다. 연장하려면 true를 보내세요. 연장 시간은 고객사의 경매 설정을 따릅니다.
seller객체
sellerId
integer (int64)필수
셀러 ID

응답

200 OKapplication/json
객체
results객체 배열
productId
string
customerProductId
string
name
string
brand
string
brandIdentifier
string
상품의 브랜드 키(식별자)입니다.
description
string
url
string
sku
string
imageUrl
string
currency
string
showPrice
boolean
기본값true
originalPrice
number
기본값0
discountPrice
number
기본값0
discountRate
number
기본값0
enableAuction
boolean
기본값true
bidStartingPrice
number
bidDuration
integer (int32)
bidIncrementalAmount
number
extendBidDuration
boolean
ctaButtonTitle
string
상품에 표시되는 CTA(call-to-action) 버튼의 제목입니다.
locked
boolean
기본값true
seller객체
sellerId
string
name
string
sellerIdentifier
string
고객사가 정의한 셀러 식별자입니다.
profileUrl
string
storeUrl
string
description
string
schemes
createdAt
string
updatedAt
string
message
string
status
string
successCount
integer
기본값0
warnCount
integer
기본값0
failCount
integer
기본값0
totalCount
integer
기본값0
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 상품 검색다음 → 상품 정보 조회

상품 API

상품 정보 조회

GET/v2/{accessKey}/product/{productId}

상품 정보 조회

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
productId
integer (int64)필수
상품 ID

응답

200 OKapplication/json

응답 본문은 Product 객체입니다.

객체
productId
string
customerProductId
string
name
string
brand
string
brandIdentifier
string
상품의 브랜드 키(식별자)입니다.
description
string
url
string
sku
string
imageUrl
string
currency
string
showPrice
boolean
기본값true
originalPrice
number
기본값0
discountPrice
number
기본값0
discountRate
number
기본값0
enableAuction
boolean
기본값true
bidStartingPrice
number
bidDuration
integer (int32)
bidIncrementalAmount
number
extendBidDuration
boolean
ctaButtonTitle
string
상품에 표시되는 CTA(call-to-action) 버튼의 제목입니다.
locked
boolean
기본값true
seller객체
sellerId
string
name
string
sellerIdentifier
string
고객사가 정의한 셀러 식별자입니다.
profileUrl
string
storeUrl
string
description
string
schemes
createdAt
string
updatedAt
string
4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 상품 생성다음 → customerProductId로 상품 정보 조회

상품 API

customerProductId로 상품 정보 조회

GET/v2/{accessKey}/product/customerProductId/{customerProductId}

customerProductId로 상품 정보 조회

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
customerProductId
string필수
고객사가 지정한 상품 ID(customerProductId)

응답

200 OKapplication/json

응답 본문은 Product 객체입니다.

객체
productId
string
customerProductId
string
name
string
brand
string
brandIdentifier
string
상품의 브랜드 키(식별자)입니다.
description
string
url
string
sku
string
imageUrl
string
currency
string
showPrice
boolean
기본값true
originalPrice
number
기본값0
discountPrice
number
기본값0
discountRate
number
기본값0
enableAuction
boolean
기본값true
bidStartingPrice
number
bidDuration
integer (int32)
bidIncrementalAmount
number
extendBidDuration
boolean
ctaButtonTitle
string
상품에 표시되는 CTA(call-to-action) 버튼의 제목입니다.
locked
boolean
기본값true
seller객체
sellerId
string
name
string
sellerIdentifier
string
고객사가 정의한 셀러 식별자입니다.
profileUrl
string
storeUrl
string
description
string
schemes
createdAt
string
updatedAt
string
4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 상품 정보 조회다음 → 상품 수정

상품 API

상품 수정

PUT/v2/{accessKey}/product

상품을 수정합니다. 각 항목은 customerProductId 또는 productId로 지정하며, 한 요청에서는 한 가지 식별자만 사용하세요. 각 항목의 status는 UPDATE 또는 FAIL입니다.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey

본문 파라미터

항목이 최소 1개 필요합니다. 각 항목은 productId 또는 customerProductId 중 하나를 지정해야 하며, 한 요청의 모든 항목에는 같은 종류의 식별자를 사용하세요.

application/json
객체 배열
productId
integer (int64)
자동으로 생성되는 고유 상품 ID(productId 또는 customerProductId 중 하나는 필수)
customerProductId
string
고객사의 상품 ID로, 고유해야 합니다(productId 또는 customerProductId 중 하나는 필수)
name
string
상품 이름입니다. 생략하거나 비어 있으면 현재 이름이 유지됩니다.
brand
string
브랜드 이름
brandIdentifier
string
브랜드 키
description
string
상품에 대한 설명
url
string
상품 URL입니다. Shoplive Player에서 상품 정보를 클릭했을 때 이동하는 대상 URL입니다. 생략하거나 비어 있으면 현재 URL이 유지됩니다.
sku
string
상품의 SKU 정보입니다 (고객사가 정의)
imageUrl
string
상품 썸네일 이미지 URL
currency
string
가격의 통화
showPrice
boolean
가격을 표시할지 여부입니다.
originalPrice
number (double)
예: 20.00 (통화가 USD인 경우 $20.00)
discountPrice
number (double)
예: 15.00 (통화가 USD인 경우 $15.00)
discountRate
number (double)
예: 25.00 (할인율이 25%인 경우)
enableAuction
boolean
상품이 경매를 지원하는지 여부
bidStartingPrice
number (double)
경매 시작 가격입니다(예: 0.99). enableAuction이 true이면 필수입니다.
bidDuration
integer (int32)
경매의 입찰 시간(초)입니다. 이 값은 enableAuction이 true일 때 필수입니다.
bidIncrementalAmount
number (double)
입찰 증가 단위 금액입니다(예: 1.00). enableAuction이 true이면 필수입니다.
extendBidDuration
boolean
경매 종료 직전에 입찰이 들어오면 남은 입찰 시간을 연장할지 여부입니다. true이면 켜고, false이면 끄며, 생략하면 상품의 현재 설정이 유지됩니다. 연장 시간은 고객사의 경매 설정을 따릅니다.
seller객체
sellerId
integer (int64)필수
셀러 ID

응답

200 OKapplication/json
객체
results객체 배열
productId
string
name
string
brand
string
description
string
url
string
sku
string
imageUrl
string
currency
string
showPrice
boolean
기본값true
originalPrice
number
기본값0
discountPrice
number
기본값0
discountRate
number
기본값0
enableAuction
boolean
기본값true
bidStartingPrice
number
bidDuration
bidIncrementalAmount
number
extendBidDuration
locked
boolean
기본값true
seller
createdAt
string
updatedAt
string
message
status
string
successCount
integer
기본값0
warnCount
integer
기본값0
failCount
integer
기본값0
totalCount
integer
기본값0
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← customerProductId로 상품 정보 조회다음 → 상품 삭제

상품 API

상품 삭제

DELETE/v2/{accessKey}/product

상품을 삭제합니다. 각 항목은 customerProductId 또는 productId로 지정하며, 한 요청에서는 한 가지 식별자만 사용하세요. 각 항목의 status는 DELETE 또는 FAIL입니다.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey

쿼리 파라미터

force
boolean
강제로 삭제할지 여부입니다. true(기본값)이면 방송에 등록된 상품은 해당 방송에서 분리된 뒤 삭제됩니다. false이면 방송에 등록된 상품은 삭제되지 않고 실패한 항목(results[]에서 status가 FAIL)으로 반환됩니다. 숏폼에 등록된 상품은 이 값과 관계없이 삭제되지 않습니다.
기본값true

본문 파라미터

항목이 최소 1개 필요합니다. 각 항목은 productId 또는 customerProductId 중 하나를 지정해야 하며, 한 요청의 모든 항목에는 같은 종류의 식별자를 사용하세요.

application/json
객체 배열
productId
integer (int64)
자동으로 생성되는 고유 상품 ID
customerProductId
string
고객사의 상품 ID로, 고유해야 합니다(고객사가 정의).

응답

200 OKapplication/json
객체
results객체 배열
productId
string
message
string
status
string
successCount
integer
기본값0
warnCount
integer
기본값0
failCount
integer
기본값0
totalCount
integer
기본값0
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 상품 수정다음 → 상품을 셀러에게 이관

상품 API

상품을 셀러에게 이관

PUT/v2/{accessKey}/product/transferToSeller/{sellerId}

상품을 셀러에게 이관

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
sellerId
integer (int64)필수

본문 파라미터

항목이 최소 1개 필요합니다. 각 항목은 productId 또는 customerProductId 중 하나를 지정해야 하며, 한 요청의 모든 항목에는 같은 종류의 식별자를 사용하세요.

application/json
객체 배열
productId
integer (int64)
자동으로 생성되는 고유 상품 ID
customerProductId
string
고객사의 상품 ID로, 고유해야 합니다(고객사가 정의).

응답

200 OKapplication/json
객체
results객체 배열
productId
string
customerProductId
string
name
string
brand
string
brandIdentifier
string
상품의 브랜드 키(식별자)입니다.
description
string
url
string
sku
string
imageUrl
string
currency
string
showPrice
boolean
기본값true
originalPrice
number
기본값0
discountPrice
number
기본값0
discountRate
number
기본값0
enableAuction
boolean
기본값true
bidStartingPrice
number
bidDuration
integer (int32)
bidIncrementalAmount
number
extendBidDuration
boolean
ctaButtonTitle
string
상품에 표시되는 CTA(call-to-action) 버튼의 제목입니다.
locked
boolean
기본값true
seller객체
sellerId
string
name
string
sellerIdentifier
string
고객사가 정의한 셀러 식별자입니다.
profileUrl
string
storeUrl
string
description
string
schemes
createdAt
string
updatedAt
string
message
status
string
successCount
integer
기본값0
warnCount
integer
기본값0
failCount
integer
기본값0
totalCount
integer
기본값0
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 상품 삭제다음 → 상품을 상위 계정으로 이관

상품 API

상품을 상위 계정으로 이관

PUT/v2/{accessKey}/product/transferToParent

상품을 상위 계정으로 이관

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey

본문 파라미터

항목이 최소 1개 필요합니다. 각 항목은 productId 또는 customerProductId 중 하나를 지정해야 하며, 한 요청의 모든 항목에는 같은 종류의 식별자를 사용하세요.

application/json
객체 배열
productId
integer (int64)
자동으로 생성되는 고유 상품 ID
customerProductId
string
고객사의 상품 ID로, 고유해야 합니다(고객사가 정의).

응답

200 OKapplication/json
객체
results객체 배열
productId
string
customerProductId
string
name
string
brand
string
brandIdentifier
string
상품의 브랜드 키(식별자)입니다.
description
string
url
string
sku
string
imageUrl
string
currency
string
showPrice
boolean
기본값true
originalPrice
number
기본값0
discountPrice
number
기본값0
discountRate
number
기본값0
enableAuction
boolean
기본값true
bidStartingPrice
number
bidDuration
integer (int32)
bidIncrementalAmount
number
extendBidDuration
boolean
ctaButtonTitle
string
상품에 표시되는 CTA(call-to-action) 버튼의 제목입니다.
locked
boolean
기본값true
seller객체
sellerId
string
name
string
sellerIdentifier
string
고객사가 정의한 셀러 식별자입니다.
profileUrl
string
storeUrl
string
description
string
schemes
createdAt
string
updatedAt
string
message
string
status
string
successCount
integer
기본값0
warnCount
integer
기본값0
failCount
integer
기본값0
totalCount
integer
기본값0
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 상품을 셀러에게 이관다음 → 방송/리허설 시작

콘솔 API

방송/리허설 시작

POST/v2/{accessKey}/console/{campaignKeyOrId}/start

방송을 시작합니다. 리허설로 시작하려면 rehearsal=true를 붙이세요.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

쿼리 파라미터

rehearsal
boolean
방송을 리허설로 시작할지 여부입니다.
기본값false

응답

200 OKapplication/json

응답 본문 없음

4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 상품을 상위 계정으로 이관다음 → 콘솔에서 상품 재고 상태 변경

콘솔 API

콘솔에서 상품 재고 상태 변경

PUT/v2/{accessKey}/console/{campaignKeyOrId}/product/stockStatus

콘솔에서 상품 재고 상태 변경

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

쿼리 파라미터

stockStatus
stringenum
IN_STOCKLOW_IN_STOCKSOLD_OUT
목록에 포함된 모든 상품에 적용할 재고 상태입니다. 기본값은 SOLD_OUT입니다.
기본값SOLD_OUT

본문 파라미터

항목이 최소 1개 필요합니다. 각 항목은 productId 또는 customerProductId 중 하나를 지정해야 하며, 한 요청의 모든 항목에는 같은 종류의 식별자를 사용하세요.

application/json
객체 배열
productId
integer (int64)
자동으로 생성되는 고유 상품 ID
customerProductId
string
고객사의 상품 ID로, 고유해야 합니다(고객사가 정의).

응답

200 OKapplication/json
객체
results객체 배열
productId
string
message
status
string
successCount
integer
기본값0
warnCount
integer
기본값0
failCount
integer
기본값0
totalCount
integer
기본값0
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 방송/리허설 시작다음 → 콘솔에서 상품의 "Now" 표시 노출/숨김

콘솔 API

콘솔에서 상품의 "Now" 표시 노출/숨김

PUT/v2/{accessKey}/console/{campaignKeyOrId}/product/show

콘솔에서 상품의 "Now" 표시 노출/숨김

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

쿼리 파라미터

show
boolean
상품의 'Now' 표시 여부
기본값true

본문 파라미터

항목이 최소 1개 필요합니다. 각 항목은 productId 또는 customerProductId 중 하나를 지정해야 하며, 한 요청의 모든 항목에는 같은 종류의 식별자를 사용하세요.

application/json
객체 배열
productId
integer (int64)
자동으로 생성되는 고유 상품 ID
customerProductId
string
고객사의 상품 ID로, 고유해야 합니다(고객사가 정의).

응답

200 OKapplication/json
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 콘솔에서 상품 재고 상태 변경다음 → 방송/리허설 종료

콘솔 API

방송/리허설 종료

POST/v2/{accessKey}/console/{campaignKeyOrId}/end

방송을 종료합니다. 리허설을 종료하면 방송은 READY로 돌아갑니다.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

응답

200 OKapplication/json

응답 본문 없음

4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 콘솔에서 상품의 "Now" 표시 노출/숨김다음 → 콘솔에서 모든 상품의 "Now" 표시 노출/숨김

콘솔 API

콘솔에서 모든 상품의 "Now" 표시 노출/숨김

PUT/v2/{accessKey}/console/{campaignKeyOrId}/product/showAll

콘솔에서 모든 상품의 "Now" 표시 노출/숨김

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

쿼리 파라미터

show
boolean
상품의 'Now' 표시 여부
기본값true

응답

200 OKapplication/json

응답 본문 없음

4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 방송/리허설 종료다음 → 경매 시작

콘솔 API

경매 시작

PUT/v2/{accessKey}/console/{campaignKeyOrId}/product/auction/start

경매 시작

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

본문 파라미터

productId 또는 customerProductId 중 하나를 지정합니다(둘 중 하나 필수). 둘 다 보내면 customerProductId가 사용됩니다.

application/json
객체
productId
integer (int64)
자동으로 생성되는 고유 상품 ID
customerProductId
string
고객사의 상품 ID로, 고유해야 합니다(고객사가 정의).

응답

200 OKapplication/json

응답 본문 없음

4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 콘솔에서 모든 상품의 "Now" 표시 노출/숨김다음 → 경매 종료

콘솔 API

경매 종료

PUT/v2/{accessKey}/console/{campaignKeyOrId}/product/auction/end

경매 종료

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

본문 파라미터

productId 또는 customerProductId 중 하나를 지정합니다(둘 중 하나 필수). 둘 다 보내면 customerProductId가 사용됩니다.

application/json
객체
productId
integer (int64)
자동으로 생성되는 고유 상품 ID
customerProductId
string
고객사의 상품 ID로, 고유해야 합니다(고객사가 정의).

응답

200 OKapplication/json

응답 본문 없음

4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 경매 시작다음 → Seller 객체

셀러 API

Seller 객체

속성 이름

타입

설명

sellerId

String!

자동으로 생성되는 셀러의 식별자입니다. (숫자 형태의 문자열, 예: "1")

name

String!

셀러의 이름입니다.

profileUrl

String?

셀러의 프로필 이미지 URL입니다.

storeUrl

String?

셀러의 스토어 URL입니다.

description

String?

셀러에 대한 설명입니다.

schemes

Map<String, String>?

플레이어에서 각 버튼을 클릭했을 때 셀러 페이지로 이동하는 앱 스킴입니다.

sellerIdentifier

String?

셀러의 문자열 식별자입니다.

예시

json
{
    "sellerId": "1",
    "name": "Shoplive Product Store",
    "profileUrl": "https://image.shoplive.cloud/7910e586-19a4-4740-804b-5f9da02e6939.jpg",
    "storeUrl": "https://shoplive.cloud",
    "description": "Description of the seller",
    "schemes": {},
    "sellerIdentifier": "Identifier_of_the_seller"
}

이전 ← 경매 종료다음 → 셀러 검색

셀러 API

셀러 검색

GET/v2/{accessKey}/seller

셀러 검색

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey

쿼리 파라미터

keyword
string
셀러 이름을 검색할 키워드
sortAscending
boolean
생성 순(셀러 ID)으로 정렬합니다. 기본값은 false(최근 생성부터)입니다.
기본값false
page
integer (int32)
페이지네이션을 위한 파라미터입니다. 기본값은 1입니다.
기본값1
count
integer (int32)
한 페이지에 표시할 결과 개수를 지정합니다 (최대: 20)
기본값10

응답

200 OKapplication/json

results 의 각 항목은 Seller 객체입니다.

객체
results객체 배열
sellerId
string
name
string
sellerIdentifier
string
고객사가 정의한 셀러 식별자입니다.
profileUrl
string
storeUrl
string
description
string
schemes
객체
totalCount
integer
검색 조건에 맞는 셀러의 전체 개수입니다.
기본값0
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← Seller 객체다음 → 셀러 생성

셀러 API

셀러 생성

POST/v2/{accessKey}/seller

셀러 생성

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey

본문 파라미터

application/json
객체
name
string필수
셀러의 이름
profileUrl
string
셀러의 프로필 이미지 URL
storeUrl
string
셀러의 스토어 URL
description
string
셀러에 대한 설명

응답

200 OKapplication/json

응답 본문은 Seller 객체입니다.

객체
sellerId
string
name
string
sellerIdentifier
string
고객사가 정의한 셀러 식별자입니다.
profileUrl
string
storeUrl
string
description
string
schemes
객체
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 셀러 검색다음 → 셀러 수정

셀러 API

셀러 수정

PUT/v2/{accessKey}/seller/{sellerId}

셀러 수정

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
sellerId
integer (int64)필수
셀러 ID

본문 파라미터

application/json
객체
name
string
셀러의 이름
profileUrl
string
셀러의 프로필 이미지 URL
storeUrl
string
셀러의 스토어 URL
description
string
셀러에 대한 설명

응답

200 OKapplication/json

응답 본문은 Seller 객체입니다.

객체
sellerId
string
name
string
sellerIdentifier
string
고객사가 정의한 셀러 식별자입니다.
profileUrl
string
storeUrl
string
description
string
schemes
객체
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 셀러 생성다음 → 셀러 삭제

셀러 API

셀러 삭제

DELETE/v2/{accessKey}/seller/{sellerId}

셀러를 삭제합니다. 삭제한 셀러는 셀러 검색에 나오지 않으며 조회·수정할 수 없습니다. 응답 본문은 없습니다.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
sellerId
integer (int64)필수
셀러 ID

응답

200 OKapplication/json

응답 본문 없음

4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 셀러 수정다음 → 셀러 정보 조회

셀러 API

셀러 정보 조회

GET/v2/{accessKey}/seller/{sellerId}

셀러 정보 조회

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
sellerId
integer (int64)필수
셀러 ID

응답

200 OKapplication/json

응답 본문은 Seller 객체입니다.

객체
sellerId
string
name
string
sellerIdentifier
string
고객사가 정의한 셀러 식별자입니다.
profileUrl
string
storeUrl
string
description
string
schemes
객체
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 셀러 삭제다음 → Brand 객체

브랜드 API

Brand 객체

속성 이름

타입

설명

brandId

String!

자동으로 생성되는 브랜드의 고유 ID입니다. 읽기 전용입니다.

name

String!

브랜드 이름입니다. 최대 255자

identifier

String!

브랜드 식별자입니다. 

description

String?

브랜드에 대한 설명입니다.

imageUrl

String!

브랜드 이미지 URL입니다.

imageWidth

Integer!

브랜드 이미지의 너비(픽셀)입니다. 자동으로 생성됩니다. 읽기 전용입니다.

imageHeight

Integer!

브랜드 이미지의 높이(픽셀)입니다. 자동으로 생성됩니다. 읽기 전용입니다.

createdAt

String!

브랜드 생성 시각입니다. 읽기 전용입니다. (형식: YYYY-MM-DD'T'HH:mm:ss'Z')

updatedAt

String!

브랜드 수정 시각입니다. 읽기 전용입니다. (형식: YYYY-MM-DD'T'HH:mm:ss'Z')

예시

json
{
    "brandId": "1",
    "name": "Shoplive",
    "identifier": "shoplive_brand",
    "description": "Shoplive Brand.",
    "imageUrl": "https://image.shoplive.cloud/{UUID}.png",
    "imageWidth": 2110,
    "imageHeight": 317,
    "createdAt": "2026-02-01T08:34:33Z",
    "updatedAt": "2026-02-22T08:09:38Z"
}

이전 ← 셀러 정보 조회다음 → 브랜드 검색

브랜드 API

브랜드 검색

GET/v2/{accessKey}/brand

브랜드 검색

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey

쿼리 파라미터

keyword
string
브랜드의 이름, 식별자, 설명을 검색할 키워드
sortAscending
boolean
생성 순(브랜드 ID)으로 정렬합니다. 기본값은 false(최근 생성부터)입니다.
기본값false
page
integer (int32)
페이지네이션을 위한 파라미터입니다. 기본값은 1입니다.
기본값1
count
integer (int32)
한 페이지에 표시할 결과 개수를 지정합니다 (최대: 20)
기본값10

응답

200 OKapplication/json

results 의 각 항목은 Brand 객체입니다.

객체
results객체 배열
brandId
string
name
string
identifier
string
description
string
imageUrl
string
imageWidth
integer
기본값0
imageHeight
integer
기본값0
createdAt
string
생성 시각입니다(오프셋이 포함된 ISO 8601 날짜·시각)
updatedAt
string
마지막 수정 시각입니다(오프셋이 포함된 ISO 8601 날짜·시각)
totalCount
integer
검색 조건에 맞는 브랜드의 전체 개수입니다.
기본값0
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← Brand 객체다음 → 브랜드 생성

브랜드 API

브랜드 생성

POST/v2/{accessKey}/brand

브랜드 생성

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey

본문 파라미터

application/json
객체
name
string필수
브랜드의 이름
imageUrl
string필수
브랜드의 이미지 URL
identifier
string필수
브랜드의 식별자
description
string
브랜드에 대한 설명

응답

200 OKapplication/json

응답 본문은 Brand 객체입니다.

객체
brandId
string
name
string
identifier
string
description
string
imageUrl
string
imageWidth
integer
기본값0
imageHeight
integer
기본값0
createdAt
string
생성 시각입니다(오프셋이 포함된 ISO 8601 날짜·시각)
updatedAt
string
마지막 수정 시각입니다(오프셋이 포함된 ISO 8601 날짜·시각)
4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 브랜드 검색다음 → 브랜드 조회

브랜드 API

브랜드 조회

GET/v2/{accessKey}/brand/{brandId}

브랜드 조회

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
brandId
integer (int64)필수
조회할 브랜드의 ID

응답

200 OKapplication/json

응답 본문은 Brand 객체입니다.

객체
brandId
string
name
string
identifier
string
description
string
imageUrl
string
imageWidth
integer
기본값0
imageHeight
integer
기본값0
createdAt
string
생성 시각입니다(오프셋이 포함된 ISO 8601 날짜·시각)
updatedAt
string
마지막 수정 시각입니다(오프셋이 포함된 ISO 8601 날짜·시각)
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 브랜드 생성다음 → 브랜드 정보 수정

브랜드 API

브랜드 정보 수정

PUT/v2/{accessKey}/brand/{brandId}

브랜드 정보 수정

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
brandId
integer (int64)필수
수정할 브랜드의 ID

본문 파라미터

application/json
객체
name
string
브랜드의 이름
imageUrl
string
브랜드의 이미지 URL
identifier
string
브랜드의 식별자
description
string
브랜드에 대한 설명

응답

200 OKapplication/json

응답 본문은 Brand 객체입니다.

객체
brandId
string
name
string
identifier
string
description
string
imageUrl
string
imageWidth
integer
기본값0
imageHeight
integer
기본값0
createdAt
string
생성 시각입니다(오프셋이 포함된 ISO 8601 날짜·시각)
updatedAt
string
마지막 수정 시각입니다(오프셋이 포함된 ISO 8601 날짜·시각)
4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 브랜드 조회다음 → 브랜드 삭제

브랜드 API

브랜드 삭제

DELETE/v2/{accessKey}/brand/{brandId}

브랜드 삭제

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
brandId
integer (int64)필수
삭제할 브랜드의 ID

응답

200 OKapplication/json

응답 본문 없음

4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 브랜드 정보 수정다음 → Shortform 객체

숏폼 API

Shortform 객체

Shortform 객체는 개별 숏폼을 구성하는 영상과 다양한 메타데이터를 포함합니다. 이 객체를 사용해 여러 개의 썸네일로 구성된 미리보기 화면을 만들거나 개별 숏폼을 재생하기 위한 피드를 구성할 수 있습니다. 숏폼 검색·조회·생성·수정 API가 이 객체를 반환합니다.

숏폼은 API로 직접 생성·수정·삭제할 수도 있습니다(숏폼 생성, 숏폼 수정, 숏폼 삭제).

Shortform 객체

속성 이름

타입

설명

shortformId

String!

Shoplive 시스템이 각 숏폼에 부여하는 고유 ID입니다.

createdAt

String!

숏폼이 생성된 날짜와 시간이며 다음 형식을 따릅니다: (형식: YYYY-MM-DD'T'HH:mm:ss'Z', 예: 2026-12-25T08:00:00Z)

updatedAt

String!

숏폼이 수정된 날짜와 시간이며 다음 형식을 따릅니다: (형식: YYYY-MM-DD'T'HH:mm:ss'Z', 예: 2026-12-25T08:00:00Z)

status

String!

숏폼의 노출 상태 플래그 (OPEN | HIDDEN | SCHEDULED)

details

Details 객체

각 숏폼의 세부 정보는 다음 속성들을 포함합니다.

  • title

  • description

  • brand

  • tags

  • productCount

  • productBanner

  • products

activity

Activity 객체

각 숏폼과 연결된 활동 정보는 다음 속성들을 포함합니다.

  • viewCount

  • likeCount

  • commentCount

  • bookmarkCount

  • shareCount

video

Video 객체

숏폼과 연결된 영상에는 다음 속성이 있습니다.

  • duration

  • videoId

  • videoUrl

  • previewVideoUrl

  • screenshotUrl

Details 객체

각 숏폼의 세부 정보는 다음 속성들을 포함합니다.

속성 이름

타입

설명

title

String!

숏폼의 제목

description

String?

숏폼의 설명

brand

brand

숏폼에 설정된 브랜드 정보

tags

List<String>?

숏폼에 설정된 태그 정보

productCount

Integer!

숏폼에 설정된 상품 개수

productBanner

productBanner

숏폼에 설정된 상품 배너 정보

products

products

숏폼과 연결된 상품에 대한 정보입니다.

Activity 객체

각 숏폼의 activity에는 다음 속성이 있습니다. 숏폼 검색이 반환하는 항목에는 viewCount만 포함됩니다. likeCount, commentCount, bookmarkCount, shareCount를 얻으려면 숏폼 조회를 호출하세요.

속성 이름

타입

설명

viewCount

Integer!

숏폼을 시청한 사용자 수

likeCount

Integer!

숏폼에 좋아요를 누른 횟수 (검색 API에서는 제공되지 않음)

commentCount

Integer!

숏폼에 달린 댓글 수 (검색 API에서는 제공되지 않음)

bookmarkCount

Integer!

숏폼이 북마크된 횟수 (검색 API에서는 제공되지 않음)

shareCount

Integer!

숏폼이 공유된 횟수 (검색 API에서는 제공되지 않음)

Video 객체

숏폼과 연결된 영상에는 다음 속성이 있습니다.

속성 이름

타입

설명

duration

Integer!

숏폼 영상의 총 재생 길이(밀리초 단위)입니다.

videoId

String!

Shoplive가 관리하는 숏폼 영상의 고유 영상 ID(문자열)입니다.

videoUrl

String!

숏폼 영상의 재생 URL(m3u8)입니다. 이는 숏폼의 원본 영상이며 미리보기 화면 용도로 사용해서는 안 됩니다. 피드를 클라이언트에서 구현할 때 사용하는 것을 권장합니다. Adaptive Bitrate는 별도로 직접 구현해야 합니다.

previewVideoUrl

String!

숏폼 영상의 미리보기 영상 URL(m3u8)입니다. 이 URL은 미리보기 화면용으로 저해상도(320P) 영상을 재생하는 데 사용됩니다. X 초 길이의 영상을 반복 재생해야 하는 경우 별도로 직접 구현해야 합니다.

screenshotUrl

String!

숏폼 영상의 썸네일 이미지를 표시하기 위한 URL입니다.

Brand 객체

속성 이름

타입

설명

brandId

String!

브랜드 ID

identifier

String!

브랜드 식별을 위한 고유 문자열

name

String!

브랜드 이름

imageUrl

String!

브랜드 이미지 URL

ProductBanner 객체

상품 배너는 상품 목록이 표시되는 UI 상단에 노출할 수 있는 배너입니다. 주로 상품 기획전이나 프로모션 페이지에서 배너에 링크를 넣어 사용합니다.

속성 이름

타입

설명

title

String!

상품 배너 제목

imageUrl

String!

상품 배너 이미지 URL

scheme

String!

상품 배너를 클릭했을 때 이동할 URL 또는 스킴입니다.

Products 객체

검색 API 결과의 products에는 숏폼마다 상품이 하나만 담깁니다. 전체 상품은 숏폼 조회 API로 확인하세요.

속성 이름

타입

설명

productId

String!

Shoplive 시스템이 관리하는 고유 상품 ID입니다.

name

String!

상품 제목

brand

String!

상품의 브랜드 정보

url

String!

상품 상세 페이지 URL

sku

String!

상품 SKU 정보

imageUrl

String!

상품 이미지 URL

currency

String!

상품의 통화 정보

showPrice

Boolean!

상품 가격 표시 여부를 나타내는 플래그입니다 (true | false)

originalPrice

Double!

상품의 원가

discountPrice

Double!

상품의 할인가

discountRate

Double!

상품 가격의 할인율

stockStatus

String!

상품의 재고 상태 (IN_STOCK | LOW_IN_STOCK | SOLD_OUT)

예시

json
{
    "shortformId": "123456789012345678",
    "createdAt": "2026-12-25T08:00:00Z", 
    "updatedAt": "2026-12-26T08:00:00Z",
    "status": "OPEN",
    "details": {
        "title": "Shortform Title",
        "description": "This is a sample description",
        "brand": {
            "brandId": "123",
            "identifier": "shoplive", 
            "name": "Shoplive",
            "imageUrl": "https://image.shoplive.cloud/brand-image.png"
        },
        "tags": [ "food", "snack" ],
        "productCount": 3,
        "productBanner": {
            "title": "Product Banner Title",
            "imageUrl": "https://image.shoplive.cloud/product-banner-image.png",
            "scheme": "https://www.shoplive.cloud/product" 
        },
        "products": [ {
            "productId": "54321",
            "name": "Shoplive T-shirts",
            "brand": "Shoplive Brand",
            "url": "https://shoplivedemo.com/product/54321",
            "sku": "sku001",
            "imageUrl": "https://image.shoplive.cloud/product-image.png",
            "currency": "KRW",
            "showPrice": true,
            "originalPrice": 3400.0,
            "discountPrice": 2500.0,
            "discountRate": 26.0,
            "stockStatus": "IN_STOCK"
      } ]
    },
    "activity": {
        "viewCount": 2345,
        "likeCount": 123,
        "commentCount": 123,
        "bookmarkCount": 123,
        "shareCount": 321 
    },
    "video": {
        "duration": 3600,
        "videoId": "1234",
        "videoUrl": "https://resource.shoplive.cloud/video/shortsform/video.m3u8",
        "previewVideoUrl": "https://resource.shoplive.cloud/video/shortsform/previewVideo.m3u8",
        "screenshotUrl": "https://image.shoplive.cloud/shortform/screenshot.png"
    }
}

이전 ← 브랜드 삭제다음 → 숏폼 검색

숏폼 API

숏폼 검색

GET/v2/{accessKey}/shortform

숏폼 검색 API를 사용할 때는 다음 사항을 참고하세요:

  • 검색 결과의 details.products에는 숏폼마다 상품이 하나만 담깁니다. 전체 상품은 숏폼 조회로 확인하세요.
  • 숏폼의 미리보기 화면용으로 API를 사용할 때는 results 각 항목의 video.previewVideoUrl 필드를 사용하는 것을 권장합니다. video.videoUrl 필드는 원본 영상을 담고 있어 해상도가 더 높고 재생에 더 많은 데이터가 필요합니다.
  • 여러 태그로 검색할 때 검색 조건을 AND 또는 OR로 설정할 수 있습니다. (예: &tags=tag1,tag2,tag3&tagSearchOperator=AND|OR)
  • API로 결과를 조회할 때 sortOrder, createdAt, updatedAt 중 어떤 컬럼을 정렬 기준으로 사용할지 결정할 수 있습니다. 정렬 순서는 sortAscending 파라미터로 지정할 수 있습니다.
  • results 항목의 activity에는 viewCount만 포함됩니다. likeCount, commentCount, bookmarkCount, shareCount를 얻으려면 숏폼 조회를 호출하세요.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey

쿼리 파라미터

from
string
숏폼을 검색할 createdAt 범위의 시작 (형식: YYYY-MM-DD'T'HH:mm:ss'Z', 예: 2026-05-20T08:00:00Z)
to
string
숏폼을 검색할 createdAt 범위의 끝 (형식: YYYY-MM-DD'T'HH:mm:ss'Z', 예: 2026-05-20T08:00:00Z)
status
stringenum
OPENHIDDENSCHEDULED
숏폼의 노출 상태 플래그
title
string
숏폼의 제목
description
string
숏폼의 설명
brand
string
숏폼에 설정된 브랜드 정보
tags
string
검색할 태그를 쉼표로 구분하여 입력합니다. AND 또는 OR 쿼리를 지정하려면 tagSearchOperator를 사용하세요.
skus
string
검색할 SKU를 쉼표로 구분하여 입력합니다. 여러 개를 지정하면 OR 조건으로 검색합니다.
tagSearchOperator
stringenum
ANDOR
태그로 검색할 때 검색 연산자를 지정하세요.
기본값OR
shortformCollectionId
integer (int64)
컬렉션을 이용해 숏폼을 검색할 때 사용합니다.
page
integer (int32)
페이지네이션을 위한 파라미터입니다. 기본값은 1입니다.
기본값1
count
integer (int32)
한 페이지에 표시할 결과 개수를 지정합니다 (최대: 100)
기본값10
sortColumn
stringenum
sortOrdercreatedAtupdatedAt
정렬 기준 열: sortOrder(어드민에서 정한 표시 순서, 기본값), createdAt(생성 시각), updatedAt(수정 시각).
sortAscending
boolean
sortColumn의 열 기준으로 정렬합니다. 기본값은 true(오름차순)입니다.
기본값true

응답

200 OKapplication/json

results 의 각 항목은 Shortform 객체입니다.

객체
results객체 배열
shortformId
string
createdAt
string
updatedAt
string
status
string
details객체
title
string
description
string
brand객체
brandId
string
identifier
string
name
string
imageUrl
string
tags
array[string]
productCount
integer
productBanner객체
title
string
imageUrl
string
scheme
string
products객체 배열
productId
string
name
string
brand
string
url
string
sku
string
imageUrl
string
currency
string
showPrice
boolean
originalPrice
number
discountPrice
number
discountRate
number
stockStatus
string
activity객체
viewCount
integer
video객체
duration
integer
videoId
string
videoUrl
string
previewVideoUrl
string
screenshotUrl
string
totalCount
integer
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← Shortform 객체다음 → 숏폼 생성

숏폼 API

숏폼 생성

POST/v2/{accessKey}/shortform

숏폼 객체 생성

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey

본문 파라미터

application/json
객체
details객체필수
title
string필수
숏폼의 제목
description
string
숏폼의 설명
tags
array[string]
숏폼에 설정할 태그 정보
brand객체
brandId
integer (int64)
브랜드 ID
products객체 배열
productId
integer (int64)
상품 ID
scheduledOpenAt
string
시간대 오프셋을 포함한 ISO 8601 날짜·시각(YYYY-MM-DDTHH:mm:ss±HH:MM, UTC는 Z)입니다. 응답은 UTC입니다.
scheduledCloseAt
string
시간대 오프셋을 포함한 ISO 8601 날짜·시각(YYYY-MM-DDTHH:mm:ss±HH:MM, UTC는 Z)입니다. 응답은 UTC입니다.
seller객체
sellerId
integer (int64)
셀러 ID
video객체필수
숏폼에 사용할 영상입니다. videoId 또는 customerVideoId 중 하나를 지정합니다(둘 중 하나 필수). 둘 다 보내면 customerVideoId가 사용됩니다.
videoId
integer (int64)
영상 ID
customerVideoId
string
고객사 영상 ID
status
string
숏폼의 상태: OPEN|HIDDEN|SCHEDULED

응답

200 OKapplication/json

응답 본문은 Shortform 객체입니다.

객체
shortformId
string
createdAt
string
updatedAt
string
status
string
details객체
title
string
description
string
brand객체
brandId
string
identifier
string
name
string
imageUrl
string
tags
array[string]
productCount
integer
productBanner객체
title
string
imageUrl
string
scheme
string
products객체 배열
productId
string
name
string
brand
string
url
string
sku
string
imageUrl
string
currency
string
showPrice
boolean
originalPrice
number
discountPrice
number
discountRate
number
stockStatus
string
activity객체
viewCount
integer
likeCount
integer
commentCount
integer
bookmarkCount
integer
shareCount
integer
video객체
duration
integer
videoId
string
videoUrl
string
previewVideoUrl
string
screenshotUrl
string
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 숏폼 검색다음 → 숏폼 조회

숏폼 API

숏폼 조회

GET/v2/{accessKey}/shortform/{shortformId}

숏폼 객체 조회

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
shortformId
integer (int64)필수
shortformId

응답

200 OKapplication/json

응답 본문은 Shortform 객체입니다.

객체
shortformId
string
createdAt
string
updatedAt
string
status
string
details객체
title
string
description
string
brand객체
brandId
string
identifier
string
name
string
imageUrl
string
tags
array[string]
productCount
integer
productBanner객체
title
string
imageUrl
string
scheme
string
products객체 배열
productId
string
name
string
brand
string
url
string
sku
string
imageUrl
string
currency
string
showPrice
boolean
originalPrice
number
discountPrice
number
discountRate
number
stockStatus
string
activity객체
viewCount
integer
likeCount
integer
commentCount
integer
bookmarkCount
integer
shareCount
integer
video객체
duration
integer
videoId
string
videoUrl
string
previewVideoUrl
string
screenshotUrl
string
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 숏폼 생성다음 → 숏폼 수정

숏폼 API

숏폼 수정

PUT/v2/{accessKey}/shortform/{shortformId}

숏폼 객체 수정

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
shortformId
integer (int64)필수
shortformId

본문 파라미터

application/json
객체
details객체
title
string
숏폼의 제목
description
string
숏폼의 설명
tags
array[string]
숏폼에 설정할 태그 정보
brand객체
brandId
integer (int64)
브랜드 ID
scheduledOpenAt
string
시간대 오프셋을 포함한 ISO 8601 날짜·시각(YYYY-MM-DDTHH:mm:ss±HH:MM, UTC는 Z)입니다. 응답은 UTC입니다.
scheduledCloseAt
string
시간대 오프셋을 포함한 ISO 8601 날짜·시각(YYYY-MM-DDTHH:mm:ss±HH:MM, UTC는 Z)입니다. 응답은 UTC입니다.
video객체
videoId
integer (int64)
영상 ID
customerVideoId
string
고객사 영상 ID
status
string
숏폼의 상태: OPEN|HIDDEN|SCHEDULED

응답

200 OKapplication/json

응답 본문은 Shortform 객체입니다.

객체
shortformId
string
createdAt
string
updatedAt
string
status
string
details객체
title
string
description
string
brand객체
brandId
string
identifier
string
name
string
imageUrl
string
tags
array[string]
productCount
integer
productBanner객체
title
string
imageUrl
string
scheme
string
products객체 배열
productId
string
name
string
brand
string
url
string
sku
string
imageUrl
string
currency
string
showPrice
boolean
originalPrice
number
discountPrice
number
discountRate
number
stockStatus
string
activity객체
viewCount
integer
likeCount
integer
commentCount
integer
bookmarkCount
integer
shareCount
integer
video객체
duration
integer
videoId
string
videoUrl
string
previewVideoUrl
string
screenshotUrl
string
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 숏폼 조회다음 → 숏폼 삭제

숏폼 API

숏폼 삭제

DELETE/v2/{accessKey}/shortform/{shortformId}

숏폼 삭제

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
shortformId
integer (int64)필수
삭제할 shortformId

응답

200 OKapplication/json

응답 본문 없음

4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 숏폼 수정다음 → 숏폼에 상품 추가

숏폼 API

숏폼에 상품 추가

POST/v2/{accessKey}/shortform/{shortformId}/product

숏폼에 상품 추가

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
shortformId
integer (int64)필수
숏폼 ID

본문 파라미터

항목이 최소 1개 필요합니다. 각 항목은 productId 또는 customerProductId 중 하나를 지정해야 하며, 한 요청의 모든 항목에는 같은 종류의 식별자를 사용하세요.

application/json
객체 배열
productId
integer (int64)
자동으로 생성되는 고유 상품 ID
customerProductId
string
고객사의 상품 ID로, 고유해야 합니다(고객사가 정의).

응답

200 OKapplication/json
객체
results객체 배열
productId
string
message
status
string
customerProductId
string
successCount
integer
기본값0
warnCount
integer
기본값0
failCount
integer
기본값0
totalCount
integer
기본값0
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 숏폼 삭제다음 → 숏폼에서 상품 제거

숏폼 API

숏폼에서 상품 제거

DELETE/v2/{accessKey}/shortform/{shortformId}/product

숏폼에서 상품 제거

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
shortformId
integer (int64)필수
숏폼 ID

본문 파라미터

항목이 최소 1개 필요합니다. 각 항목은 productId 또는 customerProductId 중 하나를 지정해야 하며, 한 요청의 모든 항목에는 같은 종류의 식별자를 사용하세요.

application/json
객체 배열
productId
integer (int64)
자동으로 생성되는 고유 상품 ID
customerProductId
string
고객사의 상품 ID로, 고유해야 합니다(고객사가 정의).

응답

200 OKapplication/json
객체
results객체 배열
productId
string
message
null
status
string
successCount
integer
warnCount
integer
failCount
integer
totalCount
integer
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 숏폼에 상품 추가다음 → Video 객체

영상 API

Video 객체

속성 이름

타입

설명

videoId

String!

자동으로 생성되는 영상의 식별자입니다. (숫자 형태의 문자열)

customerVideoId

String?

고객사의 영상 ID로, 고유해야 합니다(고객사가 정의)

title

String!

영상의 제목입니다. 최대 255자.

description

String?

영상에 대한 설명입니다. 최대 65535자.

tags

List<String>?

영상의 태그입니다. 최대 10개

filename

String!

영상이 업로드될 때의 원본 파일명입니다.

width

Integer!

영상의 너비(픽셀)입니다.

height

Integer!

영상의 높이(픽셀)입니다.

filesize

String!

영상의 파일 크기(바이트)입니다. (숫자 형태의 문자열)

videoSourceUrl

String!

업로드된 영상 파일의 URL입니다.

thumbnailImageUrl

String?

영상의 썸네일 이미지 URL입니다. 지정하지 않으면 Shoplive가 영상 생성 시 썸네일 이미지 URL을 자동으로 생성합니다.

liveStreamUrl

String?

영상을 라이브처럼 재생할 수 있는 가변 화질 HLS(m3u8) URL입니다. 영상을 생성한 직후의 응답에는 포함되지 않습니다.

liveStreamUrls

Map<String, String>?

라이브처럼 재생할 수 있는 m3u8의 해상도별 URL입니다. 키는 해상도(예: 720p, 480p, 320p)이고 값은 재생 URL입니다.

vodStreamUrl

String?

자동 화질 HLS(m3u8) 리플레이 영상 URL입니다.

vodStreamUrls

Map<String, String>?

리플레이처럼 재생할 수 있는 m3u8의 해상도별 URL입니다. 키는 해상도(예: 720p, 480p, 320p)이고 값은 재생 URL입니다.

duration

Integer!

영상의 길이(밀리초)입니다.

uploadProgress

Integer!

영상의 업로드 진행률입니다. (0-100) 모든 트랜스코딩이 끝나면 100(%)이 됩니다.

createdAt

String!

영상이 생성된 일시입니다 (형식: YYYY-MM-DD'T'HH:mm:ss'Z')

updatedAt

String!

영상이 수정된 일시입니다 (형식: YYYY-MM-DD'T'HH:mm:ss'Z')

예시

json
{
    "videoId": "100",
    "customerVideoId": "SHOPLIVE_VIDEO_1",
    "title": "Shoplive Introduction Video",
    "description": "Introduction video description",
    "tags": ["interstitial","cocacola","cpg","test"],
    "filename": "shoplive_introduction_video.mp4",
    "width": 720,
    "height": 1280,
    "filesize": "38128539",
    "videoSourceUrl": "https://resource.shoplive.cloud/videos/vod/archive/{accessKey}/{streamKey}.mp4",
    "thumbnailImageUrl": "https://image.shoplive.cloud/{streamKey}.jpg",
    "liveStreamUrl": "https://api.shoplive.cloud/v1/videos/{accessKey}/rt_1240.m3u8",
    "liveStreamUrls": {
        "720p": "https://api.shoplive.cloud/v1/videos/{accessKey}/rt_1240/720p.m3u8",
        "480p": "https://api.shoplive.cloud/v1/videos/{accessKey}/rt_1240/480p.m3u8"
    },
    "vodStreamUrl": "https://resource.shoplive.cloud/videos/vod/hls/{streamKey}.m3u8",
    "vodStreamUrls": {
        "720p": "https://resource.shoplive.cloud/videos/vod/hls/{streamKey}_720p/index.m3u8",
        "480p": "https://resource.shoplive.cloud/videos/vod/hls/{streamKey}_480p/index.m3u8"
    },
    "duration": 202000,
    "uploadProgress": 100,
    "createdAt": "2026-12-09T09:17:04Z",
    "updatedAt": "2026-12-09T09:23:15Z"
}


이전 ← 숏폼에서 상품 제거다음 → 영상 검색

영상 API

영상 검색

GET/v2/{accessKey}/video

영상 검색

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey

쿼리 파라미터

keyword
string
영상의 제목과 설명을 검색할 키워드
sortAscending
boolean
생성 순(영상 ID)으로 정렬합니다. 기본값은 false(최근 생성부터)입니다.
기본값false
page
integer (int32)
페이지네이션을 위한 파라미터입니다. 기본값은 1입니다.
기본값1
count
integer (int32)
한 페이지에 표시할 결과 개수를 지정합니다 (최대: 100)
기본값20
customerVideoId
string
고객사의 영상 ID로, 고유해야 합니다(고객사가 정의)
tags
array[string]
검색할 태그를 쉼표로 구분하여 입력합니다. AND 또는 OR 쿼리를 지정하려면 tagSearchOperator를 사용하세요.
tagSearchOperator
stringenum
ANDOR
태그로 검색할 때 검색 연산자를 지정하세요 (AND / OR)
기본값OR

응답

200 OKapplication/json

results 의 각 항목은 Video 객체입니다.

객체
results객체 배열
videoId
string
customerVideoId
string
title
string
description
string
tags
array[string]
filename
string
width
integer
기본값0
height
integer
기본값0
filesize
string
videoSourceUrl
string
thumbnailImageUrl
string
liveStreamUrl
string
liveStreamUrls
객체
라이브처럼 재생할 수 있는 해상도별 m3u8 URL입니다. 키는 해상도(예: 720p, 480p, 320p)이고 값은 재생 URL입니다.
vodStreamUrl
string
vodStreamUrls
객체
리플레이처럼 재생할 수 있는 해상도별 m3u8 URL입니다. 키는 해상도(예: 720p, 480p, 320p)이고 값은 재생 URL입니다.
duration
integer
기본값0
uploadProgress
integer
기본값0
createdAt
string
updatedAt
string
totalCount
integer
기본값0
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← Video 객체다음 → 영상 생성

영상 API

영상 생성

POST/v2/{accessKey}/video


이 API는 Shoplive 미디어 스토리지에 영상 파일을 업로드하고 영상 리소스를 생성합니다.

Shoplive 서버가 API 호출을 수신하면, 영상 파일 업로드가 완료된 후 요청자에게 응답이 반환됩니다. (썸네일 이미지 URL과 라이브/리플레이 URL은 제외)
영상 업로드가 완료되면 Shoplive 서버는 업로드된 영상에 대한 트랜스코딩을 진행하며, 영상 조회/검색 API 응답의 uploadProgress를 통해 진행 상황을 확인할 수 있습니다.
트랜스코딩이 완료되면 알림을 받을 수 있도록 Webhook URL을 설정할 수도 있습니다. (Webhook 설정은 Shoplive 계정 담당자에게 문의하세요)

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey

본문 파라미터

application/json
객체
customerVideoId
string
고객사의 영상 ID로, 고유해야 합니다(고객사가 정의)
title
string
영상의 제목입니다. 최대 255자. 지정하지 않으면 기본값은 원본 파일명입니다.
description
string
영상에 대한 설명입니다. 최대 65535자.
video
string (binary)필수
multipart/form-data 타입의 영상 파일(mp4, mov)입니다.
image
string (binary)
multipart/form-data 타입의 썸네일 이미지(스크린샷) 파일입니다. 지정하지 않으면 Shoplive가 영상 생성 시 썸네일 이미지 URL을 자동으로 생성합니다.
tags
array[string]
영상의 태그입니다(최대 10개). 태그마다 필드를 한 번씩 보내세요(예: tags=tag1&tags=tag2). 쉼표로 구분한 단일 값도 허용됩니다.

응답

200 OKapplication/json

응답 본문은 Video 객체입니다.

객체
videoId
string
customerVideoId
string
title
string
description
string
tags
array[string]
filename
string
width
integer
기본값0
height
integer
기본값0
filesize
string
videoSourceUrl
string
thumbnailImageUrl
string
vodStreamUrl
vodStreamUrls
duration
integer
기본값0
uploadProgress
integer
기본값0
createdAt
string
updatedAt
string
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 영상 검색다음 → 영상 정보 조회

영상 API

영상 정보 조회

GET/v2/{accessKey}/video/{videoId}

영상 정보 조회

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
videoId
integer (int64)필수
영상 ID

응답

200 OKapplication/json

응답 본문은 Video 객체입니다.

객체
videoId
string
customerVideoId
string
title
string
description
string
tags
array[string]
filename
string
width
integer
기본값0
height
integer
기본값0
filesize
string
videoSourceUrl
string
thumbnailImageUrl
string
liveStreamUrl
string
liveStreamUrls
객체
라이브처럼 재생할 수 있는 해상도별 m3u8 URL입니다. 키는 해상도(예: 720p, 480p, 320p)이고 값은 재생 URL입니다.
vodStreamUrl
string
vodStreamUrls
객체
리플레이처럼 재생할 수 있는 해상도별 m3u8 URL입니다. 키는 해상도(예: 720p, 480p, 320p)이고 값은 재생 URL입니다.
duration
integer
기본값0
uploadProgress
integer
기본값0
createdAt
string
updatedAt
string
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 영상 생성다음 → customerVideoId로 영상 정보 조회

영상 API

customerVideoId로 영상 정보 조회

GET/v2/{accessKey}/video/customerVideoId/{customerVideoId}

customerVideoId로 영상 정보 조회

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
customerVideoId
string필수
고객사의 영상 ID로, 고유해야 합니다(고객사가 정의)

응답

200 OKapplication/json

응답 본문은 Video 객체입니다.

객체
videoId
string
customerVideoId
string
title
string
description
string
tags
array[string]
filename
string
width
integer
기본값0
height
integer
기본값0
filesize
string
videoSourceUrl
string
thumbnailImageUrl
string
liveStreamUrl
string
liveStreamUrls
객체
라이브처럼 재생할 수 있는 해상도별 m3u8 URL입니다. 키는 해상도(예: 720p, 480p, 320p)이고 값은 재생 URL입니다.
vodStreamUrl
string
vodStreamUrls
객체
리플레이처럼 재생할 수 있는 해상도별 m3u8 URL입니다. 키는 해상도(예: 720p, 480p, 320p)이고 값은 재생 URL입니다.
duration
integer
기본값0
uploadProgress
integer
기본값0
createdAt
string
updatedAt
string
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 영상 정보 조회다음 → videoId로 영상 수정

영상 API

videoId로 영상 수정

PUT/v2/{accessKey}/video/{videoId}

videoId를 사용하여 영상의 제목, 설명, 태그, customerVideoId를 변경할 수 있습니다.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
videoId
integer (int64)필수
메타데이터를 수정할 영상의 ID

본문 파라미터

application/json
객체
customerVideoId
string
수정 후 사용할 고객사 영상 ID
title
string
영상의 제목입니다. 최대 255자. 생략하면 현재 제목을 유지합니다.
description
string
영상에 대한 설명입니다. 최대 65535자.
tags
array[string]
배열 형태의 태그입니다.

응답

200 OKapplication/json

응답 본문은 Video 객체입니다.

객체
videoId
string
customerVideoId
string
title
string
description
string
tags
array[string]
filename
string
width
integer
기본값0
height
integer
기본값0
filesize
string
videoSourceUrl
string
thumbnailImageUrl
string
liveStreamUrl
string
liveStreamUrls
객체
라이브처럼 재생할 수 있는 해상도별 m3u8 URL입니다. 키는 해상도(예: 720p, 480p, 320p)이고 값은 재생 URL입니다.
vodStreamUrl
string
vodStreamUrls
객체
리플레이처럼 재생할 수 있는 해상도별 m3u8 URL입니다. 키는 해상도(예: 720p, 480p, 320p)이고 값은 재생 URL입니다.
duration
integer
기본값0
uploadProgress
integer
기본값0
createdAt
string
updatedAt
string
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← customerVideoId로 영상 정보 조회다음 → customerVideoId로 영상 수정

영상 API

customerVideoId로 영상 수정

PUT/v2/{accessKey}/video/customerVideoId/{customerVideoId}

customerVideoId를 사용하여 영상의 제목, 설명, 태그를 변경할 수 있습니다.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
customerVideoId
string필수
메타데이터를 수정할 대상 customerVideoId

본문 파라미터

application/json
객체
title
string
영상의 제목입니다. 최대 255자. 생략하면 현재 제목을 유지합니다.
description
string
영상에 대한 설명입니다. 최대 65535자.
tags
array[string]
배열 형태의 태그입니다.

응답

200 OKapplication/json

응답 본문은 Video 객체입니다.

객체
videoId
string
customerVideoId
string
title
string
description
string
tags
array[string]
filename
string
width
integer
기본값0
height
integer
기본값0
filesize
string
videoSourceUrl
string
thumbnailImageUrl
string
liveStreamUrl
string
liveStreamUrls
객체
라이브처럼 재생할 수 있는 해상도별 m3u8 URL입니다. 키는 해상도(예: 720p, 480p, 320p)이고 값은 재생 URL입니다.
vodStreamUrl
string
vodStreamUrls
객체
리플레이처럼 재생할 수 있는 해상도별 m3u8 URL입니다. 키는 해상도(예: 720p, 480p, 320p)이고 값은 재생 URL입니다.
duration
integer
기본값0
uploadProgress
integer
기본값0
createdAt
string
updatedAt
string
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← videoId로 영상 수정다음 → videoId로 영상 삭제

영상 API

videoId로 영상 삭제

DELETE/v2/{accessKey}/video/{videoId}

videoId로 영상 삭제

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
videoId
integer (int64)필수
삭제할 videoId

응답

200 OKapplication/json

응답 본문 없음

4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← customerVideoId로 영상 수정다음 → customerVideoId로 영상 삭제

영상 API

customerVideoId로 영상 삭제

DELETE/v2/{accessKey}/video/customerVideoId/{customerVideoId}

customerVideoId로 영상 삭제

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
customerVideoId
string필수
삭제할 customerVideoId

응답

200 OKapplication/json

응답 본문 없음

4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← videoId로 영상 삭제다음 → Stats 객체

통계 API

Stats 객체

속성 이름

타입

설명

campaignId

String!

자동으로 생성되는 방송의 식별자입니다. (숫자 형태의 문자열)

campaignKey

String!

자동으로 생성되는 키입니다(최대 32바이트, 영숫자). 이 키는 API 호출에서 방송을 지정하는 데 사용됩니다.

accessKey

String!

고객사마다 고유한 키입니다. 대부분의 Shoplive API는 이 accessKey를 필요로 합니다.

title

String!

방송의 제목

scheduledStartAt

String!

방송의 예정된 시작 시각 (형식: YYYY-MM-DD'T'HH:mm:ss'Z')

campaignStartedAt

String!

방송의 실제 시작 시각 (형식: YYYY-MM-DD'T'HH:mm:ss'Z')

campaignEndedAt

String!

방송의 실제 종료 시각 (형식: YYYY-MM-DD'T'HH:mm:ss'Z')

totalViewers

Integer!

전체 시청자 수

totalLoginViewers

Integer!

고객사의 웹 또는 애플리케이션에 로그인한 전체 시청자 수

peakConcurrentViewers

Integer!

최대 동시 시청자 수

newLoginViewers

Integer!

고객사의 방송을 처음 시청한 시청자 수

averageViewingTime

Integer!

평균 시청 시간(초, totalViewingTime / totalViewers)

totalViewingTime

Integer!

전체 시청 시간(초, 모든 시청자 합계)

likes

Integer!

전체 좋아요 수

likeViewers

Integer!

좋아요 버튼을 클릭한 시청자 수

averageLikes

Double!

likes/likeViewers

chats

Integer!

전체 채팅 수

chatViewers

Integer!

채팅 메시지를 보낸 시청자 수

averageChats

Double!

chats/chatViewers

productClicks

Integer!

상품 클릭 전체 횟수

productClickViewers

Integer!

상품을 클릭한 시청자 전체 수

averageProductClicks

Double!

productClicks/productClickViewers

bannerClicks

Integer!

상품 배너 클릭 전체 횟수 (상품 배너는 상품 목록 상단에 표시되는 배너입니다)

예시

json
{
    "campaignId": "1234",
    "campaignKey": "1234fef8e8e3",
    "accessKey": "a1b2c3d4",
    "title": "test campaign",
    "scheduledStartAt": "2026-07-08T06:30:00Z",
    "campaignStartedAt": "2026-07-08T06:21:06Z",
    "campaignEndedAt": "2026-07-11T12:38:59Z",
    "totalViewers": 123456,
    "totalLoginViewers": 100000,
    "peakConcurrentViewers": 12345,
    "newLoginViewers": 123455,
    "averageViewingTime": 15,
    "totalViewingTime": 1851840,
    "likes": 123456,
    "likeViewers": 123456,
    "averageLikes": 1.0,
    "chats": 123456,
    "chatViewers": 123456,
    "averageChats": 1.0,
    "productClicks": 123456,
    "productClickViewers": 123456,
    "averageProductClicks": 1.0,
    "bannerClicks": 123456
}

이전 ← customerVideoId로 영상 삭제다음 → 기간별 방송 통계 조회

통계 API

기간별 방송 통계 조회

GET/v2/{accessKey}/campaign/stats

특정 기간 내 방송의 통계를 조회합니다. 최대 기간은 1주일입니다.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey

쿼리 파라미터

from
string필수
FROM과 TO 사이에 종료된 방송의 통계를 조회합니다(방송 종료 시각 기준). (형식: YYYY-MM-DD'T'HH:mm:ss'Z', 예: 2026-09-07T00:00:00Z) from과 to는 모두 필수이며 범위는 7일을 초과할 수 없습니다.
to
string필수
FROM과 TO 사이에 종료된 방송의 통계를 조회합니다(방송 종료 시각 기준). (형식: YYYY-MM-DD'T'HH:mm:ss'Z', 예: 2026-09-07T00:00:00Z) from과 to는 모두 필수이며 범위는 7일을 초과할 수 없습니다.
campaignKeys
string
FROM과 TO 날짜 범위 사이의 통계를 조회할 방송 키 목록입니다. 여러 개는 쉼표로 구분합니다.

응답

200 OKapplication/json

results 의 각 항목은 Stats 객체입니다.

객체
results객체 배열
campaignId
string
campaignKey
string
accessKey
string
title
string
scheduledStartAt
string
campaignStartedAt
string
campaignEndedAt
string
totalViewers
integer
기본값0
totalLoginViewers
integer
기본값0
peakConcurrentViewers
integer
기본값0
newLoginViewers
integer
기본값0
averageViewingTime
integer
기본값0
totalViewingTime
integer
기본값0
likes
integer
기본값0
likeViewers
integer
기본값0
averageLikes
number
기본값0
chats
integer
기본값0
chatViewers
integer
기본값0
averageChats
number
기본값0
productClicks
integer
기본값0
productClickViewers
integer
기본값0
averageProductClicks
number
기본값0
bannerClicks
integer
기본값0
totalCount
integer
기본값0
4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← Stats 객체다음 → 방송 통계 단건 조회

통계 API

방송 통계 단건 조회

GET/v2/{accessKey}/campaign/{campaignKeyOrId}/stats

방송 통계 단건 조회

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey
campaignKeyOrId
string필수
방송 키 또는 방송 ID

응답

200 OKapplication/json

응답 본문은 Stats 객체입니다.

객체
campaignId
string
campaignKey
string
accessKey
string
title
string
scheduledStartAt
string
campaignStartedAt
string
campaignEndedAt
string
totalViewers
integer
기본값0
totalLoginViewers
integer
기본값0
peakConcurrentViewers
integer
기본값0
newLoginViewers
integer
기본값0
averageViewingTime
integer
기본값0
totalViewingTime
integer
기본값0
likes
integer
기본값0
likeViewers
integer
기본값0
averageLikes
number
기본값0
chats
integer
기본값0
chatViewers
integer
기본값0
averageChats
number
기본값0
productClicks
integer
기본값0
productClickViewers
integer
기본값0
averageProductClicks
number
기본값0
bannerClicks
integer
기본값0
4XX Client Errorapplication/json
객체
_s
integer
기본값0
_e
string

이전 ← 기간별 방송 통계 조회다음 → 로그 파일 다운로드

통계 API

로그 파일 다운로드

GET/v2/{accessKey}/log

요청한 형식의 파일로 로그를 다운로드합니다.

헤더 파라미터

Authorization
string필수
JWT 토큰

경로 파라미터

accessKey
string필수
고객사 accessKey

쿼리 파라미터

type
string필수enum
likeLogchatLogproductClickLogpopupClickLogviewerAccessLogviewerActivityLoghighlightedChatLogfilteredChatLog
다운로드할 로그 종류
format
string필수enum
jsoncsvtsv
다운로드할 로그 파일의 형식을 지정하세요.
from
string
from과 to를 YYYY-MM-DD'T'HH:mm:ss'Z' 형식으로 지정하여 로그 검색 범위를 제한합니다 (예: 2026-05-20T09:00:00Z). from과 to 파라미터는 반드시 함께 지정해야 하며 날짜 범위는 7일을 초과할 수 없습니다. ck를 지정하지 않으면 필수입니다.
to
string
from과 to를 YYYY-MM-DD'T'HH:mm:ss'Z' 형식으로 지정하여 로그 검색 범위를 제한합니다 (예: 2026-05-20T09:00:00Z). from과 to 파라미터는 반드시 함께 지정해야 하며 날짜 범위는 7일을 초과할 수 없습니다. ck를 지정하지 않으면 필수입니다.
ck
string
방송 키 또는 방송 ID입니다. 지정하면 from과 to는 선택 사항이며, 조회 범위는 방송 시작 시각부터 4일 후까지로 자동 설정됩니다(방송이 시작된 상태여야 합니다). 7일 제한은 적용되지 않습니다.
excludeAdmin
boolean
viewerAccessLog와 viewerActivityLog에서 관리자/운영자의 활동을 제외할지 여부입니다. 기본값은 true입니다. 채팅은 필터링하지 않습니다.
기본값true

응답

200 OKapplication/json

응답 본문 없음

4XX Client Errorapplication/json
객체
_s
integer
_e
string

이전 ← 방송 통계 단건 조회다음 → 헬스 체크 API

헬스 체크 API

헬스 체크 API

Shoplive는 서비스에 대한 헬스 체크를 제공합니다.


플레이어 초기화 코드

javascript
function initPlayer() {
  (function (s,h,o,p,l,i,v,e) {s["ShoplivePlayer"]=l;(s[l]=s[l]||function(){
  (s[l].q=s[l].q||[]).push(arguments);}),(i=h.createElement(o)),
  (v=h.getElementsByTagName(o)[0]);i.async=1;i.src=p;v.parentNode.insertBefore(i,v);
  })(window,document,"script","https://static.shoplive.cloud/live.js","mplayer");

  mplayer("init", "{{ access_key }}", "{{ campaign_key }}", "{{ user authorization }}", {{ options }});
  mplayer("run", "{{ id }}");
}


헬스 체크 함수 추가



jQuery

javascript
$.get("https://config.shoplive.cloud/ping.json", function(_data_, status) {
  if (status === "success") {
    initPlayer();
  }
}).fail(function() {
  // error handling
});



Vanilla.js

javascript
var request;
if (window.XMLHttpRequest) {
  request = new XMLHttpRequest();
} else if (window.ActiveXObject) {
  request = new ActiveXObject("Microsoft.XMLHTTP");
}

request.open("GET", "https://config.shoplive.cloud/ping.json", true);

request.onreadystatechange = function() {
  if (request.readyState === 4) {
    if (request.status === 200) {
      initPlayer();
    } else {
      // error handling
    }
  }
};

request.send(null);


이전 ← 로그 파일 다운로드다음 → 웹훅

웹훅

웹훅

웹훅은 방송 시작·종료처럼 방송에서 이벤트가 발생했을 때 Shoplive가 POST 요청으로 고객사 서버에 보내는 콜백입니다. API를 자주 폴링하지 않고도 이벤트가 발생하는 즉시 데이터를 받을 수 있습니다.

웹훅 설정은 셀프서비스가 아니라 Shoplive가 등록해 드리므로, 담당 매니저 또는 ask@shoplive.cloud로 수신 URL을 전달하세요. 사용할 수 있는 이벤트는 다음과 같습니다.

  • 방송 시작: 방송이 시작될 때 Campaign 객체를 전송합니다.

  • 방송 종료: 방송이 종료될 때 Campaign 객체를 전송합니다.

  • 경매 시작 · 종료 · 리셋: 방송에서 경매 상태가 바뀔 때 AuctionWebhook 객체를 전송합니다.

시작·종료 이벤트는 각각 다른 URL로, 경매 이벤트는 세 번째 URL로 전송됩니다. 받을 이벤트 종류는 설정할 수 있습니다. 리허설 방송은 등록 시 해당 옵션을 켠 경우에만 웹훅을 보냅니다.

전송

각 이벤트는 한 번만 전송됩니다. 약 1초 안에 200을 돌려주고 실제 처리는 비동기로 하세요. 방송 검색을 campaignStatus=ENDED 조건으로 주기적으로 함께 조회하고, 방송은 campaignKey 기준으로 멱등하게 처리하세요.

서명 검증

시작·종료 이벤트는 등록 시 웹훅 시크릿 키를 설정한 경우에만 서명됩니다. 요청에는 두 헤더가 함께 옵니다. X-SHOPLIVE-WEBHOOK-TIMESTAMP(Unix epoch 밀리초 문자열)와 X-SHOPLIVE-WEBHOOK-SIGNATURE(HMAC-SHA256의 소문자 hex)입니다. 서명 대상은 타임스탬프, ., 받은 그대로의 요청 본문 바이트(JSON 파싱 전)를 이어 붙인 값이고, 키는 시크릿 문자열의 UTF-8 바이트입니다. 서명은 상수 시간 비교로 확인하세요. 경매 이벤트에는 서명 헤더가 없습니다.

Node.js, Python, Java 코드 예제는 시작 가이드의 미션 11 · 웹훅으로 종료 감지를 참고하세요.

이전 ← 헬스 체크 API다음 → AuctionWebhook 객체

웹훅

AuctionWebhook 객체

속성 이름

타입

설명

action

string

START_AUCTION, END_AUCTION, RESET_AUCTION

campaignMeta

CampaignMeta

방송의 메타 정보입니다.

campaignProduct

CampaignProduct

CampaignProduct 객체입니다.

예시

json
{
  "action": "START_AUCTION",
  "campaignMeta": {
    "campaignId": 1234,
    "campaignKey": "{campaignKey}",
    "accessKey": "{accessKey}",
    "shoplivePlayerUrl": "https://www.shoplive.show/v1/player.html?ak={accessKey}&ck={campaignKey}",
    "title": "Shoplive Liveshow",
    "description": "",
    "campaignStatus": "ONAIR",
    "rerun": false,
    "userCount": 0,
    "likeCount": 0,
    "rehearsalPasscode": "9876",
    "serveReplay": true,
    "logoImageUrl": null,
    "brand": null,
    "preCampaignVideoUrl": null,
    "preCampaignImageUrl": "https://image.shoplive.cloud/bg_shoplive.png",
    "postCampaignImageUrl": "https://image.shoplive.cloud/bg_shoplive.png",
    "backgroundImageUrl": "https://image.shoplive.cloud/bg_shoplive.png",
    "ieUnsupportImageUrl": "https://image.shoplive.cloud/bg_shoplive.png",
    "tags": null,
    "scheduledStartAt": "2026-11-01T09:00:00Z",
    "scheduledEndAt": null,
    "campaignStartedAt": "2026-11-01T09:00:05Z",
    "campaignEndedAt": null,
    "createdAt": "2026-11-01T08:15:00Z",
    "updatedAt": "2026-11-01T09:00:05Z"
  },
  "campaignProduct": {
    "productId": "1234",
    "customerProductId": "SHOPLIVE_PRODUCT_1",
    "name": "Keyring",
    "brand": "SHOPLIVE",
    "description": null,
    "url": "https://www.shoplive.cloud/en",
    "sku": "SKU001",
    "imageUrl": "https://image.shoplive.cloud/e05d1464-1942-4e4e-bb0b-c4310167d465.jpeg",
    "currency": "USD",
    "showPrice": true,
    "originalPrice": 20.0,
    "discountPrice": 20.0,
    "discountRate": 0,
    "enableAuction": true,
    "bidStartingPrice": 100,
    "bidDuration": 1000,
    "bidIncrementalAmount": 1,
    "extendBidDuration": false,
    "ctaButtonTitle": null,
    "seller": null,
    "extendedProperties": null,
    "createdAt": "2026-05-20T08:01:05Z",
    "updatedAt": "2026-11-01T09:05:00Z",
    "campaignId": 1234,
    "showingNow": true,
    "sortOrder": 1,
    "stockStatus": "IN_STOCK",
    "auction": {
      "productId": 1234,
      "auctionStatus": "ONGOING",
      "startingPrice": 100,
      "bidRound": 1,
      "currentPrice": 100,
      "winningPrice": null,
      "recommendedPrices": [
        100
      ],
      "winner": null,
      "leader": null,
      "winnerCheckoutScheme": null,
      "startedAt": 1793523900000,
      "endingAt": 1793524900000,
      "endedAt": null
    }
  }
}

이전 ← 웹훅