릴로
개발자 문서사용자 가이드
커스텀몰 API / 상품·카탈로그 조회

커스텀몰 API  /  상품·카탈로그

상품·카탈로그 조회

상품 문의에 답할 때 써요. 검색·상세는 v1.0 선택, 카탈로그 전체 목록과 카테고리는 v1.1 선택이에요.

상품 검색

GET/v1/products?product_name={keyword}&limit={n}

product_namestring필수

상품 이름 부분 일치

limitnumber선택

최대 50

응답 — 200 OK
{
  "data": [
    {
      "product_no": "77",
      "product_name": "Wool Crew Knit",
      "currency": "KRW",
      "price": "42000",
      "retail_price": "52000",
      "display": "T",
      "selling": "T",
      "sold_out": "F",
      "summary_description": "70% wool crew neck",
      "list_image": "https://cdn.mall.example.com/products/77/main.jpg",
      "product_url": "https://mall.example.com/product/77"
    }
  ]
}

상품 상세

GET/v1/products/{product_no}

릴로는 embed=variants를 붙여 호출해요. 옵션별 재고(variants)를 주면 ‘M 사이즈 있어요?’ 같은 질문에 정확히 답해요. 재고 수준은 릴로가 quantity로 계산해요(5개 이하면 적음).

product_nostring필수

상품 번호

product_namestring필수

상품 이름

price / retail_pricestring선택

판매가 / 소비자가

display / selling / sold_outstring선택

진열·판매·품절 여부 "T"/"F"

summary_descriptionstring선택

짧은 설명

descriptionstring선택

상세 설명. HTML 그대로 보내도 돼요 — 릴로가 태그를 지워요

list_imagestring선택

대표 이미지의 절대 https URL

detail_image / additional_imagesstring선택

상세·추가 이미지

product_material / origin_place_value / shipping_infostring선택

소재·원산지·배송 안내

variantsobject[]선택

옵션별 variant_code, options[], additional_amount, selling, use_inventory, quantity

currencystring선택

확장. 통화 (없으면 KRW)

product_urlstring선택

확장. 상품 페이지 URL

응답 — 200 OK
{
  "data": {
    "product_no": "77",
    "product_name": "Wool Crew Knit",
    "currency": "KRW",
    "price": "42000",
    "retail_price": "52000",
    "selling": "T",
    "sold_out": "F",
    "description": "<p>HTML is fine — Lillo strips the tags</p>",
    "list_image": "https://cdn.mall.example.com/products/77/main.jpg",
    "detail_image": "https://cdn.mall.example.com/products/77/detail.jpg",
    "product_material": "70% wool",
    "origin_place_value": "Korea",
    "shipping_info": "Ships same day for orders before 2 p.m.",
    "variants": [
      { "variant_code": "P000000X000A",
        "options": [{ "name": "Size", "value": "M" }],
        "additional_amount": "0", "selling": "T",
        "use_inventory": "T", "quantity": 3 }
    ]
  }
}

카탈로그 전체 목록 (v1.1)

GET/v1/products?since_product_no={n}&limit=100

since_product_no가 오면 검색이 아니라 전체 목록 모드예요. 지식의 ‘상품’ 폴더를 이 목록으로 동기화해요 (capabilities catalog).

  • product_no가 since_product_no보다 큰 상품을 번호 오름차순으로 limit(최대 100)개 돌려주세요.
  • 진열·판매 여부와 상관없이 전부 주세요. 숨김은 릴로가 처리해요. 마지막 페이지는 limit보다 적게 돌려주면 돼요.
  • category, options, created_date와 확장 필드 sales_count(최근 90일 판매 수량, 선택)를 더할 수 있어요. sales_count가 있으면 인기순에 써요.
  • 릴로는 6시간마다(KST 00:20·06:20·12:20·18:20), 그리고 연결 테스트를 통과한 직후에 불러요. 페이지 사이 0.6초 간격, 한 번에 최대 5,000개예요.
  • 가격·재고는 답하기 직전에 상품 상세로 다시 확인해요. 목록은 찾기용 스냅샷이에요.
응답 — 목록의 상품 하나
{
  "product_no": "77",
  "product_name": "Wool Crew Knit",
  "price": "42000",
  "retail_price": "52000",
  "display": "T",
  "selling": "T",
  "sold_out": "F",
  "created_date": "2026-09-01T10:00:00+09:00",
  "list_image": "https://cdn.mall.example.com/products/77/main.jpg",
  "product_url": "https://mall.example.com/product/77",
  "category": [{ "category_no": "24", "recommend": "F", "new": "T" }],
  "options": { "options": [
    { "option_name": "Color",
      "option_value": [{ "option_text": "Ivory" }, { "option_text": "Black" }] }
  ] },
  "sales_count": 132
}

카테고리 (v1.1)

GET/v1/categories

limitnumber선택

최대 100

offsetnumber선택

건너뛸 개수

응답 — 200 OK
{
  "data": [
    { "category_no": "24", "category_name": "Knitwear",
      "parent_category_no": "1", "category_depth": 2 }
  ]
}
이전회원 조회다음주문 쓰기
상품·카탈로그 조회 · 개발자 문서 | 릴로