# 표준 API 직접 연동

<figure><img src="/files/YehlINDMwTaT8Y0a7xdI" alt=""><figcaption></figcaption></figure>

표준 API 직접 연동은 고객사의 상품 정보를 API를 통해 genser로 데이터를 직접 전송하는 방식입니다.&#x20;

***

genser의 직접 연동 API는 데이터의 확장성과 상호운용성을 위해 다음과 같은 글로벌 기술 표준을 준수합니다.

* **JSON-LD & Schema.org:** 데이터에 의미를 부여하는 구조화된 데이터 포맷을 사용하여, Vertex AI가 상품의 맥락을 완벽하게 이해하도록 돕습니다.
* **CloudEvents:** 모든 상품 정보 변경을 '이벤트'로 취급하여, 시스템 간의 신뢰성 있는 데이터 교환을 보장합니다.

{% stepper %}
{% step %}

## 연동 준비하기 (Prepare)

API를 호출하기 위해 필요한 기본 정보입니다.

* **API Endpoint:** `https://api.genser.app/collectors/products`
* **Method:** `POST`
* **Content-Type:** `application/json` (또는 `application/ld+json`)
* **Service Key:** genser 어드민 \[설정] 메뉴에서 발급받은 `apiKey`

> **데이터 반영 시점 안내**
>
> API로 전송된 데이터는 즉시 검색 결과에 노출되지 않으며, 해당 국가의 현지 시간으로 매일 오전 00:15am에 실행되는 일괄 처리(Batch) 작업을 통해 검색 엔진에 반영됩니다.

{% endstep %}

{% step %}

## 인증하기 (Authenticate)

genser API는 복잡한 토큰 교환 방식 대신, 헤더(Header)에 키 값을 직접 포함하는 간편한 방식을 사용합니다. 어드민에서 발급받은 **Service Key**를 준비해 주세요. (`genser 어드민 > 설정` 에서 확인 가능)

* **Header Name:** `apiKey`&#x20;
* **Value:** 발급받은 키 값 그대로 입력 (Base64 인코딩 불필요)

**HTTP 요청 헤더 예시:**

```
POST /searches/products HTTP/1.1
Host: api.genser.app
Content-Type: application/json
apiKey: cb37cce9d6ae434fa366151b3420a9af //발급 받은 서비스 키
```

{% endstep %}

{% step %}

## 상품 데이터 전송하기 (Send Data)

신규 상품을 등록하거나, 기존 상품 정보(가격, 재고 등)가 변경되었을 때 아래 형식으로 데이터를 전송합니다. **JSON-LD** 및 **CloudEvents** 표준 규격을 따릅니다.

#### 요청 본문 (Request Body)

상품 수집 API를 호출할 때 본문(Body)에 포함해야 하는 최상위 필드입니다. 상세 상품 정보는 `@graph` 객체에 담아 전송합니다.

<table><thead><tr><th width="117.11328125">필드명</th><th width="96.91015625">타입</th><th width="79.609375">구분</th><th>설명</th></tr></thead><tbody><tr><td>@context</td><td>String</td><td>권장</td><td>JSON-LD 데이터의 기준 사전 정의 (값: <code>https://schema.org/</code>)</td></tr><tr><td>specversion</td><td>String</td><td>권장</td><td>CloudEvents 스펙 버전 (값: <code>1.0</code>)</td></tr><tr><td>id</td><td>String</td><td>권장</td><td>요청 건당 고유 식별자 (UUID 등)</td></tr><tr><td>type</td><td>String</td><td>권장</td><td>이벤트 유형 (예: create_product)</td></tr><tr><td>agent</td><td>Object</td><td>필수</td><td>데이터를 전송하는 주체(시스템) 식별값</td></tr><tr><td>@graph</td><td>Object</td><td>필수</td><td>실제 상품 정보가 포함된 Product 객체 리스트</td></tr></tbody></table>

#### 리소스 객체 (Resource Objects)

<table><thead><tr><th width="174.95703125">필드명</th><th width="89.03515625">타입</th><th width="80.3671875">구분</th><th>설명</th></tr></thead><tbody><tr><td>@type</td><td>String</td><td>필수</td><td>객체 타입 정의 (값: <code>Product</code>)</td></tr><tr><td>sku</td><td>String</td><td>필수</td><td>회사 내부에서 상품을 구분할 때 쓰는 관리 코드 (예: A001-Red)</td></tr><tr><td>name</td><td>String</td><td>필수</td><td>고객에게 보여지는 실제 상품의 이름</td></tr><tr><td>category</td><td>Object</td><td>필수</td><td>사이트에 진열되는 카테고리 분류 (예: 의류 > 남성 > 티셔츠)</td></tr><tr><td>└ @type</td><td>String</td><td>필수</td><td>객체 타입 정의 (값: <code>CategoryCode</code>)</td></tr><tr><td>└ name</td><td>String</td><td>필수</td><td>카테고리 명칭 (예: 스니커즈, 아우터)</td></tr><tr><td>└ code</td><td>String</td><td>권장</td><td>카테고리 분류 코드</td></tr><tr><td>brand</td><td>Object</td><td>필수</td><td>이 상품을 만든 브랜드 정보</td></tr><tr><td>└ @type</td><td>String</td><td>선택</td><td>객체 타입 정의 (값: <code>Brand</code>)</td></tr><tr><td>└ id</td><td>String</td><td>필수</td><td>브랜드 아이디</td></tr><tr><td>└ name</td><td>Object</td><td>필수</td><td>브랜드 이름, 브랜드 이름 표기 언어 코드(예: ko)</td></tr><tr><td>description</td><td>Object</td><td>필수</td><td>상품 설명, 언어 코드, 상품 설명 부가 정보 등</td></tr><tr><td>offers</td><td>Object</td><td>필수</td><td>가격 및 재고 정보 객체</td></tr><tr><td>└ @type</td><td>String</td><td>선택</td><td>객체 타입 정의 (값: <code>Offer</code>)</td></tr><tr><td>└ sku</td><td>String</td><td>필수</td><td>판매용 SKU</td></tr><tr><td>└ gtin</td><td>String</td><td>필수</td><td>전 세계적으로 통용되는 상품 고유 번호 (예: 880으로 시작하는 바코드, EAN/UPC)</td></tr><tr><td>└ mpn</td><td>String</td><td>필수</td><td>제조사에서 부여한 부품 번호나 모델명</td></tr><tr><td>└ price</td><td>Number</td><td>필수</td><td>고객이 실제로 결제하게 될 최종 판매 금액</td></tr><tr><td>└ priceCurrency</td><td>String</td><td>필수</td><td>결제 통화 기준 (한국은 KRW, 미국은 USD 등)</td></tr><tr><td>└ availability</td><td>String</td><td>필수</td><td>지금 구매가 가능한지 여부 ( 값: <code>InStock, OutOfStock, PreOrder</code>)</td></tr><tr><td>└ availabilityStarts</td><td>Date</td><td>필수</td><td>상품 판매가 시작되는 날짜와 시간 (2025-11-28T10:00:00Z)</td></tr><tr><td>└ availabilityEnds</td><td>Date</td><td>필수</td><td>상품 판매를 마감하는 날짜와 시간 (2025-11-28T10:00:00Z)</td></tr><tr><td>└ shippingDetails</td><td>Object</td><td>선택</td><td>배송 정보</td></tr><tr><td>└ image</td><td>Object</td><td>필수</td><td>상품 이미지</td></tr><tr><td>additionalProperty</td><td>Array</td><td>선택</td><td>관세청 신고를 위한 HS Code나 친환경 태그 등 특수한 추가 정보</td></tr><tr><td>└ @type</td><td>String</td><td>선택</td><td>정보가 어떤 형태인지 정의 (값: <code>PropertyValue</code>)</td></tr><tr><td>└ propertyID</td><td>String</td><td>선택</td><td><p>정보 이름표 (ID)<br></p><ul><li><code>html</code>: 웹용 HTML 설명</li><li><code>seo_title</code>: 검색 노출용 제목</li><li><code>hsCode</code>: 통관용 관세 코드</li><li><code>sustainabilityTags</code>: 친환경 태그</li></ul></td></tr><tr><td>└ value</td><td>String</td><td>선택</td><td>이름표에 해당하는 실제 내용 (예: 이름표가 <code>hsCode</code>라면, 값은 <code>851762</code>)</td></tr></tbody></table>

<details>

<summary><strong>요청 본문 샘플 코드 예시</strong></summary>

```js
{
  "@context": "https://schema.org/",
  "specversion": "1.0",
  "id": "EVT-CREATE-PRODUCT",
  "type": "create_product",
  "agent": {
    "@type": "Organization",
    "name": "ExampleCorp"
  },
  "@graph": [
    {
      "@type": "Product",
      "sku": "PROD-001-A",
      "name": {
        "@value": "프리미엄 블루투스 이어폰",
        "@language": "ko"
      },
      "description": [
        {
          "@type": "TextObject",
          "text": "완전 무선 블루투스 이어폰으로 고음질 사운드와 편안한 착용감을 제공합니다.",
          "inLanguage": "ko",
          "additionalProperty": [
            {
              "@type": "PropertyValue",
              "propertyID": "html",
              "value": "<p>완전 무선 블루투스 이어폰으로 <strong>고음질 사운드</strong>와 편안한 착용감을 제공합니다.</p>"
            },
            {
              "@type": "PropertyValue",
              "propertyID": "seo_title",
              "value": "프리미엄 블루투스 이어폰 - 고음질 무선 이어폰"
            },
            {
              "@type": "PropertyValue",
              "propertyID": "seo_description",
              "value": {
                "@value": "고음질 완전 무선 이어폰, 장시간 착용에도 편안한 프리미엄 제품",
                "@language": "ko"
              }
            }
          ]
        }
      ],
      "brand": {
        "@type": "Brand",
        "@id": "brand-001",
        "name": {
          "@value": "사운드맥스",
          "@language": "ko"
        },
        "logo": "https://example.com/brand/soundmax-logo.png"
      },
      "category": [
        {
          "@type": "CategoryCode",
          "codeValue": "ELEC001",
          "name": {
            "@value": "전자기기",
            "@language": "ko"
          },
          "position": 1
        },
        {
          "@type": "CategoryCode",
          "codeValue": "AUDIO005",
          "name": {
            "@value": "오디오 기기",
            "@language": "ko"
          },
          "position": 2
        }
      ],
      "positiveNotes": {
        "@value": "고음질, 장시간 배터리, 편안한 착용감",
        "@language": "ko"
      },
      "url": {
        "@value": "https://example.com/product/P001",
        "@language": "ko"
      },
      "itemCondition": "NewCondition",
      "hasAdultConsideration": "UnclassifiedAdultConsideration",
      "countryOfOrigin": {
        "@type": "Country",
        "address": "KR"
      },
      "material": {
        "@value": "플라스틱, 실리콘",
        "@language": "ko"
      },
      "offers": {
        "@type": "Offer",
        "sku": "PROD-001-A",
        "gtin": "8801234567890",
        "mpn": "SM-EAR-2025",
        "price": 129000,
        "priceCurrency": "KRW",
        "priceSpecification": {
          "@type": "UnitPriceSpecification",
          "price": 129000,
          "unitCode": "EA"
        },
        "availability": "InStock",
        "availabilityStarts": "2025-11-28T10:00:00Z",
        "availabliltyEnds": "2026-12-31T23:59:59Z", 
        "inventoryLevel": {
          "@type": "QuantitativeValue",
          "value": 250
        },
        "shippingDetails": {
          "@type": "OfferShippingDetails",
          "weight": {
            "@type": "QuantitativeValue",
            "value": 0.2,
            "unitCode": "KG"
          }
        },
        "image": [
          {
            "@type": "ImageObject",
            "contentUrl": "https://example.com/product/P001/main.jpg",
            "contentSize": "350KB",
            "width": {
              "@type": "QuantitativeValue",
              "value": 1080
            },
            "height": {
              "@type": "QuantitativeValue",
              "value": 1080
            }
          }
        ]
      },
      "additionalProperty": [
        {
          "@type": "PropertyValue",
          "propertyID": "hsCode",
          "value": "851762"
        },
        {
          "@type": "PropertyValue",
          "propertyId": "sustainabilityTags", 
          "value": ["lowEnergyConsumption", "recyclablePackaging"]
        }
      ]
    }
  ]
}
```

</details>

#### 다국어 정보 연동 (Multi-language Support)

단일 요청으로 여러 언어의 상품 정보를 동시에 등록할 수 있습니다. 글로벌 판매를 위해 상품명, 브랜드, 카테고리 등 텍스트 정보에 다국어 값을 설정하려면, 해당 필드를 JSON 배열(`Array`)로 변경하고 언어 코드(`@language`)를 구분하여 입력해 주세요.

* **기본 원칙**
  * **단일 언어:** Object 형식 `{ "@value": "...", "@language": "ko" }`
  * **다국어:** Array 형식 `[ { "ko" 데이터 }, { "en" 데이터 } ]`
* **지원 필드:** `name`, `brand.name`, `category.name`, `positiveNotes`, `material`, `url` 등
* **주의사항:** `description` 필드는 `inLanguage`속성을 사용하여 구분합니다.

<details>

<summary><strong>다국어 적용 요청 본문 샘플 코드 예시</strong></summary>

```js
{
  "@context": "https://schema.org/",
  "specversion": "1.0",
  "id": "EVT-CREATE-PRODUCT",
  "type": "create_product",
  "agent": {
    "@type": "Organization",
    "name": "ExampleCorp"
  },
  "@graph": [
    {
      "@type": "Product",
      "sku": "PROD-001-A",
      "name": [
        {
          "@value": "프리미엄 블루투스 이어폰",
          "@language": "ko"
        },
        {
          "@value": "Premium Bluetooth Earphones",
          "@language": "en"
        }
      ],
      "description": [
        {
          "@type": "TextObject",
          "text": "완전 무선 블루투스 이어폰으로 고음질 사운드와 편안한 착용감을 제공합니다.",
          "inLanguage": "ko",
          "additionalProperty": [
            {
              "@type": "PropertyValue",
              "propertyID": "html",
              "value": "<p>완전 무선 블루투스 이어폰...</p>"
            }
          ]
        },
        {
          "@type": "TextObject",
          "text": "True wireless bluetooth earphones providing high-quality sound and comfortable fit.",
          "inLanguage": "en",
          "additionalProperty": [
            {
              "@type": "PropertyValue",
              "propertyID": "html",
              "value": "<p>True wireless bluetooth earphones...</p>"
            }
          ]
        }
      ],
      "brand": {
        "@type": "Brand",
        "@id": "brand-001",
        "name": [
          {
            "@value": "사운드맥스",
            "@language": "ko"
          },
          {
            "@value": "SoundMax",
            "@language": "en"
          }
        ],
        "logo": "https://example.com/brand/soundmax-logo.png"
      },
      "category": [
        {
          "@type": "CategoryCode",
          "codeValue": "ELEC001",
          "name": [
             { "@value": "전자기기", "@language": "ko" },
             { "@value": "Electronics", "@language": "en" }
          ],
          "position": 1
        },
        {
          "@type": "CategoryCode",
          "codeValue": "AUDIO005",
          "name": [
             { "@value": "오디오 기기", "@language": "ko" },
             { "@value": "Audio Devices", "@language": "en" }
          ],
          "position": 2
        }
      ],
      "positiveNotes": [
        {
          "@value": "고음질, 장시간 배터리, 편안한 착용감",
          "@language": "ko"
        },
        {
          "@value": "High fidelity, Long battery life, Comfortable fit",
          "@language": "en"
        }
      ],
      "url": [
        {
          "@value": "https://example.com/product/P001",
          "@language": "ko"
        },
        {
          "@value": "https://example.com/en/product/P001",
          "@language": "en"
        }
      ],
      "itemCondition": "NewCondition",
      "hasAdultConsideration": "UnclassifiedAdultConsideration",
      "countryOfOrigin": {
        "@type": "Country",
        "address": "KR"
      },
      "material": [
        {
          "@value": "플라스틱, 실리콘",
          "@language": "ko"
        },
        {
          "@value": "Plastic, Silicone",
          "@language": "en"
        }
      ],
      "offers": {
        "@type": "Offer",
        "sku": "PROD-001-A",
        "gtin": "8801234567890",
        "mpn": "SM-EAR-2025",
        "price": 129000,
        "priceCurrency": "KRW",
        "priceSpecification": {
          "@type": "UnitPriceSpecification",
          "price": 129000,
          "unitCode": "EA"
        },
        "availability": "InStock",
        "availabilityStarts": "2025-11-28T10:00:00Z",
        "availabliltyEnds": "2026-12-31T23:59:59Z",
        "inventoryLevel": {
          "@type": "QuantitativeValue",
          "value": 250
        },
        "shippingDetails": {
          "@type": "OfferShippingDetails",
          "weight": {
            "@type": "QuantitativeValue",
            "value": 0.2,
            "unitCode": "KG"
          }
        },
        "image": [
          {
            "@type": "ImageObject",
            "contentUrl": "https://example.com/product/P001/main.jpg",
            "contentSize": "350KB",
            "width": {
              "@type": "QuantitativeValue",
              "value": 1080
            },
            "height": {
              "@type": "QuantitativeValue",
              "value": 1080
            }
          }
        ]
      },
      "additionalProperty": [
        {
          "@type": "PropertyValue",
          "propertyID": "hsCode",
          "value": "851762"
        },
        {
          "@type": "PropertyValue",
          "propertyId": "sustainabilityTags",
          "value": ["lowEnergyConsumption", "recyclablePackaging"]
        }
      ]
    }
  ]
}
```

</details>

{% endstep %}

{% step %}

## 응답 확인하기 (Check Response)

API 호출 후 HTTP 상태 코드를 확인하여 전송 성공 여부를 판단합니다.

#### 상태 코드 (HTTP Status Codes)

가장 먼저 확인해야 할 응답 상태 코드입니다.

<table><thead><tr><th width="166.3515625">상태 코드</th><th width="117.9609375">결과</th><th>설명</th></tr></thead><tbody><tr><td>200 OK</td><td>성공</td><td>성공입니다. 다음날 00:15am 배치를 통해 반영됩니다.</td></tr><tr><td>400 Bad Request</td><td>요청 형식 오류</td><td>JSON 문법이 틀렸거나, 필수 값(<code>sku</code>, <code>name</code> 등)이 누락되었는지 확인하세요.</td></tr><tr><td>401 Unauthorized</td><td>인증 실패</td><td>Header의 <code>apiKey</code> 값이 정확한지, 공백은 없는지 확인하세요.</td></tr><tr><td>500 Internal Error</td><td>서버 오류</td><td>일시적인 장애일 수 있습니다. 잠시 후 재시도(Retry) 로직을 실행하세요.</td></tr></tbody></table>
{% endstep %}
{% endstepper %}


---

# 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://docs.genser.ai/integration/product-data-integration/standard-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.