> For the complete documentation index, see [llms.txt](https://adpopcornssp.gitbook.io/ssp-sdk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://adpopcornssp.gitbook.io/ssp-sdk/undefined-2/extra-guide/coupang/reco-v2-api.md).

# Reco V2 API 연동

## URL

```url
https://ssp-ext-proxy.adpopcorn.com/coupang/reco/v2
```

## Method

```
POST
```

## Headers

```http
Content-Type: application/json
```

{% hint style="danger" %}

## 크롤링 등과 같은 비정상적인 요청을 방지를 위해 User-Agent 에 python-requests 와 같은 값은 사용할 수 없습니다

{% endhint %}

## Request parameter

<table><thead><tr><th width="188">Body parameter</th><th width="142">Type</th><th>설명</th></tr></thead><tbody><tr><td>site</td><td><a href="#site">Site 객체</a></td><td>웹 사이트 요청에 필요합니다<br><mark style="color:$danger;"><code>site</code> 및 <code>app</code>은 둘 중 하나만 제공해야 합니다</mark></td></tr><tr><td>app</td><td><a href="#app">App 객체</a></td><td>앱  요청에 필요합니다<br><mark style="color:$danger;"><code>site</code> 및 <code>app</code>은 둘 중 하나만 제공해야 합니다</mark></td></tr><tr><td>device</td><td><a href="#device">Device 객체</a></td><td>필수 항목입니다</td></tr><tr><td>imp</td><td><a href="#imp">Imp 객체</a></td><td>필수 항목입니다</td></tr><tr><td>user</td><td><a href="#user">User 객체</a></td><td>선택 사항입니다</td></tr><tr><td>affiliate</td><td><a href="#affiliate">Affiliate 객체</a></td><td>필수 항목입니다</td></tr></tbody></table>

### Site 객체&#x20;

<table><thead><tr><th width="144.66668701171875">Parameter</th><th width="80.8890380859375">Type</th><th width="84.778076171875">Scope</th><th>Description</th></tr></thead><tbody><tr><td>domain</td><td>string</td><td>추천</td><td>쿠팡 광고가 노출될 최상위 웹 도메인<br>예) coupang.com</td></tr><tr><td>page</td><td>string</td><td>추천</td><td>실제 광고 지면 URL (가능할 경우)<br>예) https://page.coupang.com/p/bep</td></tr><tr><td>id</td><td>string</td><td></td><td>사이트 고유 식별자</td></tr></tbody></table>

### App 객체&#x20;

<table><thead><tr><th width="145.77777099609375">Parameter</th><th width="80.8890380859375">Type</th><th width="84.7781982421875">Scope</th><th>Description</th></tr></thead><tbody><tr><td>bundleId</td><td>string</td><td>추천</td><td>안드로이드 번들/패키지명 또는 iOS 번들 식별자 (앱 ID)</td></tr><tr><td>domain</td><td>string</td><td>추천</td><td>앱 도메인</td></tr><tr><td>id</td><td>string</td><td></td><td>앱의 고유 식별자</td></tr></tbody></table>

### Device 객체&#x20;

<table><thead><tr><th width="145.77783203125">Parameter</th><th width="88.66680908203125">Type</th><th width="91.4447021484375">Scope</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>필수</td><td>Gogle Advertising ID on Android 또는IDFA on iOS</td></tr><tr><td>lmt</td><td>number</td><td>필수</td><td>GAID/IDFA 동의 여부 <br>안드로이드: 0 - 비활성화, 1: 관심 기반 광고 수신 거부 활성화<br>iOS: 0 - 비활성화, 1: 광고 트래킹 제한 스위치 활성화</td></tr><tr><td>ip</td><td>string</td><td>추천</td><td>사용자의 IP 주소 (IPv4)</td></tr><tr><td>ua</td><td>string</td><td>추천</td><td>수정하지 않은 사용자 에이전트 문자열</td></tr></tbody></table>

### Imp 객체&#x20;

<table><thead><tr><th width="145.77777099609375">Parameter</th><th width="88.6666259765625">Type</th><th width="92.333251953125">Scope</th><th>Description</th></tr></thead><tbody><tr><td>imageSize</td><td>string</td><td>필수</td><td>상품 이미지 사이즈 (너비x높이)<br>필요한 화면 비율에 따라 크기 조정 가능<br>예) 300x250</td></tr><tr><td>placementId</td><td>string</td><td>추천</td><td>인벤토리 영역을 위한 ID<br>고유한 광고 영역을 참조해야 합니다</td></tr><tr><td>adType</td><td>number</td><td>선택사항</td><td><p>광고유형<br></p><p>1: text-only<br>2: banner (general display ad)<br>3: native (display native ad)<br>4: interstitial (full-page ad)<br>5: non-rewarded video<br>6: rewarded video</p></td></tr><tr><td>pos</td><td>number</td><td>선택사항</td><td>광고 영역 위치<br><br>1: 화면 상단<br>3: 화면 하단<br>4: 헤더<br>5: 푸터<br>6: 사이드바<br>7: 전체 화면</td></tr></tbody></table>

### User 객체&#x20;

<table><thead><tr><th width="145.77783203125">Parameter</th><th width="88.66680908203125">Type</th><th width="88.1114501953125">Scope</th><th>Description</th></tr></thead><tbody><tr><td>puid</td><td>string</td><td>필수</td><td>퍼블리셔가 정의한 최종 사용자 ID<br>제3자 쿠기 또는 ID에 의존하지 않고 사용자를 인식할 수 있는 대체 ID 및 개인정보 보호 우선 방식</td></tr></tbody></table>

### Affiliate 객체&#x20;

<table><thead><tr><th width="145.7777099609375">Parameter</th><th width="89.7777099609375">Type</th><th width="90.333251953125">Scope</th><th>Description</th></tr></thead><tbody><tr><td>subId</td><td>string</td><td>필수 <sup><sub><mark style="color:$danger;"><strong>1</strong></mark></sub></sup></td><td>채널 ID (정산 단위)</td></tr><tr><td>subIds</td><td>string[]</td><td>필수 <sup><sub><mark style="color:$danger;"><strong>1</strong></mark></sub></sup></td><td>채널 ID 리스트(정산 단위) - <mark style="color:$danger;"><strong>2개 이상일 경우 사용</strong></mark></td></tr><tr><td>subParam</td><td>string</td><td>선택사항</td><td>사용자 추적 및 리포트에 사용할 커스텀 파라미터</td></tr></tbody></table>

{% hint style="info" %} <mark style="color:$danger;">**`subId`**</mark> 또는 <mark style="color:$danger;">**`subIds`**</mark> 중 하나를 반드시 전달해야  합니다.

<mark style="color:$danger;">**`subIds`**</mark> 에 전달된 값은 <mark style="color:$danger;">**`subId`**</mark> 보다 우선하여 균등 분배 되어 사용됩니다.
{% endhint %}

{% code title="JSON" lineNumbers="true" %}

```json5
{
    "site": {
        "domain": "test.com",
        "page": "http://www.test.com/abcd",
        "id": "id1"
    },
    "app": {
        "bundleId": "com.coupang.mobile",
        "id": "id2"
    },
    "imp": {
        "imageSize": "300x250",
        "adType": 1,
        "placementId": "pid1",
        "pos": 1
    },
    "device": {
        "id": "00000000-0000-0000-0000-000000000000",
        "lmt": 1,
        "ip": "0.0.0.0",
        "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36"
    },
    "user": {
        "puid": "1111111"
    },
    "affiliate": {
        "subId": "CPSap22222", // 또는 2개 이상일 경우 "subIds": ["CPSap22222", "CPSap33333"]
        "subParam": "AF0001"
    }
}
```

{% endcode %}

## Response

<table><thead><tr><th width="188">Body parameter</th><th width="142">Type</th><th>설명</th></tr></thead><tbody><tr><td>rCode</td><td>string</td><td><p>상태코드<br><br>0: 정상</p><p>204: 추천 상품 없음</p><p>400: 파라미터 오류</p><p>403: 인증 오류</p><p>404: 채널 ID 없음</p><p>429: 요청량 초과</p><p>500: 서버 오류</p></td></tr><tr><td>rMessage</td><td>string</td><td>상태메시지</td></tr><tr><td>data</td><td>object</td><td></td></tr><tr><td>   result</td><td><a href="#product">Product</a>[]</td><td>상품 리스트</td></tr></tbody></table>

### Product 객체

<table><thead><tr><th width="159">ID</th><th width="174">Type</th><th>설명</th></tr></thead><tbody><tr><td>productId</td><td>number</td><td>상품 ID</td></tr><tr><td>productName</td><td>string</td><td>상품명</td></tr><tr><td>productPrice</td><td>number</td><td>가격 (KRW)</td></tr><tr><td>productImage</td><td>string</td><td>상품 이미지 URL</td></tr><tr><td>productUrl</td><td>string</td><td>상품 페이지의 트래킹 URL</td></tr><tr><td>categoryName</td><td>string</td><td>상품 카테고리 (최대 길이 20자)</td></tr><tr><td>isRocket</td><td>boolean</td><td>로켓 배송 여부</td></tr><tr><td>impressionUrl</td><td>string</td><td>상품의 노출 트래킹 URL로 상품이 보여질때 호출되어야 합니다</td></tr></tbody></table>

### 응답예제

{% tabs %}
{% tab title="200" %}
{% code title="" lineNumbers="true" expandable="true" %}

```json
{
    "rCode": "0",
    "rMessage": "게시글 작성 시, \"파트너스 활동을 통해 일정액의 수수료를 제공받을 수 있음\"을 기재하셔야 합니다",
    "data": {
        "result": [
            {
                "productId": 1232968322,
                "productName": "곰곰 신선한 1A 우유",
                "productPrice": 7380,
                "productImage": "https://ads-partners.coupang.com/openapi/image/xTspdrrR1ec92d3Lxf3YsKvxsiY5KtI0FGHrX1HheZ_g4cIGAJ15p37XgwjLdc_Ctgn6GXDh0ty9d4PHb20sQYOgpSOSZF0we46ksbToHrify0EgHGFS718NP2V7doOBEUkgwewvqVzTLmfwHL4uZw_op6K1ZINtAeFVaGXg2VwGln5ZvZz7UtrPdqwq-JlCXyPO-y-1bNvh-d2zaqxrcI7VcwpNzc4I7jBdkB7KZ82VtwTAzqkgeV2tUqTfSonQ6aVbNFKgQ2TmEmiukR9REgbiCpRJv05kpQaQi6gC4uJ2rOZX0WDUWpe574u8e5N4QOu7STF1Pl3mIkOXI69NnTwzzQehA_85lJlkAP3k-lXbBL2Rtg==",
                "productUrl": "https://link.coupang.com/re2/AFFSDP?lptag=AF1036751&subid=CPSapapp1&pageKey=1232968322&itemId=19223669920&vendorItemId=86340356298&traceid=V0-193-1fc5b0b4f277ae56&requestId=20251031100958614095278693&token=57579G&landing_exp=APP_LANDING_B",
                "categoryName": "로켓프레시",
                "isRocket": true,
                "impressionUrl": "https://ads-partners.coupang.com/openapi/impression/O_EBAOeSNR8fuB7ZO_IR8lFhelrWD7_fmaUAYxbhoZ8w2MLyoVMMj02n5MKse6RPdZD5Qo5IQ_W1fgldBqJz2NONpdBv1PXPrabaLlZgsO7-VMy13uFx4mZ03P8k24pe1EtqHfCBxvYUmZ0N6vTqbRFKb_o5X2D-YSYWfZvHE2mdWv7bi28ZUHlbq4Au4Qi3CXCwjc6QFPzd489EDvTwrFpOJ9xEWrVZezMAR7qqPRFRTzg35UMGFNh9y3lGdMXcQBX_aO5wO_7srlCp04bgxrLGPyPE4XQUwqm4qG3NC7_IIjjuUGPR-DR9lHkb4ZkNSSViXP5IduEI2S51EqKXld7Y5lGDDUuP-XMTc2tH5Wu8lkfMyg=="
            },
            {
                "productId": 7987740493,
                "productName": "5세대 저소음 BLDC 모터 날개없는 선풍기 타워형",
                "productPrice": 139000,
                "productImage": "https://ads-partners.coupang.com/openapi/image/tuTEd3-InAdCATpJtmPVRmSVoajNQJKNDRU8L_KIJHp6Pf40qhVnoQ9XMLSyn8WMbNe1ymlYZkVCkJlKrwO_gNFpdeYunjgCb0wCemfvk9gkXI49QWEOggapgImxNPPVMD4AXCgdqH3UBCbdFkkkxPEIMHy8PhAsLfRyDtYCOQb4ZbrUKOH7w-2_Fvs6xwFmj0IAYlE-vUQy2HUQsrm02sBHBElWDuDDlFIdkqGBSWTRILosUSjQOCCHifQddid43zn4NxAS54rdlIo5uYc9KZSvRwkgmWGjopoCyNK6Zn0p0vpWVGTzeOBVdrlHx1fFtNbZOffNjxQJMVWieoAT1ac6hJmthJkBmLm0nE6DqogEHCVQs9kSlaR3g6w=",
                "productUrl": "https://link.coupang.com/re2/AFFSDP?lptag=AF1036751&subid=CPSapapp1&pageKey=7987740493&itemId=25151521546&vendorItemId=92142036228&traceid=V0-193-f02a803120acb871&requestId=20251031100958614095278693&token=57579G&landing_exp=APP_LANDING_B",
                "categoryName": "가전디지털",
                "isRocket": true,
                "impressionUrl": "https://ads-partners.coupang.com/openapi/impression/Ul0zpjg_H_Cpv_7dUpDbkzjS9gTdKoBMvgR5_IELF1WNkIFxVChUg5mNX_juiWZnsm6hElQmrqXLY74zLNEyLV2l36Lp5Mh4TYqca9YnnZhasLXnw7cbRFraC1tG4QBKHlr0jTqkRKHUeV-ZxphoD8ymdveKMrfQqfghD5c5POtMTtQjd1fIZFEaw3fP_Giq3N6f6M1SK77mOTNAtbmC9IYSWyw58Ezv6UpWd3AO9fii1PE-S4PO5hfqA6HlQhbaacG-mH5TQf5yBA0n0BTjd2SAkrB5n1Wx-CqsVOB--ExY9i4Affe7HhAAbUq4zeHVUIhq1Q7aAt46_XUQ0IyMalZVISdvubZBMgxCsHWQJu66xCH87YrOsoiXzRY="
            }
        ]
    }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}

## 노출 측정 가이드 라인

노출 트래킹은 고객 측 그리고 추천이 표시되는 디바이스에서 구현되어야 합니다. 노출 URL 트래커는 상품 추천이 최종 사용자에게 노출되고 실제 사람이 상품을 본 경우에만 실행되어야 합니다.
{% endhint %}