sam-docs/dev/guides/item-master-items-api.md

품목기준관리(ItemMaster) & 품목관리(Items) API 문서

프론트엔드 개발자를 위한 API 스펙 문서 작성일: 2025-12-10

목차

1. 개요
2. 품목관리 (Items) API
3. 품목기준관리 (ItemMaster) API
4. 공통 응답 형식
5. 에러 처리

---

개요

품목관리 (Items) vs 품목기준관리 (ItemMaster)

구분	품목관리 (Items)	품목기준관리 (ItemMaster)
역할	실제 품목 데이터 CRUD	품목 입력 화면/폼 구성 관리
대상 데이터	products, materials 테이블	item_pages, item_sections, item_fields 테이블
사용자	품목 등록/수정하는 일반 사용자	화면 구성을 설정하는 관리자
비유	엑셀 데이터	엑셀 양식(템플릿)

품목 유형 코드 (item_type / product_type)

코드	설명	저장 테이블
FG	완제품 (Finished Goods)	products
PT	반제품/부품 (Part)	products
SM	반자재 (Semi-Material)	materials
RM	원자재 (Raw Material)	materials
CS	소모품 (Consumables)	materials

---

품목관리 (Items) API

실제 품목 데이터를 조회/생성/수정/삭제하는 API입니다.

1. 통합 품목 목록 조회

역할: products와 materials를 통합하여 조회 (UNION 방식)

GET /api/v1/items

Request Parameters (Query)

파라미터	타입	필수	설명
type	string	N	품목 유형 필터 (쉼표 구분). 기본값: FG,PT,SM,RM,CS
search 또는 q	string	N	검색어 (코드, 이름, 태그)
category_id	integer	N	카테고리 ID 필터
size	integer	N	페이지당 항목 수. 기본값: 20
page	integer	N	페이지 번호. 기본값: 1
include_deleted	boolean	N	삭제된 항목 포함 여부. 기본값: false

Request 예시

GET /api/v1/items?type=FG,PT&search=모터&size=10&page=1

Response

{
  "success": true,
  "message": "조회되었습니다.",
  "data": {
    "data": [
      {
        "id": 1,
        "item_type": "FG",
        "code": "P-001",
        "name": "완제품A",
        "specification": null,
        "unit": "EA",
        "category_id": 5,
        "type_code": "FG",
        "created_at": "2025-01-01T00:00:00.000000Z",
        "deleted_at": null,
        "safety_stock": 100,
        "lead_time": 7
      }
    ],
    "current_page": 1,
    "per_page": 20,
    "total": 150,
    "last_page": 8
  }
}

Response 필드 설명

필드	설명
id	품목 고유 ID (테이블별 독립)
item_type	품목 유형 코드
code	품목 코드
name	품목명
specification	규격 (materials만 해당)
unit	단위 (EA, KG, M 등)
category_id	카테고리 ID
type_code	품목 유형 코드 (item_type과 동일)
created_at	생성일시
deleted_at	삭제일시 (Soft Delete)
safety_stock	안전재고 (attributes에서 플랫 전개)
lead_time	리드타임 (attributes에서 플랫 전개)

Note

: attributes JSON 필드는 자동으로 최상위로 플랫 전개되어 반환됩니다.

---

2. 단일 품목 조회 (ID 기반)

역할: 특정 ID의 품목 상세 정보 조회 (가격 정보 옵션)

GET /api/v1/items/{id}

Path Parameters

파라미터	타입	필수	설명
id	integer	Y	품목 ID

Query Parameters

파라미터	타입	필수	설명
item_type	string	N	품목 유형 코드. 기본값: FG
include_price	boolean	N	가격 정보 포함 여부. 기본값: false
client_id	integer	N	고객 ID (가격 조회 시)
price_date	string	N	가격 기준일 (YYYY-MM-DD)

Request 예시

GET /api/v1/items/123?item_type=SM&include_price=true&client_id=5

Response

{
  "success": true,
  "message": "조회되었습니다.",
  "data": {
    "id": 123,
    "item_type": "SM",
    "code": "M-001",
    "name": "반자재A",
    "specification": "10mm x 20mm",
    "unit": "EA",
    "category_id": 10,
    "category": {
      "id": 10,
      "name": "철강류"
    },
    "type_code": "SM",
    "prices": {
      "sale": {
        "unit_price": 15000,
        "currency": "KRW",
        "effective_from": "2025-01-01"
      },
      "purchase": {
        "unit_price": 10000,
        "currency": "KRW",
        "effective_from": "2025-01-01"
      }
    }
  }
}

---

3. 단일 품목 조회 (코드 기반)

역할: 품목 코드로 상세 정보 조회 (Product → Material 순서로 검색)

GET /api/v1/items/code/{code}

Path Parameters

파라미터	타입	필수	설명
code	string	Y	품목 코드

Query Parameters

파라미터	타입	필수	설명
include_bom	boolean	N	BOM 정보 포함 여부. 기본값: false

Request 예시

GET /api/v1/items/code/P-001?include_bom=true

---

4. 품목 생성

역할: 새 품목 등록 (product_type에 따라 products 또는 materials에 저장)

POST /api/v1/items

Request Body

필드	타입	필수	설명
code	string	Y	품목 코드 (최대 50자, 중복 시 자동 증가)
name	string	Y	품목명 (최대 255자)
product_type	string	Y	품목 유형: FG, PT, SM, RM, CS
unit	string	Y	단위 (최대 20자)
category_id	integer	N	카테고리 ID
description	string	N	설명
is_sellable	boolean	N	판매 가능 여부. 기본값: true
is_purchasable	boolean	N	구매 가능 여부. 기본값: false
is_producible	boolean	N	생산 가능 여부. 기본값: false
safety_stock	integer	N	안전재고 (0 이상)
lead_time	integer	N	리드타임 (0 이상)
is_variable_size	boolean	N	가변 사이즈 여부
product_category	string	N	제품 분류 (최대 20자)
part_type	string	N	부품 유형 (최대 20자)
attributes	object	N	동적 필드 (JSON)
material_code	string	N	자재 코드 (Material 전용)
item_name	string	N	품명 (Material 전용)
specification	string	N	규격 (Material 전용)
is_inspection	string	N	검수 여부: Y, N
search_tag	string	N	검색 태그
remarks	string	N	비고
options	object	N	옵션 (JSON)

Request 예시

{
  "code": "P-NEW-001",
  "name": "신규 완제품",
  "product_type": "FG",
  "unit": "EA",
  "category_id": 5,
  "is_sellable": true,
  "safety_stock": 50,
  "attributes": {
    "color": "red",
    "size": "L"
  }
}

Response

{
  "success": true,
  "message": "품목이 생성되었습니다.",
  "data": {
    "id": 999,
    "code": "P-NEW-001",
    "name": "신규 완제품",
    "product_type": "FG",
    "unit": "EA",
    "category_id": 5,
    "is_active": true,
    "is_sellable": true,
    "is_purchasable": false,
    "is_producible": false,
    "created_by": 1,
    "created_at": "2025-12-10T10:00:00.000000Z"
  }
}

중복 코드 처리: 코드가 이미 존재하면 자동으로 증가합니다.

• P-001 중복 → P-002
• ABC 중복 → ABC-001

---

5. 품목 수정

역할: 기존 품목 정보 수정

PUT /api/v1/items/{id}

Path Parameters

파라미터	타입	필수	설명
id	integer	Y	품목 ID

Request Body

필드	타입	필수	설명
item_type	string	Y	품목 유형 (테이블 분기용)
code	string	N	품목 코드
name	string	N	품목명
...			(생성과 동일한 필드, 모두 선택)

Request 예시

{
  "item_type": "FG",
  "name": "수정된 완제품명",
  "safety_stock": 100
}

Response

{
  "success": true,
  "message": "품목이 수정되었습니다.",
  "data": {
    "id": 999,
    "code": "P-NEW-001",
    "name": "수정된 완제품명",
    "safety_stock": 100,
    "updated_by": 1,
    "updated_at": "2025-12-10T11:00:00.000000Z"
  }
}

---

6. 품목 삭제 (Soft Delete)

역할: 품목 삭제 (BOM 구성품으로 사용 중이면 삭제 불가)

DELETE /api/v1/items/{id}

Path Parameters

파라미터	타입	필수	설명
id	integer	Y	품목 ID

Query Parameters

파라미터	타입	필수	설명
item_type	string	N	품목 유형. 기본값: FG

Response

{
  "success": true,
  "message": "품목이 삭제되었습니다.",
  "data": "success"
}

에러 Response (BOM 사용 중)

{
  "success": false,
  "message": "해당 품목은 3건의 BOM에서 구성품으로 사용 중입니다."
}

---

7. 품목 일괄 삭제

역할: 여러 품목 일괄 삭제

DELETE /api/v1/items/batch

Request Body

필드	타입	필수	설명
item_type	string	Y	품목 유형
ids	array	Y	삭제할 품목 ID 배열

Request 예시

{
  "item_type": "FG",
  "ids": [1, 2, 3, 4, 5]
}

---

품목기준관리 (ItemMaster) API

품목 입력 화면의 구성(페이지, 섹션, 필드)을 관리하는 API입니다.

구조 개요

ItemMaster 계층 구조:

Page (페이지)
├── Section (섹션) - fields 타입
│   ├── Field (필드)
│   ├── Field (필드)
│   └── Field (필드)
└── Section (섹션) - bom 타입
    ├── BomItem (BOM 항목)
    └── BomItem (BOM 항목)

• Page: 품목 유형별 입력 화면 (예: 완제품 등록 페이지)
• Section: 페이지 내 영역 구분 (예: 기본정보, BOM 구성)
• Field: 입력 필드 정의 (예: 품목코드, 품목명)
• BomItem: BOM 섹션의 구성품 정의

1. 초기화 데이터 로드

역할: 프론트엔드 앱 초기화 시 필요한 전체 ItemMaster 데이터 로드

GET /api/v1/item-master/init

Response

{
  "success": true,
  "message": "조회되었습니다.",
  "data": {
    "pages": [
      {
        "id": 1,
        "tenant_id": 1,
        "group_id": null,
        "page_name": "완제품 등록",
        "item_type": "FG",
        "absolute_path": "/items/fg/create",
        "is_active": true,
        "sections": [
          {
            "id": 10,
            "title": "기본정보",
            "type": "fields",
            "order_no": 1,
            "is_locked": false,
            "fields": [
              {
                "id": 100,
                "field_name": "품목코드",
                "field_key": "code",
                "field_type": "textbox",
                "is_required": true,
                "order_no": 1,
                "is_locked": true
              }
            ]
          }
        ]
      }
    ],
    "sections": [...],
    "fields": [...],
    "customTabs": [...],
    "unitOptions": [...]
  }
}

Response 필드 설명

필드	설명
pages	페이지 목록 (섹션, 필드 중첩 포함)
sections	모든 독립 섹션 목록 (재사용 가능)
fields	모든 독립 필드 목록 (재사용 가능)
customTabs	커스텀 탭 목록 (컬럼 설정 포함)
unitOptions	단위 옵션 목록

---

2. 페이지 API

페이지 목록 조회

GET /api/v1/item-master/pages

Query 파라미터	타입	필수	설명
item_type	string	N	품목 유형 필터

페이지 생성

POST /api/v1/item-master/pages

Request Body	타입	필수	설명
page_name	string	Y	페이지명 (최대 255자)
item_type	string	Y	품목 유형: FG, PT, SM, RM, CS
absolute_path	string	N	절대 경로 (최대 500자)

페이지 수정

PUT /api/v1/item-master/pages/{id}

페이지 삭제

DELETE /api/v1/item-master/pages/{id}

---

3. 섹션 API

독립 섹션 목록 조회

GET /api/v1/item-master/sections

Query 파라미터	타입	필수	설명
is_template	boolean	N	템플릿 섹션 필터

독립 섹션 생성 (페이지 연결 없음)

POST /api/v1/item-master/sections

Request Body	타입	필수	설명
group_id	integer	N	계층 번호
title	string	Y	섹션 제목 (최대 255자)
type	string	Y	섹션 타입: fields, bom

페이지에 섹션 생성 (연결)

POST /api/v1/item-master/pages/{pageId}/sections

섹션 복제

POST /api/v1/item-master/sections/{id}/clone

섹션 사용처 조회

GET /api/v1/item-master/sections/{id}/usage

역할: 해당 섹션이 어떤 페이지에서 사용되고 있는지 조회

섹션 수정

PUT /api/v1/item-master/sections/{id}

섹션 삭제

DELETE /api/v1/item-master/sections/{id}

섹션 순서 변경

PUT /api/v1/item-master/pages/{pageId}/sections/reorder

Request Body	타입	필수	설명
items	array	Y	[{id: 1, order_no: 1}, {id: 2, order_no: 2}]

---

4. 필드 API

독립 필드 목록 조회

GET /api/v1/item-master/fields

독립 필드 생성 (섹션 연결 없음)

POST /api/v1/item-master/fields

Request Body	타입	필수	설명
group_id	integer	N	계층 번호
field_name	string	Y	필드 표시명 (최대 255자)
field_key	string	N	필드 키 (최대 80자, 영문 시작)
field_type	string	Y	필드 타입 (아래 참조)
is_required	boolean	N	필수 입력 여부
default_value	string	N	기본값
placeholder	string	N	플레이스홀더 (최대 255자)
display_condition	object	N	표시 조건 (JSON)
validation_rules	object	N	검증 규칙 (JSON)
options	array	N	드롭다운 옵션 등 (JSON)
properties	object	N	추가 속성 (JSON)
is_locked	boolean	N	잠금 여부

필드 타입 (field_type)

타입	설명
textbox	한 줄 텍스트 입력
number	숫자 입력
dropdown	드롭다운 선택
checkbox	체크박스
date	날짜 선택
textarea	여러 줄 텍스트 입력

섹션에 필드 생성 (연결)

POST /api/v1/item-master/sections/{sectionId}/fields

필드 복제

POST /api/v1/item-master/fields/{id}/clone

필드 사용처 조회

GET /api/v1/item-master/fields/{id}/usage

역할: 해당 필드가 어떤 섹션에서 사용되고 있는지 조회

필드 수정

PUT /api/v1/item-master/fields/{id}

필드 삭제

DELETE /api/v1/item-master/fields/{id}

---

공통 응답 형식

모든 API는 동일한 응답 구조를 따릅니다.

성공 응답

{
  "success": true,
  "message": "처리되었습니다.",
  "data": { ... }
}

페이지네이션 응답

{
  "success": true,
  "message": "조회되었습니다.",
  "data": {
    "data": [...],
    "current_page": 1,
    "per_page": 20,
    "total": 100,
    "last_page": 5,
    "from": 1,
    "to": 20
  }
}

---

에러 처리

에러 응답 형식

{
  "success": false,
  "message": "에러 메시지",
  "errors": {
    "field_name": ["검증 오류 메시지"]
  }
}

주요 HTTP 상태 코드

코드	설명
200	성공
201	생성 성공
400	잘못된 요청 (검증 실패, 중복 코드 등)
401	인증 필요
403	권한 없음
404	리소스 없음
422	검증 실패 (Validation Error)
500	서버 오류

주요 에러 케이스

상황	메시지 예시
품목 없음	"해당 품목을 찾을 수 없습니다."
코드 중복	"이미 사용 중인 품목코드입니다."
BOM 사용 중	"해당 품목은 N건의 BOM에서 구성품으로 사용 중입니다."
필수 필드 누락	"품목코드는 필수입니다."
잘못된 품목 유형	"품목 유형은 FG, PT, SM, RM, CS 중 하나여야 합니다."

---

인증

모든 API는 다음 인증이 필요합니다:

1. API Key: X-API-KEY 헤더
2. Bearer Token: Authorization: Bearer {token} 헤더

GET /api/v1/items
X-API-KEY: your-api-key
Authorization: Bearer your-access-token

---

변경 이력

날짜	버전	변경 내용
2025-12-10	1.0	최초 작성