> For the complete documentation index, see [llms.txt](https://docs.genser.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.genser.ai/integration/product-data-integration/standard-api/legacy-api.md).

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

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

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

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.genser.ai/integration/product-data-integration/standard-api/legacy-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.