WMS 개방형 API: 피해야 할 5가지 통합 함정

결론부터 말하자면, WMS와 사내 시스템(ERP, OMS, 재무)의 통합이 터질 때, 그 이유는 거의 WMS 개방형 API가 어려워서가 아니다. 터지는 이유는 팀이 "API 호출이 된다"를 "통합이 끝났다"로 착각하기 때문이다. 하나의 엔드포인트는 반나절이면 되지만, 프로덕션급 통합은 최소 2주가 걸린다. 그 차이가 아래의 다섯 가지 함정이며, 내가 본 통합 실패의 대부분은 이것 때문이다. 각 함정: 증상 → 근본 원인 → 해결책 → 체크리스트. 체크리스트는 고라이브 전날 체크리스트에 복사해 두자.

함정 1: 마스터 데이터 매핑 없음 — 쓰레기 주문이 들어온다

증상: ERP에서 WMS로 판매 주문을 보내면, WMS가 대부분을 "품목을 찾을 수 없음"으로 거부한다. 더 나쁜 경우 — 품목은 존재하지만 잘못된 품목이라 잘못된 제품이 출고된다. 재고 동기화도 깨진다. WMS의 가용 수량이 ERP 장부와 영원히 맞지 않는다.

근본 원인: 두 시스템이 마스터 데이터를 공유한 적이 없었다. ERP의 품목 코드는 10년 전에 공급사 접두사를 박아 넣어 정의했고, WMS는 새로운 내부 SKU를 쓴다. 로케이션, 운송사, 고객 — 모든 코드 테이블이 두 개씩 존재한다. API는 필드를 옮길 뿐, 의미가 맞는지 절대 확인하지 않는다.

나는 이 실패를 세 번 봤다. 최악은 2024년 11월 피크를 앞두고 고라이브한 캘리포니아 자동차 부품 3PL이었다. ERP는 공급사 바코드로 품목을 키잉하고, WMS는 내부 SKU로 키잉했다. 첫 주에 전체 주문 다운로드의 거의 3분의 1이 예외 큐에서 죽었다 — 피커들은 태스크를 보지 못하고, 슈퍼바이저들은 "출고됨"을 보고 있었다. 해결책은 화려하지 않았다. 하룻밤 만에 만든 매핑 테이블, 다운로드 전 검증, 수작업 예외 풀, 백로그가 해소될 때까지의 다운로드 동결. 피크 첫 주 나흘 내내 불 끄기였다.

해결책:

네 가지 코드 세트 — 품목, 로케이션, 운송사, 고객 — 의 매핑 테이블을 만들고, IT가 아니라 사업 오너의 승인을 받는다.
모든 송출 인터페이스를 사전 검증한다. 매핑 테이블에 없는 코드는 거부하고 로그에 남긴다 — "보내고 나중에 처리"는 절대 안 된다.
신규/비활성 코드를 양 시스템 간에 매일 대사하고, 차이는 데이터 오너에게 이메일로 보낸다. 예외 풀에는 오너와 SLA(예: 4시간)를 둔다. 쓰레기통이 아니다.

체크리스트: 매핑 승인 완료, 사전 검증 가동 중, 대사 테스트 완료, 예외 오너 지정 완료.

함정 2: API를 실시간 파이프로 취급 — 피크 첫날 속도 제한에 걸림

증상: 평상주에는 잘 된다. 그런데 프로모션이나 월말이 오면 WMS API 호출이 대거 타임아웃되기 시작하고, 주문 다운로드 지연이 수초에서 수십 분으로 늘어나고, 벤더의 속도 제한기가 통합 전체를 차갑게 멈출 수 있다.

근본 원인: 지름길 — 사내 시스템이 WMS API를 직접 폴링하거나 실시간으로 푸시한다. 몇 초마다 재고 확인, 주문당 한 번의 호출. 모든 개방형 API에는 호출 빈도 상한이 있다(계약 전에 서면으로 받아둬라). 적은 볼륨은 절대 건드리지 않지만, 피크 볼륨은 정면으로 부딪힌다. 백오프 없는 재시도는 이미 과부하인 엔드포인트를 더 두드린다.

해결책:

통합 계층과 WMS 사이에 메시지 큐를 둔다. 사내 시스템은 메시지를 던져 넣고, 컨슈머가 지속 가능한 속도로 WMS를 호출한다. 피크는 백로그를 만들 뿐, 깨지지 않는다 — 느린 것이 죽은 것보다 낫다.
재고와 주문 상태는 폴링보다 WMS 푸시 콜백을 우선한다. 폴링이 꼭 필요하면 5분과 5초는 운영상 거의 차이가 없다 — 부하는 한 자릿수가 다르다.
모든 호출에 멱등성 키 — 같은 트랜잭션을 두 번 푸시해도 실행은 한 번. 재시도는 백오프하고, 세 번 실패하면 메시지는 데드레터 큐로 간다.

체크리스트: 큐 배포 완료, 속도 제한 서면 확보, 멱등성 엔드투엔드, 재시도 상한 설정.

시스템 통합 데이터 흐름름

함정 3: 해피 패스만 코딩 — 타임아웃이 주문을 조용히 떨어뜨림

증상: 가장 지독한 함정. 호출이 타임아웃된다. 사내 시스템은 실패로 판단하고 재전송한다 — 하지만 WMS는 이미 받았고, 잃어버린 것은 응답뿐이었다. 같은 주문이 두 번 다운로드되고 두 번 피킹된다. 또는 100건 배치를 보내면 97건이 처리되고, 인터페이스는 전체 성공을 보고하고, 세 건의 주문이 대사일까지 사라진다.

근본 원인: 개발이 정상 흐름만 테스트했다. 타임아웃의 의미 — 성공인가 실패인가 — 를 아무도 정의하지 않았다. 배치가 부분 성공했을 때 누가 각 라인의 상태를 파싱하는가. 쓴 적도 없고, 테스트한 적도 없다. 고라이브 전 모두가 묻는 건 "연결되나"다. "깨지면 어떻게 되나"를 묻는 사람은 없다.

해결책:

타임아웃 의미를 인터페이스별로 정의하고 문서화한다. 읽기는 안전하게 재시도할 수 있다. 쓰기는 타임아웃 후 재전송 전에 상태를 확인한다. 맹목 재전송은 절대 안 된다.
배치 응답을 라인별로 파싱한다 — 모든 문서의 결과를 로그에 남긴다. 전체 "성공"이 각 라인의 성공을 의미하지 않는다.
일일 대사(우리 시스템 상태 대 WMS)를 돌리고 자동 불일치 알림을 켜다. 중요 인터페이스는 장애 상황에서 리허설한다 — 케이블 뽑기, 프로세스 킬, 타임아웃 시뮬레이션 — 시스템이 스스로 복구함을 증명하기 위해.

체크리스트: 타임아웃 의미 문서화 완료, 배치 라인별 파싱, 대사 가동 중, 장애 훈련 완료.

함정 4: 보안은 나중에 붙이기 — 하나의 키가 모든 것을 지배

증상: 고라이브 일주일 전에 누군가가 인증을 떠올린다. 키 하나를 생성해 통합 프로그램 설정에 하드코딩하고, ERP도 OMS도 재무도 공유한다. 6개월 후 만든 개발자가 퇴사하고, 키는 그와 함께 떠나고, 아무도 로테이션을 감히 하지 못한다.

근본 원인: 보안이 기능보다 뒤다. "일단 돌아가게 하자." 키 문제는 고라이브까지 미뤤졌다 — 그 이후에는 건드리기 너무 무섭다.

해결책:

호출자별 키 분리 — ERP, OMS, 재무 각각 전용 키. 한 시스템에 문제가 생겨도 그 키만 폐기하면 나머지는 건드리지 않는다.
키별 최소 권한: 읽기 전용 재고 키로는 주문을 다운로드할 수 없다. 모든 키는 시크릿 매니저에 둔고, 평문에는 절대 두지 않는다.
주기적으로 로테이션한다(예: 6개월). 첫 로테이션은 고라이브 한 달 후에 돌린다. 아직 모두가 절차를 기억할 때.

체크리스트: 키 분리 완료, 최소 권한, 시크릿 매니저, 로테이션 훈련 완료.

함정 5: 샌드박스에서 되니까 출시 — 그날 밤 프로덕션 폭발

증상: 샌드박스에서는 200건 주문이 날아다닌다. 고라이브 밤에는 2,000건 주문이 통합 프로그램을 짓눌렀다. 또는 샌드박스 WMS가 프로덕션보다 한 마이너 릴리스 뒤처져 있고, 한 필드 동작이 달라 프로덕션이 밤새 배치 에러를 뱑는다.

근본 원인: 샌드박스와 프로덕션은 다른 세상이다. 데이터 볼륨 10배, 훨씬 더러운 데이터, 다른 네트워크. 샌드박스에서만 테스트하는 것은 운전학원 연습장에서 연습하고 바로 고속도로로 합류하는 것과 같다.

해결책:

고라이브 전에 피크의 1.5배로 부하 테스트한다 — 스트레스 테스트 대상은 WMS가 아니라 우리 코드와 큐다. 우리의 병목을 먼저 찾아라.
마스킹한 프로덕션 데이터로 샌드박스에서 전체 회귀 테스트를 리플레이한다. 더러운 데이터를 찾는다. 누락 코드, 특수 문자, 너무 긴 필드 — 항상 상상보다 나쁘다.
샌드박스/프로덕션 버전 일치를 확인하고 벤더의 변경 노트를 받는다. 롤백을 리허설한다. 통합이 죽으면 한 번의 액션으로 수동으로 되돌릴 수 있는가, 백필은 어떻게 하는가. 모두가 두 답을 외우고 있어야 한다.

체크리스트: 피크 1.5배 부하 테스트, 마스킹 데이터 회귀 완료, 버전 일치 확인, 롤백 훈련 완료.

직관에 반하는 견해

API 문서가 가장 충실하고 엔드포인트가 가장 많은 WMS가 통합에서 가장 아프다.

뒤집어 들리지만 30개가 넘는 프로젝트에서 성립한다. 문서가 충실한 벤더는 세분화된 엔드포인트를 공개한다 — 하나의 "주문 다운로드"가 다섯 개나 여섯 개의 인터페이스로 쪼개져 있고 각각 선택적 필드가 있다. 구현자는 "전부"를 통합하고, 표면이 넓을수록 함정이 늘어난다. 모든 필드의 의미를 맞추고, 모든 에러 브랜치를 처리해야 한다. 문서가 얇고 핵심 엔드포인트가 스무 개인 WMS는 생사를 가르는 흐름 — 다운로드, 콜백, 재고 확인 — 으로만 좁히게 만든다. 표면이 작으면 실패할 방법도 적다.

그러니 "200개 이상의 개방형 API"에 눈이 멀지 마라. 세 가지 질문을 던져라. 핵심 흐름에 필요한 최소 엔드포인트는? 속도 제한은 — 계약서에 있는가? 샌드박스-프로덕션 일치는 — 서면으로 있는가? 답이 없으면 엔드포인트 개수는 장식이다. 트레이드오프를 한 문장으로: 통합 깊이와 통합 비용은 항상 함께 스케일한다. 핵심 엔드포인트 다섯 개로 해결되면, 쉴 개를 "제대로" 통합하지 마라. 통합 표면은 지속적인 유지보수이지 턴키 납품이 아니다.