# 레거시 API 연동 (v0.3)

본 가이드는 **기존 전용 API(v0.3)를 이용해 상품 데이터를 연동 중인 고객사**를 위한 페이지입니다.

해당 규격은 상품의 기본 정보부터 브랜드, 카테고리, 상세 가격 정보를 계층 구조(Object)로 수집합니다. 만약 신규로 연동을 진행하시는 고객사라면, 본 페이지 대신 [\[표준 API 직접 연동\]](https://docs.genser.ai/integration/product-data-integration/standard-api) 가이드를 참고해 주시기 바랍니다.

## 1. 개요 및 연동 정보

고객사의 상품 데이터를 genser API 엔드포인트로 전송하여 검색 엔진에 반영합니다.

<table><thead><tr><th width="181.09765625">항목</th><th>내용</th></tr></thead><tbody><tr><td><strong>Endpoint (운영)</strong></td><td><a href="https://api.genser.app/searches/products">https://api.genser.app/searches/products</a></td></tr><tr><td><strong>HTTP Method</strong></td><td><code>POST</code></td></tr><tr><td><strong>인증 방식</strong></td><td>Header에 <code>x-api-key: {발급받은_API_KEY}</code> 포함</td></tr></tbody></table>

## 2. 데이터 업데이트 및 반영 시점

데이터는 성격별로 반영 시점이 다릅니다.

* **일반 상품 정보 (신규/수정):** 매일 **오전 00:15** 일괄 업데이트 (Batch)
* **품절 정보 (Status):** 데이터 수신 즉시 **실시간** 반영
* **업데이트 방법:** 상품 정보가 변경되거나 신규 등록될 때마다 동일한 API를 다시 호출하여 최신 데이터를 전송해 주세요.

## 3. 상세 데이터 규격 (v0.3)

필드 정의서에 따른 주요 항목들입니다.&#x20;

### 3.1 검색 상품 (Product)

<table><thead><tr><th width="206.3359375">필드명</th><th width="146.8984375">타입</th><th width="74.63671875">필수</th><th width="489.00390625">설명</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>Y</td><td>상품 고유 코드</td></tr><tr><td>name</td><td>String</td><td>Y</td><td>상품명</td></tr><tr><td>brand</td><td>Object</td><td>Y</td><td>브랜드 정보</td></tr><tr><td>└ code</td><td>String</td><td>Y</td><td>브랜드 이름</td></tr><tr><td>└ name</td><td>String</td><td>Y</td><td>브랜드코드</td></tr><tr><td>categories</td><td>Array</td><td>Y</td><td>카테고리 정보</td></tr><tr><td>└ largeCode</td><td>String</td><td>Y</td><td>대분류 코드</td></tr><tr><td>└ largeName</td><td>String</td><td>Y</td><td>대분류 이름</td></tr><tr><td>└ midCode</td><td>String</td><td>N</td><td>중분류 코드</td></tr><tr><td>└ midName</td><td>String</td><td>N</td><td>중분류 이름</td></tr><tr><td>└ smallCode</td><td>String</td><td>N</td><td>소분류 코드</td></tr><tr><td>└ smallName</td><td>String</td><td>N</td><td>소분류 이름</td></tr><tr><td>└ detailCode</td><td>String</td><td>N</td><td>세분류 코드</td></tr><tr><td>└ detailName</td><td>String</td><td>N</td><td>세분류 이름</td></tr><tr><td>image</td><td>Object</td><td>Y</td><td>상품 이미지 정보</td></tr><tr><td>└ mainUrl</td><td>String</td><td>Y</td><td>대표 이미지 url</td></tr><tr><td>└ detailUrls</td><td>Array</td><td>Y</td><td>상품 상세 이미지 URL 배열</td></tr><tr><td>└ productUrl</td><td>String</td><td>N</td><td>제품 상세 페이지 url</td></tr><tr><td>priceInfo</td><td>Object</td><td>Y</td><td>가격 정보</td></tr><tr><td>└ currency</td><td>String</td><td>Y</td><td>통화 코드</td></tr><tr><td>└ price</td><td>Double</td><td>Y</td><td>상품 가격</td></tr><tr><td>└ salePrice</td><td>Double</td><td>Y</td><td>상품 할인가격</td></tr><tr><td>└ salePercent</td><td>Double</td><td>N</td><td>상품 할인율</td></tr><tr><td>rating</td><td>Object</td><td>N</td><td>리뷰 정보</td></tr><tr><td>└ reviewCount</td><td>Integer</td><td>N</td><td>리뷰수</td></tr><tr><td>└ avgRating</td><td>Double</td><td>N</td><td>평균 평점</td></tr><tr><td>└ avgDeliveryRating</td><td>Double</td><td>N</td><td>평균 배송 평점</td></tr><tr><td>createdAt</td><td>String</td><td>Y</td><td>상품 등록일</td></tr><tr><td>createdAtEpochMilli</td><td>Long</td><td>N</td><td>상품 등록일</td></tr><tr><td>isInStock</td><td>Boolean</td><td>N</td><td>상품 재고 여부</td></tr><tr><td>attribute</td><td>Object</td><td>N</td><td>상품 속성 정보</td></tr><tr><td>└ description</td><td>String</td><td>N</td><td>상품 상세 정보</td></tr><tr><td>└ keywords</td><td>Array</td><td>N</td><td>주요 키워드</td></tr><tr><td>└ colors</td><td>Array</td><td>N</td><td>색상</td></tr><tr><td>└ series</td><td>String</td><td>N</td><td>시리즈</td></tr><tr><td>└ situations</td><td>Array</td><td>N</td><td>상황</td></tr><tr><td>└ seasons</td><td>Array</td><td>N</td><td>계절</td></tr><tr><td>└ materials</td><td>Array</td><td>N</td><td>소재</td></tr><tr><td>└ gender</td><td>Array</td><td>N</td><td>성별</td></tr><tr><td>└ ages</td><td>Array</td><td>N</td><td>연령대</td></tr><tr><td>└ sizes</td><td>Array</td><td>N</td><td>공통 사이즈</td></tr><tr><td>└ features</td><td>Array</td><td>N</td><td>상품 특징</td></tr><tr><td>└ styles</td><td>Array</td><td>N</td><td>상품 스타일</td></tr><tr><td>└ installTime</td><td>Integer</td><td>N</td><td>설치 예상 시간 (분)</td></tr><tr><td>└ flavor</td><td>Array</td><td>N</td><td>맛</td></tr><tr><td>└ maxLoad</td><td>String</td><td>N</td><td>최대 하중</td></tr><tr><td>└ skinType</td><td>Array</td><td>N</td><td>적합 피부타입</td></tr><tr><td>└ spf</td><td>Array</td><td>N</td><td>자외선 차단 지수</td></tr><tr><td>└ fragrance</td><td>Array</td><td>N</td><td>향</td></tr><tr><td>└ energyGrade</td><td>String</td><td>N</td><td>에너지효율 등급</td></tr><tr><td>└ originCountry</td><td>String</td><td>N</td><td>제조국 / 원산지</td></tr><tr><td>└ promotions</td><td>String</td><td>N</td><td>상품 프로모션</td></tr><tr><td>└ isBroadcast</td><td>Boolean</td><td>N</td><td>방송된 상품 유무</td></tr><tr><td>└ width</td><td>Double</td><td>N</td><td>가로</td></tr><tr><td>└ height</td><td>Double</td><td>N</td><td>높이</td></tr><tr><td>└ depth</td><td>Double</td><td>N</td><td>세로</td></tr><tr><td>└ skinColors</td><td>Array</td><td>N</td><td>피부색상</td></tr><tr><td>└ diseaseInfos</td><td>Array</td><td>N</td><td>질병종류</td></tr><tr><td>└ functions</td><td>Array</td><td>N</td><td>기능</td></tr><tr><td>└ applyAreas</td><td>Array</td><td>N</td><td>적용 부위</td></tr><tr><td>└ alternatives</td><td>Array</td><td>N</td><td>대체 상품 리스트</td></tr><tr><td>customs</td><td>Array</td><td>N</td><td>고객사 커스텀 데이터</td></tr><tr><td>└ name</td><td>String</td><td>Y</td><td>이름</td></tr><tr><td>└ values</td><td>Array</td><td>N</td><td>값</td></tr></tbody></table>

<details>

<summary>검색 상품 데이터 JSON 요청 예시</summary>

```js
[
  {
    "code": "P-KR-2025-001",
    "name": "프리미엄 울 니트 가디건",
    "brand": {
      "code": "BR-LOMO",
      "name": "로모 스튜디오"
    },
    "categories": [
      {
        "largeCode": "10",
        "largeName": "여성의류",
        "midCode": "1010",
        "midName": "아우터",
        "smallCode": "101010",
        "smallName": "가디건",
        "detailCode": "10101001",
        "detailName": "라운드넥 가디건"
      }
    ],
    "image": {
      "mainUrl": "https://api.example.co.kr/images/products/2025/05/wool_cardigan_main.jpg",
      "detailUrls": [
        "https://api.example.co.kr/images/products/2025/05/wool_cardigan_detail_01.jpg",
        "https://api.example.co.kr/images/products/2025/05/wool_cardigan_detail_02.jpg"
      ],
      "productUrl": "https://www.example.co.kr/product/detail.html?product_no=1001"
    },
    "priceInfo": {
      "currency": "KRW",
      "price": 50000.0,
      "salePrice": 45000.0,
      "salePercent": 10.0
    },
    "rating": {
      "reviewCount": 128,
      "avgRating": 4.8,
      "avgDeliveryRating": 4.9
    },
    "createAt": "2025-05-03T09:30:00+09:00",
    "createdAtEpochMilli": 1746232200000,
    "isInStock": true,
    "attribute": {
      "description": "부드러운 촉감의 오버핏 울 가디건으로, 클래식한 감성과 현대적인 실루엣이 조화를 이룹니다.",
      "keywords": ["울 가디건", "오버핏", "하객룩", "봄 아우터", "데일리룩"],
      "series": "2025 Spring 컬렉션",
      "situations": ["출근룩", "데이트룩", "주말 나들이"],
      "seasons": ["봄", "가을", "간절기"],
      "materials": ["울 80%", "폴리에스터 20%"],
      "gender": ["여성", "남녀공용"],
      "ages": ["20대", "30대"],
      "sizes": ["Free", "S", "M", "L"],
      "features": ["오버핏", "드롭숄더", "안감 없음", "신축성 좋음"],
      "styles": ["미니멀", "캐주얼", "베이직"],
      "originCountry": "대한민국",
      "promotions": ["신규가입 쿠폰 적용가능"],
      "isBroadcast": false
    },
    "customs": [
      {
        "name": "gift_option",
        "values": ["선물 포장", "쇼핑백 동봉"]
      }
    ]
  }
]
```

</details>

### 3.2 필터 (Filters)

<table><thead><tr><th width="226.76953125">필드명</th><th width="96.58984375">타입</th><th width="79.49609375">필수</th><th>설명</th></tr></thead><tbody><tr><td>httpStatus</td><td></td><td></td><td>http 상태</td></tr><tr><td>└ code</td><td>String</td><td>Y</td><td>HTTP 상태코드</td></tr><tr><td>└ reasonPhrase</td><td>String</td><td>Y</td><td>HTTP 상태메세지</td></tr><tr><td>processCode</td><td>String</td><td>Y</td><td>요청의 성공여부 “OK“ or “FAIL“</td></tr><tr><td>processValue</td><td>Object</td><td>Y</td><td>요청의 결과값</td></tr></tbody></table>

<details>

<summary>필터 데이터 JSON 요청 예시</summary>

```js
[
    {
        "name": "color",
        "values": [
            "골드",
            "베이지",
            "브라운"
        ]
    }
]
```

</details>

### 3.3 콘텐트 (Content)

콘텐트 수집 API 입니다.&#x20;

<table><thead><tr><th width="239.60546875">필드명</th><th width="98.1484375">타입</th><th width="77.72265625">필수</th><th width="489.00390625">설명</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>Y</td><td>콘텐츠 코드</td></tr><tr><td>name</td><td>String</td><td>Y</td><td>콘텐츠 이름</td></tr><tr><td>categories</td><td>Array</td><td>Y</td><td>상품 카테고리</td></tr><tr><td>└ largeCode</td><td>String</td><td>Y</td><td>대분류 코드</td></tr><tr><td>└ largeName</td><td>String</td><td>Y</td><td>대분류 이름</td></tr><tr><td>└ midCode</td><td>String</td><td>N</td><td>중분류 코드</td></tr><tr><td>└ midName</td><td>String</td><td>N</td><td>중분류 이름</td></tr><tr><td>└ smallCode</td><td>String</td><td>N</td><td>소분류 코드</td></tr><tr><td>└ smallName</td><td>String</td><td>N</td><td>소분류 이름</td></tr><tr><td>└ detailCode</td><td>String</td><td>N</td><td>세분류 코드</td></tr><tr><td>└ detailName</td><td>String</td><td>N</td><td>세분류 이름</td></tr><tr><td>image</td><td>Object</td><td>Y</td><td>상품 이미지 정보</td></tr><tr><td>└ mainUrl</td><td>String</td><td>Y</td><td>대표 이미지 url</td></tr><tr><td>└ detailUrls</td><td>Array</td><td>Y</td><td>상품상세이미지 url</td></tr><tr><td>└ productUrl</td><td>String</td><td>N</td><td>제품 상세 페이지 url</td></tr><tr><td>priceInfo</td><td>Object</td><td>Y</td><td>가격 정보</td></tr><tr><td>└ currency</td><td>String</td><td>Y</td><td>통화</td></tr><tr><td>└ price</td><td>Double</td><td>Y</td><td>상품 가격</td></tr><tr><td>└ salePrice</td><td>Double</td><td>Y</td><td>상품 할인가격</td></tr><tr><td>└ salePercent</td><td>Double</td><td>N</td><td>상품 할인율</td></tr><tr><td>createdAt</td><td>String</td><td>Y</td><td>상품 등록일</td></tr><tr><td>createdAtEpochMilli</td><td>Long</td><td>N</td><td>상품 등록일</td></tr><tr><td>languageCode</td><td>String</td><td>N</td><td>언어 코드</td></tr><tr><td>display</td><td>Object</td><td>N</td><td>전시 정보</td></tr><tr><td>└ isYn</td><td>Boolean</td><td>N</td><td>전시 여부</td></tr><tr><td>└ start</td><td>Long</td><td>Y</td><td>전시 시작 시간</td></tr><tr><td>└ end</td><td>Long</td><td>Y</td><td>전시 종료 시간</td></tr><tr><td>attribute</td><td>Object</td><td>N</td><td>상품 속성 정보</td></tr><tr><td>└ description</td><td>String</td><td>N</td><td>상품 설명</td></tr><tr><td>└ keywords</td><td>Array</td><td>N</td><td>주요 키워드</td></tr><tr><td>└ series</td><td>String</td><td>N</td><td>시리즈</td></tr><tr><td>└ location</td><td>String</td><td>N</td><td>위치</td></tr><tr><td>└ branchName</td><td>String</td><td>N</td><td>지점명</td></tr><tr><td>└ instructorName</td><td>String</td><td>N</td><td>강사명</td></tr><tr><td>└ sessionCount</td><td>Int</td><td>N</td><td>강의횟수</td></tr><tr><td>└ materialsPrice</td><td>Double</td><td>N</td><td>재료비</td></tr><tr><td>└ requiredSupplies</td><td>String</td><td>N</td><td>준비물</td></tr><tr><td>└ textbookInfo</td><td>String</td><td>N</td><td>교재정보</td></tr><tr><td>└ note</td><td>String</td><td>N</td><td>유의사항</td></tr><tr><td>└ cancellationRefundPolicy</td><td>String</td><td>N</td><td>강좌 취소 및 환불안내</td></tr><tr><td>└ phoneNumber</td><td>String</td><td>N</td><td>전화번호</td></tr><tr><td>└ lastOrder</td><td>Long</td><td>N</td><td>라스트오더 시간</td></tr><tr><td>└ menuName</td><td>Array</td><td>N</td><td>메뉴명</td></tr><tr><td>└ menuPrice</td><td>Array</td><td>N</td><td>메뉴 가격</td></tr><tr><td>└ menuDescription</td><td>Array</td><td>N</td><td>메뉴 설명</td></tr></tbody></table>

<details>

<summary>콘텐츠 정보 수집 JSON 요청 예시</summary>

```js
[
  {
    "code": "F-KR-2025-MK01",
    "name": "프리미엄 티본 스테이크 밀키트 (2인분)",
    "categories": [
      {
        "largeCode": "50",
        "largeName": "식품",
        "midCode": "5010",
        "midName": "밀키트/간편식",
        "smallCode": "501010",
        "smallName": "메인요리",
        "detailCode": "50101001",
        "detailName": "스테이크/고기"
      }
    ],
    "image": {
      "mainUrl": "https://api.example.co.kr/images/food/2025/steak_kit_main.jpg",
      "detailUrls": [
        "https://api.example.co.kr/images/food/2025/steak_kit_detail_01.jpg",
        "https://api.example.co.kr/images/food/2025/steak_kit_detail_02.jpg"
      ]
    },
    "priceInfo": {
      "currency": "KRW",
      "price": 65000.0,
      "salePrice": 58500.0,
      "salePercent": 10.0
    },
    "createAt": "2025-05-15T10:00:00+09:00",
    "createdAtEpochMilli": 1747270800000,
    "languageCode": "ko",
    "display": {
      "isYn": true,
      "start": 1747270800000,
      "end": 2534022000000
    },
    "attribute": {
      "description": "유명 레스토랑의 맛 그대로, 집에서 즐기는 프리미엄 숙성 티본 스테이크 쿠킹 박스입니다.",
      "keywords": [
        "밀키트",
        "홈파티",
        "캠핑요리",
        "스테이크",
        "기념일"
      ],
      "series": "2025 홈 다이닝 컬렉션",
      "location": "충청북도 음성군 (HACCP 인증 제조시설)",
      "brandName": "셰프의 식탁",
      "instructorName": "에드워드 홍 셰프",
      "sessionCount": 2,
      "materialsPrice": 0,
      "requiredSupplies": "조리도구(프라이팬) 외 필요 없음",
      "textbookInfo": "시크릿 레시피 카드 동봉",
      "note": "신선식품 특성상 배송 후 단순 변심 반품 불가",
      "cancellationRefundPolicy": "출고 전 취소 가능, 출고 후 환불 불가",
      "phoneNumber": "1544-0000",
      "lastOrder": 1762837200000,
      "menuName": "티본 스테이크 & 가니쉬 세트",
      "menuPrice": 58500,
      "menuDescription": "30일 숙성 티본(500g) + 아스파라거스 + 특제 소스"
    }
  }
]
```

</details>

## 4. 응답 코드 (Response)

API 호출 후 응답 본문의 `processCode`를 통해 성공 여부를 확인합니다.

* **processCode "0":** 정상 접수 (익일 00:15 반영 예정)
* **그 외 코드:** 오류 발생 (응답 본문의 `processValue` 메시지 확인 필요)

{% hint style="info" %}
**데이터 반복 안내**

데이터가 Array 타입일 때, 데이터가 반복될 수 있습니다.&#x20;
{% endhint %}

{% hint style="info" %}
**개발 가이드 팁**

* 품절 정보를 실시간으로 반영하려면 `inInstock` 필드를 포함하여 API를 즉시 호출하세요.
* 상품 상세 정보가 수정된 경우, 변경된 필드뿐만 아니라 전체 스키마를 포함하여 다시 전송하는 것이 안전합니다.
  {% endhint %}