api4.yml

swagger: "2.0"
info:
  description: "여러 마켓을 하나의 API로 통합 연동 할 수 있습니다. `RESTful API`로 제공되며, `snake_case`를 사용 합니다."
  version: 4.0.0
  title: PLAYAPI ENGINES API V4
  termsOfService: "http://www.playauto.co.kr/"
  contact:
    email: "[email protected]"
  license:
    name: PLAYAUTO INC (ISC)
host: engines.playapi.io
basePath: /v4
tags:
  - name: products
    description: 상품 API
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json

# -----------------------------------------  
# Endpoint 정의 시작 
# -----------------------------------------  
  
paths:
  /products:
    post:
      tags:
        - products
      summary: 마켓에 상품을 등록 합니다.
      description: ""
      parameters:
        - in: body
          name: products
          description: 등록 데이터
          required: true
          schema:
            type: array
            items: 
              $ref: "#/definitions/product"
        
      responses:
        200:
          description: 처리 결과 
        400:
          description: Invalid input
        500:
          description: Server Error
    
          
# -----------------------------------------  
# 모델 정의 시작 
# - product
# - product_item
# - product_ids
# - shipping
# -----------------------------------------  
definitions:

  product: 
    description: 상품 모델 (하위에 여러개의 SKU 상품으로 구성 됩니다.)
    properties: 
      market_account_uuid: 
        description: 등록할 판매자 계정 고유ID
        type: string
      market_category_id: 
        description: 마켓 카테고리 ID
        type: string
      parent_sku: 
        description: 상품 그룹 코드 (이 값은 `부모 SKU`로 사용 됩니다.)
        type: string
      parent_title: 
        description: 그룹 대표 상품명
        type: string
      items: 
        description: SKU 단위의 자식 상품 목록 (선택형 옵션으로 등록)
        type: array
        items: 
          $ref: "#/definitions/product_item"
      main_sku:
        description: 자식 상품 목록 중, 부모 상품에서 대표로 사용할 상품 SKU값 
        type: string
      addon_items:
        description: SKU 단위의 추가 구매 상품 목록 (일부 마켓은 지원하지 않음)
        type: array
        items: 
          $ref: "#/definitions/product_item"
      shipping: 
        type: string
        description: 배송 정보 구성중 
      setform_uuid: 
        description: 세트폼 고유 ID
        type: string
    required: 
      - market_account_uuid
      - setform_uuid
      - sku
      - market_category_id
      - product_name
      - product_items
      - master_sku
      - shipping
    
  # 상품 sku 단위 모델 
  product_item: 
    description: SKU 단위 상품 모델 
    properties: 
      sku: 
        description: 상품 SKU 
        type: string
      product_ids:
        $ref: "#/definitions/product_ids"
      title: 
        description: 상품명
        type: string
      currency:
        description: 적용 통화 
        type: string
        enum: [USD,CAD,EUR,KRW,JPY,CNY]
      standard_price: 
        description: 정상 판매가
        type: double
      sale:
        description: 세일 설정 
        properties:
          start_date:
            description: 세일 시작일
            type: datetime
          end_date:
            description: 세일 종료일 
            type: datetime
          sale_price:
            description: 세일 판매가 
            type: double
      promo_tag:
        description: 프로모션 
        properties:
          promo_type: 
            description: 프로모션 타입
            type: string
            enum: [SALE, NEW, NEWARRIVAL, WEBONLY, CLEARANCE, LIMITEDOFFER, SPECIALOFFER, SPECIALPURCHASE, ONLYINSTORES]
          from_data:
            description: 프로모션 시작일
            type: date
          through_data:
            description: 프로모션 종료일
            type: date
      quantity: 
        description: 재고 수량 
        type: integer
      tax_code: 
        description: >
          과세 유형 코드:
            * `GEN_TAX` - 일반 상품 (과세) 
            * `GEN_NOTAX` - 일반 상품 (비과세)
            * `BOOKS_GEN` - 일반 서적류
            * `BOOKS_RELIG` - 종교 서적류
        type: string
        enum: [GEN_TAX, GEN_NOTAX, BOOKS_GEN, BOOKS_RELIG]
      condition:
        description: 상품 상태 
        properties:
          condition_type:
            description: >
              상품 상태:
                * `NEW` - 새 상품
                * `USED_LIKE_NEW` - 새 상품 같은 중고
                * `USED_VERY_GOOD` - 상태 좋은 중고
                * `REFURBISHED` - 반품된 상품 
            type: string
            enum: [NEW, USED_LIKE_NEW, USED_VERY_GOOD, REFURBISHED] 
          condition_note:
            description: 상품 상태 코멘트
            type: string
      item_package_quantity:
        description: 하나의 패키지에 포함 된 동일한 제품의 갯수. 10개의 양말 패키지의 경우, item_package_quantity는 10입니다.
        type: integer
      number_of_items:
        description: 제품에 포함 된 개별 품목의 수로, 각 품목은 개별 판매용으로 포장되지 않습니다. 각 패키지에 3쌍의 양말이 들어있는 10개 짜리 상품의 경우 number_of_items는 30입니다.
        type: integer
      brand: 
        description: 브랜드
        type: string
      designer: 
        description: 디자이너
        type: string
      description_text: 
        description: 긴 상품 소개 Text (HTML을 사용할 수 없는 마켓용)
        type: string
      description_html: 
        description: 긴 상품 소개 HTML 
        type: string
      bullet_point:
        description: 제품 기능에 대한 간략한 설명 
        type: string
      item_dimensions:
        $ref: "#/definitions/dimensions"
      package_dimensions:
        $ref: "#/definitions/dimensions"
      merchant_catalog_code:
        description: 판매자의 자체 상품 코드 (SKU와 다른 값인 경우 사용)
        type: string
      msrp:
        description: 제조사의 권장 소비자가 
        type: double
      max_order_quantity:
        description: 고객이 주문할 수있는 제품의 최대 수량
        type: integer
      manufacturer:
        description: 제조사
        type: string
      search_terms:
        description: 제품 검색용 키워드 (최대 5개)
        type: array
        items:
          type: string
      target_audience:
        description: 구매 가능 대상 제한 
        type: string
        enum: [ADULTS,CHILDREN,MEN,WOMEN]
      is_gift_wrap_available:
        description: 선물 포장 가능 여부 
        type: boolean
      is_gift_message_available:
        description: 선물 메시지 전달 가능 여부
        type: boolean
      size: 
        description: 사이즈 값
        type: string
      color: 
        description: 색상 값 
        type: string
      style_name:
        description: 스타일 값 
        type: string
      model_number: 
        description: 모델명
        type: string
      country_of_origin: 
        description: 원산지 국가 코드 (2자로 된 국가코드)
        type: string 
      country_produced_in: 
        description: 원산지 표시명  
        type: string 
      images: 
        description: 이미지 URL 목록 (첫번째 url을 메인 이미지로 사용)
        type: array
        items:
          type: string
          description: 이미지 URL (http/https)
    required: 
      - sku
      - title
      - standard_price
      - quantity
      - tax_code
      - condition
      - description_text
      - description_html
      - manufacturer
      - size
      - color
      - images
      - country_of_origin
  
  product_ids:
    description: 상품 표준ID 정보
    properties: 
      asin: 
        type: string
        description: ASIN (Amazon Standard Identification Numbers)
      upc: 
        type: string
        description: UPC (Universal Product Code)
      ean: 
        type: string
        description: EAN (European Article Number)
      isbn: 
        type: string
        description: ISBN (International Standard Book Number)
      hscode:
        type: string
        description: HS CODE (Harmonized System code)

  dimensions:
    description: 치수 정보
    properties:
      unit_of_size_measure: 
        description: 사이즈 단위
        enum: [CM,M,IN,FT]
        type: string
      width:
        description: 가로
        type: float
      length:
        description: 세로
        type: float
      height:
        description: 높이
        type: float
      unit_of_weight_measure: 
        description: 무게 단위
        enum: [LB,KG]
        type: string
      weight:
        description: 무게
        type: float