세원 시스템 API 연동 명세서

1. 연동 개요

목적
화면 단위 API 개발의 비효율성을 해소하고, 퍼널 중심의 동적 데이터 활용 체계를 구축합니다.
리소스 테이블 기반의 표준 API 모델을 정립하여 향후 확장 가능한 구조를 만듭니다.

배경

화면 단위 API 개발은 건별 비용, 확장성, 유지보수 측면에서 비효율적
DB 직접 접근은 보안 리스크 및 비즈니스 로직 누락 위험 존재
표준화된 API를 통한 안전하고 확장 가능한 데이터 통신 필요

기대 효과

차일디: AI 기반 수요 예측, 발주 최적화, 재고 건전성 확보
세원: 표준 API 모델 확보로 타 고객사 유료 옵션 제공 가능

2. 단계별 개발 로드맵

1

조회 전용 API

운영 DB 부하를 최소화하면서 필요한 데이터를 호출하는 읽기 전용 인터페이스 구축

2

상태 변경 API

입고 확정, 출고 처리 등 기존 데이터의 상태를 변경하는 비즈니스 로직 연동

3

생성 API

신규 데이터 생성을 포함한 완전한 CRU 기능 구현 (삭제는 데이터 무결성 보호를 위해 제외)

중요: 직접 DB를 건드리는 것은 데이터 무결성을 해칠 수 있으므로, 세원이 검증한 표준 API를 통해 안전하게 소통합니다.

3. 도메인 구성

세원 시스템과의 데이터 연동은 5개의 핵심 도메인으로 구성됩니다. 각 도메인은 독립적인 API 세트를 제공하며, 차일디 시스템의 AI 기반 분석 및 최적화 기능을 지원합니다.

📦

상품

상품 등록/수정/조회, 카테고리, 속성 정보

💰

원가

사전/사후 원가 정보 관리 및 비교

📥

입출고

품번 일자별 입고, 출고 데이터

📊

재고

매장/창고별 실시간 재고

💳

판매

주문, 취소/반품, 매출 내역

4. 공통 규격

4.1 인증 방식

모든 API 요청 시 Bearer 토큰 방식의 인증이 필요합니다.

요청 헤더

Authorization: Bearer {access_token}
Content-Type: application/json

4.2 에러 응답 형식

API 오류 발생 시 표준화된 에러 응답을 반환합니다.

에러 응답 예시

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "brand_code는 필수 파라미터입니다.",
    "details": {
      "field": "brand_code",
      "reason": "required"
    }
  }
}

주요 에러 코드

코드	설명
INVALID_PARAMETER	잘못된 파라미터
UNAUTHORIZED	인증 실패
NOT_FOUND	리소스를 찾을 수 없음
INTERNAL_ERROR	서버 내부 오류

4.3 페이지네이션

모든 목록 조회 API는 페이지네이션을 지원합니다.

파라미터	설명	기본값
page	페이지 번호 (1부터 시작)	1
limit	페이지당 건수	100 (최대: 1000)

4.4 날짜/시간 형식

타입	형식	예시
날짜	YYYY-MM-DD	2026-03-04
날짜시간	ISO 8601	2026-03-04T15:30:00Z

5. 상품(Product) API

5.1 상품 목록 조회

GET /api/v1/products

상품 마스터 정보를 조회합니다. 브랜드, 시즌, 품번 등으로 필터링 가능합니다.

요청 파라미터

파라미터	타입	필수	설명
brand_code	string	선택	브랜드 코드 (예: HR)
season	string	선택	시즌 (예: 2026)
product_name	string	선택	상품명 (부분 검색 가능)
main_category	string	선택	대복종
sub_category	string	선택	소복종
style_no	string	선택	품번 (STYLE NO)
page	integer	선택	페이지 번호 (기본값: 1)
limit	integer	선택	페이지당 건수 (기본값: 100)

응답 예시

{
  "success": true,
  "data": {
    "total": 8009,
    "page": 1,
    "limit": 100,
    "items": [
      {
        "style_no": "9N62S2S03",
        "product_name": "산수화 자수 셔츠",
        "brand_code": "HR",
        "brand_name": "헤지스",
        "season": "2026",
        "color": "OTMU",
        "color_name": "오트밀",
        "size": "140",
        "main_category": "상의",
        "sub_category": "셔츠",
        "supplier": "로제스",
        "production_type": "완사입",
        "retail_price": 100000,
        "image_url": "https://...",
        "created_at": "2026-03-04T10:00:00Z",
        "updated_at": "2026-03-04T10:00:00Z"
      }
    ]
  }
}

5.2 상품 상세 조회

GET /api/v1/products/{style_no}

특정 품번의 상세 정보를 조회합니다. 컬러별, 사이즈별 SKU 정보를 포함합니다.

응답 예시

{
  "success": true,
  "data": {
    "style_no": "9N62S2S03",
    "product_name": "산수화 자수 셔츠",
    "brand_code": "HR",
    "brand_name": "헤지스",
    "season": "2026",
    "colors": [
      {
        "color_code": "OTMU",
        "color_name": "오트밀",
        "sizes": [
          {"size": "140", "sku": "9N62S2S03-OTMU-140"},
          {"size": "150", "sku": "9N62S2S03-OTMU-150"}
        ]
      }
    ],
    "main_category": "상의",
    "sub_category": "셔츠",
    "supplier": "로제스",
    "production_type": "완사입",
    "retail_price": 100000,
    "attributes": {
      "fabric": "면 100%",
      "origin": "중국"
    }
  }
}

5.3 상품 등록3단계

POST /api/v1/products

신규 상품을 등록합니다.

요청 본문

{
  "style_no": "9N62S2S03",
  "product_name": "산수화 자수 셔츠",
  "brand_code": "HR",
  "season": "2026",
  "main_category": "상의",
  "sub_category": "셔츠",
  "supplier": "로제스",
  "production_type": "완사입",
  "retail_price": 100000,
  "variants": [
    {
      "color_code": "OTMU",
      "color_name": "오트밀",
      "size": "140",
      "sku": "9N62S2S03-OTMU-140"
    }
  ]
}

5.4 상품 수정3단계

PUT /api/v1/products/{style_no}

기존 상품 정보를 수정합니다.

5.5 카테고리 목록 조회

GET /api/v1/products/categories

상품 카테고리 목록을 조회합니다. 대복종과 소복종 계층 구조로 제공됩니다.

응답 예시

{
  "success": true,
  "data": {
    "categories": [
      {
        "main_category": "상의",
        "sub_categories": [
          {"code": "SHIRT", "name": "셔츠"},
          {"code": "TSHIRT", "name": "티셔츠"},
          {"code": "KNIT", "name": "니트"}
        ]
      },
      {
        "main_category": "하의",
        "sub_categories": [
          {"code": "PANTS", "name": "팬츠"},
          {"code": "JEANS", "name": "청바지"}
        ]
      },
      {
        "main_category": "아우터",
        "sub_categories": [
          {"code": "JACKET", "name": "재킷"},
          {"code": "COAT", "name": "코트"}
        ]
      }
    ]
  }
}

6. 원가(Cost) API

참고: 원가 정보는 상품 마스터와 별도 테이블로 관리되며, 상품 품번(style_no)을 기준으로 연결됩니다.

6.1 사전원가 조회

GET /api/v1/costs/pre/{style_no}

상품의 사전원가 정보를 조회합니다.

응답 예시

{
  "success": true,
  "data": {
    "style_no": "9N62S2S03",
    "cost_type": "pre",
    "raw_material": 15000,
    "sub_material": 3000,
    "processing": 8000,
    "label_sticker": 500,
    "tag": 300,
    "labor": 12000,
    "customs": 2000,
    "logistics": 2200,
    "margin": 57000,
    "total_cost": 43000,
    "retail_price": 100000,
    "margin_rate": 57.0,
    "updated_at": "2026-03-04T10:00:00Z"
  }
}

6.2 사후원가 조회

GET /api/v1/costs/post/{style_no}

상품의 사후원가(실제 발생 원가) 정보를 조회합니다.

응답 예시

{
  "success": true,
  "data": {
    "style_no": "9N62S2S03",
    "cost_type": "post",
    "raw_material": 15500,
    "sub_material": 3200,
    "processing": 8500,
    "label_sticker": 500,
    "tag": 300,
    "labor": 12500,
    "customs": 2100,
    "logistics": 2400,
    "margin": 55000,
    "total_cost": 45000,
    "retail_price": 100000,
    "margin_rate": 55.0,
    "variance": 2000,
    "updated_at": "2026-04-01T10:00:00Z"
  }
}

6.3 원가 등록/수정2단계

POST /api/v1/costs

상품의 원가 정보를 등록하거나 수정합니다.

요청 본문

{
  "style_no": "9N62S2S03",
  "cost_type": "pre",
  "raw_material": 15000,
  "sub_material": 3000,
  "processing": 8000,
  "label_sticker": 500,
  "tag": 300,
  "labor": 12000,
  "customs": 2000,
  "logistics": 2200,
  "note": "2026 SS 시즌 사전원가"
}

원가 항목 설명

항목	설명
raw_material	원자재 비용 (원단 등)
sub_material	부자재 비용 (단추, 지퍼 등)
processing	가공비 (염색, 워싱 등)
label_sticker	라벨/스티커 비용
tag	택/택고리 비용
labor	공임 (봉제비 등)
customs	관세
logistics	물류/경비

6.4 사전/사후 원가 비교

GET /api/v1/costs/compare/{style_no}

사전원가와 사후원가를 비교하여 차이를 분석합니다.

응답 예시

{
  "success": true,
  "data": {
    "style_no": "9N62S2S03",
    "pre_cost": {
      "total": 43000,
      "margin_rate": 57.0
    },
    "post_cost": {
      "total": 45000,
      "margin_rate": 55.0
    },
    "variance": {
      "amount": 2000,
      "percentage": 4.65,
      "items": {
        "raw_material": 500,
        "processing": 500,
        "labor": 500,
        "logistics": 200
      }
    }
  }
}

7. 입출고(Inbound/Outbound) API

7.1 입고 내역 조회

GET /api/v1/inbound

일자별 입고 데이터를 조회합니다. 적정 발주 시점 파악에 활용됩니다.

요청 파라미터

파라미터	타입	필수	설명
start_date	date	필수	조회 시작일 (YYYY-MM-DD)
end_date	date	필수	조회 종료일 (YYYY-MM-DD)
brand_code	string	선택	브랜드 코드
style_no	string	선택	품번
store_code	string	선택	매장 코드

응답 예시

{
  "success": true,
  "data": {
    "items": [
      {
        "inbound_no": "IB20260304001",
        "inbound_date": "2026-03-04",
        "style_no": "9N62S2S03",
        "product_name": "산수화 자수 셔츠",
        "color": "OTMU",
        "size": "140",
        "sku": "9N62S2S03-OTMU-140",
        "quantity": 100,
        "store_code": "WH001",
        "store_name": "본사창고",
        "supplier": "로제스",
        "status": "confirmed",
        "created_at": "2026-03-04T09:00:00Z"
      }
    ]
  }
}

7.2 출고 내역 조회

GET /api/v1/outbound

일자별 출고 데이터를 조회합니다. 수요량 동적 파악에 활용됩니다.

요청 파라미터

파라미터	타입	필수	설명
start_date	date	필수	조회 시작일
end_date	date	필수	조회 종료일
brand_code	string	선택	브랜드 코드
style_no	string	선택	품번
channel	string	선택	판매 채널
store_code	string	선택	매장 코드

응답 예시

{
  "success": true,
  "data": {
    "items": [
      {
        "outbound_no": "OB20260304001",
        "outbound_date": "2026-03-04",
        "order_no": "ORD20260304001",
        "style_no": "9N62S2S03",
        "sku": "9N62S2S03-OTMU-140",
        "quantity": 1,
        "channel": "온라인몰",
        "store_code": "WH001",
        "store_name": "본사창고",
        "status": "shipped"
      }
    ]
  }
}

7.3 입고 확정 처리2단계

POST /api/v1/inbound/{inbound_no}/confirm

입고 예정 건을 확정 처리합니다.

요청 본문

{
  "confirmed_quantity": 100,
  "confirmed_by": "홍길동",
  "note": "정상 입고"
}

8. 재고(Inventory) API

8.1 실시간 재고 조회

GET /api/v1/inventory

매장/창고별 실시간 재고를 조회합니다. 결품 방지 및 악성 재고 탐지에 활용됩니다.

요청 파라미터

파라미터	타입	필수	설명
brand_code	string	선택	브랜드 코드
style_no	string	선택	품번
store_code	string	선택	매장 코드
sku	string	선택	SKU

응답 예시

{
  "success": true,
  "data": {
    "items": [
      {
        "sku": "9N62S2S03-OTMU-140",
        "style_no": "9N62S2S03",
        "product_name": "산수화 자수 셔츠",
        "color": "OTMU",
        "size": "140",
        "store_code": "WH001",
        "store_name": "본사창고",
        "available_quantity": 95,
        "allocated_quantity": 5,
        "total_quantity": 100,
        "last_updated": "2026-03-04T15:30:00Z"
      }
    ]
  }
}

8.2 매장별 재고 현황

GET /api/v1/inventory/by-store

매장별 재고 집계 정보를 조회합니다.

응답 예시

{
  "success": true,
  "data": {
    "stores": [
      {
        "store_code": "WH001",
        "store_name": "본사창고",
        "store_type": "창고",
        "total_skus": 1657,
        "total_quantity": 22809,
        "inventory_value": 489680000
      },
      {
        "store_code": "ST001",
        "store_name": "강남점",
        "store_type": "매장",
        "total_skus": 450,
        "total_quantity": 3200,
        "inventory_value": 85000000
      }
    ]
  }
}

8.3 재고 수불부 조회

GET /api/v1/inventory/ledger

재고 수불 이력을 조회합니다. 입고/출고/조정 내역을 시계열로 확인할 수 있습니다.

요청 파라미터

파라미터	타입	필수	설명
start_date	date	필수	조회 시작일
end_date	date	필수	조회 종료일
sku	string	선택	SKU
transaction_type	string	선택	거래 유형 (입고/출고/조정)

응답 예시

{
  "success": true,
  "data": {
    "items": [
      {
        "transaction_date": "2026-03-04",
        "sku": "9N62S2S03-OTMU-140",
        "transaction_type": "입고",
        "quantity": 100,
        "balance_before": 0,
        "balance_after": 100,
        "reference_no": "IB20260304001",
        "store_code": "WH001",
        "store_name": "본사창고"
      },
      {
        "transaction_date": "2026-03-04",
        "sku": "9N62S2S03-OTMU-140",
        "transaction_type": "출고",
        "quantity": -5,
        "balance_before": 100,
        "balance_after": 95,
        "reference_no": "OB20260304001",
        "store_code": "WH001",
        "store_name": "본사창고"
      }
    ]
  }
}

9. 판매(Sales) API

9.1 주문 내역 조회

GET /api/v1/orders

주문 내역을 조회합니다. 채널별 수익성 분석에 활용됩니다.

요청 파라미터

파라미터	타입	필수	설명
start_date	date	필수	조회 시작일
end_date	date	필수	조회 종료일
channel	string	선택	판매 채널
status	string	선택	주문 상태
brand_code	string	선택	브랜드 코드
style_no	string	선택	품번
store_code	string	선택	매장 코드

응답 예시

{
  "success": true,
  "data": {
    "items": [
      {
        "order_no": "ORD20260304001",
        "order_date": "2026-03-04T14:20:00Z",
        "channel": "온라인몰",
        "customer_name": "[고객명]",
        "items": [
          {
            "sku": "9N62S2S03-OTMU-140",
            "product_name": "산수화 자수 셔츠",
            "quantity": 1,
            "unit_price": 100000,
            "discount": 10000,
            "final_price": 90000
          }
        ],
        "total_amount": 90000,
        "status": "confirmed"
      }
    ]
  }
}

9.2 취소/반품 내역 조회

GET /api/v1/returns

취소 및 반품 내역을 조회합니다.

요청 파라미터

파라미터	타입	필수	설명
start_date	date	필수	조회 시작일
end_date	date	필수	조회 종료일
return_type	string	선택	반품 유형 (취소/반품)
brand_code	string	선택	브랜드 코드
style_no	string	선택	품번
store_code	string	선택	매장 코드

응답 예시

{
  "success": true,
  "data": {
    "items": [
      {
        "return_no": "RT20260304001",
        "order_no": "ORD20260304001",
        "return_date": "2026-03-05",
        "return_type": "반품",
        "reason": "사이즈 불만",
        "sku": "9N62S2S03-OTMU-140",
        "quantity": 1,
        "refund_amount": 90000,
        "status": "completed"
      }
    ]
  }
}

9.3 매출 집계 조회

GET /api/v1/sales/summary

일별/월별/채널별 매출 집계를 조회합니다. 마케팅 인사이트 도출에 활용됩니다.

요청 파라미터

파라미터	타입	필수	설명
start_date	date	필수	조회 시작일
end_date	date	필수	조회 종료일
group_by	string	선택	집계 기준 (daily/monthly/channel/brand/store/style)
brand_code	string	선택	브랜드 코드
style_no	string	선택	품번
store_code	string	선택	매장 코드

응답 예시

{
  "success": true,
  "data": {
    "summary": [
      {
        "date": "2026-03-04",
        "brand_code": "HR",
        "brand_name": "헤지스",
        "channel": "온라인몰",
        "store_code": "ST001",
        "store_name": "강남점",
        "order_count": 150,
        "total_quantity": 200,
        "gross_sales": 15000000,
        "discount": 1500000,
        "net_sales": 13500000,
        "return_count": 5,
        "return_amount": 500000,
        "cancel_count": 3,
        "cancel_amount": 300000
      }
    ]
  }
}

10. Webhook 이벤트

Webhook이란?
세원 시스템에서 특정 이벤트 발생 시, 차일디 서버로 실시간 알림을 전송하는 방식입니다. 주기적인 폴링 없이 즉각적인 데이터 동기화가 가능합니다.

10.1 재고 변동 알림

POST {차일디_webhook_url}/inventory-changed

재고 수량이 변경될 때마다 차일디 서버로 알림을 전송합니다.

Payload 예시

{
  "event": "inventory.changed",
  "timestamp": "2026-03-04T15:30:00Z",
  "data": {
    "sku": "9N62S2S03-OTMU-140",
    "store_code": "WH001",
    "store_name": "본사창고",
    "previous_quantity": 100,
    "current_quantity": 95,
    "change_type": "출고",
    "reference_no": "OB20260304001"
  }
}

10.2 주문 생성 알림

POST {차일디_webhook_url}/order-created

신규 주문이 생성될 때 알림을 전송합니다.

Payload 예시

{
  "event": "order.created",
  "timestamp": "2026-03-04T14:20:00Z",
  "data": {
    "order_no": "ORD20260304001",
    "channel": "온라인몰",
    "total_amount": 90000,
    "items": [
      {
        "sku": "9N62S2S03-OTMU-140",
        "quantity": 1
      }
    ]
  }
}

10.3 입고 완료 알림

POST {차일디_webhook_url}/inbound-completed

입고가 완료될 때 알림을 전송합니다.

Payload 예시

{
  "event": "inbound.completed",
  "timestamp": "2026-03-04T09:30:00Z",
  "data": {
    "inbound_no": "IB20260304001",
    "style_no": "9N62S2S03",
    "total_quantity": 100,
    "store_code": "WH001",
    "store_name": "본사창고"
  }
}

11. 세원측 제공 필요 자료

협의 필요 사항
원활한 API 개발을 위해 세원측에서 아래 자료 제공이 필요합니다.

우선순위 높음

1. 핵심 테이블 샘플 데이터 (5~10건)

상품 마스터 테이블
원가 정보 테이블 (사전/사후)
재고 수불부 테이블
입출고 테이블
주문/판매 테이블

참고: 정식 문서가 아니어도 괜찮습니다. 주요 테이블의 샘플 데이터가 포함된 엑셀 파일만 주시면 저희가 구조를 역으로 파악하겠습니다.

2. 기존 연동 사례

카페24, 무신사 등 타 시스템 연동 API 프로토콜
표준 API 문서 (있는 경우)

우선순위 중간

1. 테이블 구조 정보

ERD 또는 테이블 정의서 (간략 버전)
주요 필드 설명 및 데이터 타입

참고: 전체 공유가 어렵다면 기본 구조 및 데이터 형태에 대한 가이드라도 제공받길 희망합니다.

2. 코드 정보

브랜드 코드 목록 (예: HR, LF 등)
매장 코드 목록 (창고 및 매장 구분 포함)
상태 코드 정의 (주문, 입고, 출고 등)
채널 코드 목록 (온라인몰, 오프라인 등)
대복종/소복종 코드 목록

기술 검토 사항

항목	설명
Webhook 지원	실시간 이벤트 알림 기능 지원 가능 여부
API Rate Limit	API 호출 제한 정책 (분당/시간당 요청 수)
개발 환경	개발/스테이징 환경 제공 여부
보안 정책	IP 화이트리스트, SSL 인증서 등