WMS-TARAS 연동 표준화와 도입 가이드 설계

왜 중요한가

B2B 연동에서 계약 구조가 불명확하면, 구현보다 해석 비용과 재작업 비용이 더 크게 늘어나기 때문이다.

B2B 연동을 API 문서 수준에 머물지 않고, 실패 모델·field-level error·운영 가이드까지 포함한 구현 가능한 제품 계약으로 재설계한 사례이다.

배경

이 사례는 단순 API 문서화가 아니라, 고객사 연동 논의를 실행 가능한 계약 구조로 바꾸고 실패 모델까지 재설계한 플랫폼 사례이다. 핵심 근거는 sequence diagram, endpoint, webhook, 피킹 타입 조회·지정 구조, TWMS 요구사항 정리, TARAS 작업지시 API v2 가이드이다. 핵심 설계 포인트는 invalid location, duplicate order, partial failure 같은 예외 흐름과 PickingRound / PickingUnit 상태 전이를 함께 정의한 실패 모델이었다.

문제 정의

핵심 문제는 문서가 부족하다는 것이 아니라, 같은 연동을 팀마다 다르게 이해하고 해석하는 정렬 비용이 크다는 점이었다. B2B 연동은 엔드포인트 설명만으로 충분하지 않고, 호출 순서, 상태 전이, 실패 응답, 복구 방식이 함께 정의돼야 실제 구현이 가능하다. 기존 500 / KeyError 응답은 고객이 무엇을 수정해야 하는지 알기 어렵다는 점에서 계약 품질이 낮았다. 결국 문제의 본질은 API의 존재 여부가 아니라, 고객과 내부 팀이 같은 계약 모델을 공유하지 못했다는 점이었다.

가설

실패 모델과 복구 규칙을 명시한 계약을 설계하면 고객사 구현 과정의 해석 차이와 재작업을 줄일 수 있다.
연동을 endpoint 목록이 아니라 end-to-end 계약 구조로 표현하면 구현 오해를 줄일 수 있다.
실패 응답과 복구 규칙까지 명시하면 고객이 스스로 수정 가능한 self-service 수준이 올라간다.
비개발자도 검증 가능한 운영 자산(예: 차수 생성 가이드)까지 제공하면 도입 장벽이 더 낮아진다.
field-level error와 상태 전이를 함께 정의하면 연동 실패 시에도 고객이 수정 가능한 제품 계약을 만들 수 있다.

실행

sequence diagram, endpoint, webhook, 피킹 타입 조회·지정 구조를 end-to-end 계약 구조로 연결했다.
invalid location, duplicate order, partial failure를 중심으로 실패 모델을 설계했다.
PickingRound는 생성하되 PickingUnit은 FAILED + last_event로 진단 가능한 구조를 핵심 포인트로 설계했다.
기존 500 / KeyError 응답을 400 / field-level error로 바꿔, 고객이 수정 가능한 계약 구조로 전환했다.
TWMS 요구사항 정리를 통해 고객 운영 정책을 상태 전이, 롤백, 검증 구조로 번역했다.
TARAS 작업지시 API v2 가이드를 통해 비개발자도 검증 가능한 운영 자산으로 확장했다.
이 과정의 핵심 목표는 개발팀만 이해하는 API가 아니라, 고객 운영팀도 해석 가능한 제품 계약을 만드는 것이었다.

검증

검증의 핵심 근거는 sequence diagram, endpoint 정의, webhook 흐름, 실패 응답 구조였다.

invalid location, duplicate order, partial failure 시나리오를 설계에 반영해 정상 흐름뿐 아니라 예외 흐름까지 함께 검증했다.
TARAS 작업지시 API v2를 활용한 차수 생성 가이드는 실제 운영 검증 가능성을 높이는 근거였다.
검증의 핵심은 단순히 연동이 되는가가 아니라, 실패했을 때도 고객이 수정 가능한 계약인가를 확인하는 것이었다.
고객이 오해 없이 구현할 수 있는가,
실패 시 무엇을 수정해야 하는지 알 수 있는가,
운영팀도 상태를 해석할 수 있는가