# S2S API

매체 서버에 Server-to-Server API 방식으로 광고 데이터를 제공하는 기능에 대하여 설명합니다. 이 API 는 사전에 등록된 매체 서버에서만 호출이 가능합니다. 클라이언트에서 광고 데이터를 조회하는 기능이 필요하다면 SDK 가 제공하는 [Data API](https://snapplay.gitbook.io/docs/data-api/sdk-api) 기능을 사용해주세요.

## 1. 목록 조회

{% tabs %}
{% tab title="Base URL" %}

```url
https://ads.snapplay.io/api/main/offer/v1
```

{% endtab %}
{% endtabs %}

GET 방식으로 호출하며 필요한 파라메터들은 아래와 같습니다.

<table><thead><tr><th width="231.75390625">파라메터</th><th width="107.96484375" align="center">필수 여부</th><th>설명</th><th data-hidden>필수여부</th></tr></thead><tbody><tr><td>app_id</td><td align="center">필수</td><td>매체의 APP_ID 값 입니다.</td><td>필수</td></tr><tr><td>plcmt_nm</td><td align="center"></td><td>플레이스먼트의 명칭입니다.</td><td>필수</td></tr></tbody></table>

조회 결과는 JSON 구조의 문자열입니다. 아래의 Sample data 를  참고하세요.

```json
{
    "ret_cd": 0,
    "ret_list": [
        {
            "adv_id": 18467,
            "adv_title": "오늘의 쿠팡 특가는?",
            "adv_desc": "쿠팡 구매하기",
            "os_type": "W",
            "adv_type": 493,
            "actn_type": 1001,
            "type_nm": "클릭",
            "cta_label":"참여하기",
            "icon_img_url": "https://d1djcwwrtg2512.cloudfront.net/icon/44490",
            "feed_img_url": "https://d1djcwwrtg2512.cloudfront.net/feed/295803",
            "trgt_country": ["KR","JP","US"],
            "adv_types": [10007,10011,90001,493,1001],
            "curr_cd": "KRW",
            "pnt_unit": "코인",
            "adv_sdt": 1748505600000,
            "adv_edt": 32503647600000,
            "action_list": [
                {
                    "actn_id": 18469,
                    "actn_title": "클릭하기",
                    "actn_desc": "쿠팡 생필품 BEST&NEW 보러가기",
                    "actn_type": 1001,
                    "user_pnt" : 2,
                    "org_user_pnt" : 2,
                    "pay_amt": 3,
                    "per_amt": 0,
                    "pay_intvl": 2,
                    "day_max_pay": 5
                }
            ],
            "adid_yn": "Y",
            "detail_yn": "N",
        }
    ]
}
```

### 광고 목록 필드 (ret\_list)

<table><thead><tr><th width="146.34765625">필드</th><th width="126.875">타입</th><th>설명</th></tr></thead><tbody><tr><td>adv_id</td><td>long</td><td>광고 식별을 위한 고유 ID</td></tr><tr><td>adv_title</td><td>String</td><td>광고 타이틀</td></tr><tr><td>adv_desc</td><td>String</td><td>광고 설명 문구</td></tr><tr><td>os_type</td><td>String</td><td>광고 OS ("A", "I", "W")</td></tr><tr><td>adv_type</td><td>int</td><td>광고 타입 (별도 표 참고)</td></tr><tr><td>actn_type</td><td>int</td><td>첫번째 액션의 액션 유형 (별도 표 참고)</td></tr><tr><td>type_nm</td><td>String</td><td>액션 유형의 명칭 (목록 표시에 활용한다.)</td></tr><tr><td>cta_label</td><td>String</td><td>광고 페이지 이동을 위한 버튼용 라벨 (상세 화면에서 활용한다.)</td></tr><tr><td>icon_img_url</td><td>String</td><td>아이콘(정사각형 이미지) URL</td></tr><tr><td>feed_img_url</td><td>String</td><td>피드 이미지(가로) URL</td></tr><tr><td>app_pkg</td><td>String</td><td>앱 패키지(Android), 번들 또는 스키마(iOS), 사이트 주소(Web)</td></tr><tr><td>trgt_country</td><td>String Array</td><td>국가 타게팅</td></tr><tr><td>adv_types</td><td>int Array</td><td>광고 타입, 액션 타입 및 별도 설정된 tag 값들을 배열로 제공한다.</td></tr><tr><td>curr_cd</td><td>String</td><td>pay_amt의 통화 코드("KRW", "USD" 등)</td></tr><tr><td>pnt_unit</td><td>String</td><td>사용자 재화 명칭 (사이트에서 설정)</td></tr><tr><td>adv_sdt</td><td>long</td><td>광고 시작 일시 (1970.01.01 부터의 milli-seconds 값)</td></tr><tr><td>adv_edt</td><td>long</td><td>광고 종료 일시</td></tr><tr><td>adid_yn</td><td>String</td><td>ADID 필수 광고</td></tr><tr><td>detail_yn</td><td>String</td><td>상세 페이지 필수 표시 광고 (상세 페이지 구현이 필요)</td></tr><tr><td>cps_sale_price</td><td>Numeric</td><td>CPS 상품인 경우 상품 판매가</td></tr><tr><td>cps_org_price</td><td>Numeric</td><td>CPS 상품인 경우 상품 할인 전 가격</td></tr><tr><td>action_list</td><td>Object Array</td><td>액션 목록</td></tr></tbody></table>

### 액션 목록 필드 (action\_list)&#x20;

<table><thead><tr><th width="149.11328125">필드</th><th width="128.26953125">타입</th><th>설명</th></tr></thead><tbody><tr><td>actn_id</td><td>long</td><td>액션 고유 ID</td></tr><tr><td>actn_title</td><td>String</td><td>액션 타이틀</td></tr><tr><td>actn_desc</td><td>String</td><td>액션 설명 문구</td></tr><tr><td>actn_type</td><td>int</td><td>액션 유형 코드 (별도 표 참고)</td></tr><tr><td>user_pnt</td><td>long</td><td>사용자 지급 재화</td></tr><tr><td>org_user_pnt</td><td>long</td><td>2배 이벤트 등을 진행할 경우에는 원래 지급 재화</td></tr><tr><td>pay_amt</td><td>Numeric</td><td>지급 비용 (통화 단위는 curr_cd 값으로 전달함)</td></tr><tr><td>per_amt</td><td>int</td><td>CPS 광고인 경우 이 구매 금액당 adv_amt 정산됨</td></tr><tr><td>pay_intvl</td><td>int</td><td>한번 참여 후 이 시간이 지나야 다시 참여 가능(시간)</td></tr><tr><td>day_max_pay</td><td>int</td><td>0 이면 1번만 참여가능, 1 이상이면 하루에 그 횟수만큼 참여가능</td></tr></tbody></table>

## 2. 광고 참여

작성 중입니다.

{% tabs %}
{% tab title="Base URL" %}

```url
https://ads.snapplay.io/api/main/offer/join
```

{% endtab %}
{% endtabs %}

GET 방식으로 호출한다.

<table><thead><tr><th width="162.59375">파라메터</th><th width="132.9140625">필수 여부</th><th>설명</th></tr></thead><tbody><tr><td>app_id</td><td>필수</td><td>매체의 APP_ID 값 입니다.</td></tr><tr><td>plcmt_nm</td><td></td><td>플레이스먼트의 명칭입니다.</td></tr><tr><td>adv_id</td><td>필수</td><td>참여할 광고의 adv_id 값입니다.</td></tr><tr><td>pub_user_nm</td><td></td><td>매체의 사용자 식별값입니다.</td></tr><tr><td>adid</td><td>(필수)</td><td>기기의 광고 ID 입니다. adid_yn = 'Y' 인 광고는 필수입니다.</td></tr><tr><td>asid</td><td></td><td>Android App Set ID 또는 iOS IDFV</td></tr><tr><td>ph_os</td><td></td><td>기기의 OS (A, I, W)</td></tr><tr><td>ip_addr</td><td>(필수)</td><td>매체서버에서 호출하는 경우 별도로 전달 </td></tr></tbody></table>

### Response

Sample Data

```json
{
    "ret_cd": 0,
    "adv_url": "https://go.adserver.com?cid=2598001&pid=2303&click_id=e6...."
}
```

결과 필드

<table><thead><tr><th width="124.59765625">필드</th><th width="136.76171875">타입</th><th>설명</th></tr></thead><tbody><tr><td>ret_cd</td><td>int</td><td>처리 결과 코드이다. <a href="error-code-and-types">별도 표</a>를 참고한다.</td></tr><tr><td>adv_url</td><td>String</td><td>광고 랜딩 페이지 이다.</td></tr><tr><td>sec_left</td><td>long</td><td>결과 코드가 10020(참여 가능 시간이 지나지 않음) 인 경우 남은 시간을 전달해준다.</td></tr></tbody></table>