API 설계
유통 시스템 API는 단순 CRUD보다 업무 행위 중심으로 설계하는 편이 안전합니다. 출고확정, 입고확정, 주문취소, 반품검수처럼 하나의 요청이 상태 변경, 재고 수불, 정산, 외부 연동을 함께 일으키는 경우가 많기 때문입니다.
기본 원칙
| 원칙 | 설명 |
|---|---|
| 행위 중심 | PATCH status보다 POST /confirm, POST /cancel처럼 업무 의도를 드러낸다. |
| 상태 검증 | 서버에서 현재 상태와 요청 가능한 다음 상태를 검증한다. |
| 멱등성 | 중복 요청이 들어와도 같은 결과를 반환한다. |
| 이력 저장 | 누가, 언제, 어떤 사유로 처리했는지 남긴다. |
| 연동 분리 | 외부 시스템 전송 실패가 내부 업무 완료를 무조건 되돌리지 않게 한다. |
API 흐름 예시
예시 API
| API | 역할 |
|---|---|
POST /api/orders/{id}/cancel | 주문 취소 |
POST /api/outbounds/{id}/confirm | 출고확정 |
POST /api/inbounds/{id}/confirm | 입고확정 |
POST /api/returns/{id}/inspect | 반품 검수 |
POST /api/interfaces/{id}/retry | 연동 재처리 |
PDA API 기준
PDA API는 네트워크 재시도와 중복 스캔이 빈번합니다. 요청에는 작업 ID, 스캔 대상, 스캔 시각, 기기 ID, 멱등 키를 포함합니다.
{
"taskId": "PICK-1001",
"scanCode": "8801234567890",
"deviceId": "PDA-17",
"scannedAt": "2026-06-16T09:12:30+09:00",
"idempotencyKey": "PICK-1001-8801234567890-001"
}
실무에서 자주 생기는 문제
- 화면에서만 버튼을 막고 API 상태 검증을 하지 않는다.
- 같은 요청이 두 번 들어와 재고가 중복 차감된다.
- 외부 연동 실패를 업무 실패로 처리해 이미 완료된 작업을 되돌린다.
- API 응답에는 성공이라고 나오지만 이력이 남지 않아 운영 추적이 어렵다.