재고 이동 API

창고 간 재고 이동을 추적하고 기록합니다. 모든 재고 변동은 이동으로 기록됩니다.

엔드포인트
GET

/stock-movements

stock_movements:read

페이지네이션된 재고 이동 목록을 조회합니다. 제품, 창고, 유형, 날짜 범위 필터를 지원합니다.

POST

/stock-movements

stock_movements:write

새 재고 이동을 기록합니다. 재고 수량이 자동으로 업데이트됩니다.

필드 참조
필드유형필수설명

id

string

아니오

고유 재고 이동 식별자 (읽기 전용)

productId

string

예

제품 식별자

productSku

string

아니오

제품 SKU (읽기 전용)

productName

string

아니오

제품 이름 (읽기 전용)

warehouseId

string

예

창고 식별자

warehouseName

string

아니오

창고 이름 (읽기 전용)

variantId

string

아니오

제품 변형 식별자 (해당 시)

quantity

integer

예

이동 수량 (양의 정수)

movementType

string

예

IN, OUT, ADJUSTMENT, TRANSFER_OUT 또는 TRANSFER_IN

reference

string

아니오

참조 번호 (예: 구매 주문서)

unitCost

integer

아니오

단가 (센트 단위)

batchNumber

string

아니오

배치 번호

notes

string

아니오

추가 메모

createdAt

datetime

아니오

ISO 8601 타임스탬프 (읽기 전용)

쿼리 매개변수 (목록)
필드유형필수설명

page

integer

아니오

페이지 번호 (기본값: 1)

limit

integer

아니오

페이지당 항목 수 (기본값: 20, 최대: 100)

productId

string

아니오

제품 ID로 필터

warehouseId

string

아니오

창고 ID로 필터

movementType

string

아니오

유형으로 필터: IN, OUT, ADJUSTMENT, TRANSFER_OUT, TRANSFER_IN

from

string

아니오

시작 날짜 필터 (ISO 8601)

to

string

아니오

종료 날짜 필터 (ISO 8601)

예시
재고 이동 목록 조회
bash
curl "https://api.mercozy.com/api/v1/external/stock-movements?page=1&limit=20&movementType=IN" \
  -H "X-API-Key: mk_live_xxxxx"
재고 이동 생성
bash
curl -X POST "https://api.mercozy.com/api/v1/external/stock-movements" \
  -H "X-API-Key: mk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "product-uuid",
    "warehouseId": "warehouse-uuid",
    "quantity": 100,
    "movementType": "IN",
    "reference": "PO-2024-001",
    "notes": "Initial stock"
  }'
응답 예시
json
{
  "data": {
    "id": "sm_abc123",
    "productId": "product-uuid",
    "productSku": "WDG-001",
    "productName": "Premium Widget",
    "warehouseId": "warehouse-uuid",
    "warehouseName": "Main Warehouse",
    "variantId": null,
    "quantity": 100,
    "movementType": "IN",
    "reference": "PO-2024-001",
    "unitCost": null,
    "batchNumber": null,
    "notes": "Initial stock",
    "createdAt": "2025-12-15T10:30:00Z"
  }
}