표준 API 직접 연동

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

---

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

• JSON-LD & Schema.org: 데이터에 의미를 부여하는 구조화된 데이터 포맷을 사용하여, Vertex AI가 상품의 맥락을 완벽하게 이해하도록 돕습니다.

• CloudEvents: 모든 상품 정보 변경을 '이벤트'로 취급하여, 시스템 간의 신뢰성 있는 데이터 교환을 보장합니다.

1

연동 준비하기 (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) 작업을 통해 검색 엔진에 반영됩니다.

2

인증하기 (Authenticate)

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

• Header Name: apiKey

• Value: 발급받은 키 값 그대로 입력 (Base64 인코딩 불필요)

HTTP 요청 헤더 예시:

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

3

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

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

요청 본문 (Request Body)

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

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

리소스 객체 (Resource Objects)

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

요청 본문 샘플 코드 예시

{
  "@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"]
        }
      ]
    }
  ]
}

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

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

• 기본 원칙

  • 단일 언어: Object 형식 { "@value": "...", "@language": "ko" }

  • 다국어: Array 형식 [ { "ko" 데이터 }, { "en" 데이터 } ]

• 지원 필드: name, brand.name, category.name, positiveNotes, material, url 등

• 주의사항: description 필드는 inLanguage속성을 사용하여 구분합니다.

다국어 적용 요청 본문 샘플 코드 예시

{
  "@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"]
        }
      ]
    }
  ]
}

4

응답 확인하기 (Check Response)

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

상태 코드 (HTTP Status Codes)

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

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