# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://adpopcornssp.gitbook.io/ssp-sdk/undefined-2/extra-guide/coupang/reco-v2-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.