결론부터 말하겠다. 가동 시작 이후 API와 EDI 연동 문제 해결은 고장 난 연결을 최대한 빨리 고치는 것이 아니다. 더 악화시키지 않는 것이다. 내가 본 가장 비싼 실수는 원래 장애 때문이 아니었다. 누군가 당황해서 모든 것을 재전송하고, 재고를 손으로 수정하고, 인터페이스를 재시작하면서 추적 가능한 장애를 아무도 맞출 수 없는 엉망으로 만들었기 때문이다. 그러니 무엇이든 건드리기 전에 장애를 분류하라. 메시지가 아예 도착하지 않았는가? 도착했지만 처리되지 않았는가? 처리됐지만 확인이 돌아오지 않았는가? 아니면 세 시스템이 각자 자기 숫자가 맞다고 주장하는가? 분류를 잘못하면 그 이후의 모든 단계도 잘못된다. 나는 이 함정을 세 개의 서로 다른 창고에서, 같은 각본으로 세 번 봤다.

첫 번째 이야기는 지난 가을, 캘리포니아 온타리오 외곽의 가정용품 제3자 물류 창고에서 나왔다. 가동 시작 후 3주째 되는 화요일 아침, 소매업체는 400건이 넘는 주문이 창고에 한 번도 도달하지 않았다고 보고했다. 당직자는 인터페이스가 중단됐다고 생각하고 두 번 재시작했다. 아무것도 바뀌지 않았다. 확인 결과 소매업체는 주문을 보냈고 우리 게이트웨이는 이를 받았지만, 소매업체가 알리지 않고 상품 코드의 접미사를 바꾸는 바람에 주문 검증 단계에서 멈춰 있었다. 고장 난 것은 아무것도 없었다. 양쪽 모두 상대방은 아무것도 바꾸지 않았다고 가정했을 뿐이다. 우리는 옛 코드를 임시로 매핑해 출하를 움직이게 한 뒤, 정식 통지 절차를 통해 코드 변경을 추진했다. 그 이후로 나는 시스템 로그보다 변경 로그를 먼저 확인한다.

두 번째 이야기는 더 고통스럽다. 시카고 인근의 소형 가전 창고는 가동 시작 후 첫 달 동안 재고가 하루에 100단위 이상 어긋났고, 때로는 높게, 때로는 낮게 나타났으며, 일주일 동안 아무도 패턴을 찾지 못했다. 알고 보니 두 가지 문제가 겹쳐 있었다. 소매업체 시스템이 반품 입고를 두 번 보내고 있었고, 우리 쪽에는 멱등성 검사가 없어 같은 반품이 두 번 장부에 올랐다. 거기에 순환 실사 조정이 WMS에 직접 입력되고 소매업체로는 다시 보내지지 않았다. 각자 자기 숫자만 계속 수정했고, 격차는 계속 커졌다. 해결책은 영리하지 않았다. 업무 문서 번호 기준으로 재전송된 모든 메시지를 중복 제거하고, 모든 재고 조정은 누군가 수량을 바꾸고 그냥 떠나도록 내버려 두지 말고 인터페이스를 통해 처리하도록 한 것이다. 그 두 줄은 그 이후로 내 가동 시작 당일 밤 체크리스트에 올라 있다.

API/EDI 장애: 먼저 분류하고, 그다음 행동하라

분류는 네 문장으로 할 수 있으며, 로그 파일을 열기 전에 장애를 그중 하나에 맞춰야 한다. 첫째, 메시지가 아예 도착하지 않았다. 보내지 않았거나, 잘못된 엔드포인트로 보냈거나, 인증서가 만료됐거나, 네트워크가 끊겼다. 둘째, 도착했지만 처리되지 않았다. 검증, 매핑, 누락된 필드에서 멈춰 있다. 셋째, 처리됐지만 확인이 돌아오지 않았다. 업무 문서는 생성됐지만 확인이 돌아가지 않아 발신자는 네가 받지 못했다고 생각하고 다시 보냈다. 넷째, 모두가 의견이 다르다. 주문, 출하, 재고 시스템이 서로 다른 정의를 쓰기 때문에 각자 따로로는 옳아 보인다.

10분의 분류는 어떤 종류의 문제인지도 모른 채 수천 줄의 로그를 뒤지는 4시간을 아낄 수 있다. 그리고 한 가지 규칙: 증거 없이 운영 인터페이스를 재시작하지 마라. 재시작은 전송 중인 메시지의 상태를 지우고, 따라갈 수 있었던 흔적을 더 이상 따라갈 수 없는 흔적으로 만든다.

많은 가동 이후 문제는 선정 당시에 심어졌다. 누가 마스터 데이터를 소유하고 누가 예외를 먼저 감지하는지를 아무도 확정하지 않았을 때다. 그런 결정을 다시 검토하고 있다면, API 대 EDI 선정 비교는 빼먹은 책임을 운영 합의서에 적어 넣는 데 유용한 참고 자료다.

API/EDI 메시지 추적: 논쟁하기 전에 메시지를 찾아라

내 메시지 추적 루틴은 다섯 단계이며, 이 순서대로 작동한다. 1단계, 업무 문서 번호를 들고 발신자 시스템으로 가서 발송 기록을 확인한다. 보냈는가, 어느 엔드포인트로 보냈는가, 어떤 응답 코드가 돌아왔는가? 2단계, 우리 게이트웨이의 수신 기록을 확인하고 원본 메시지가 저장됐는지 확인한다. 3단계, 원본 메시지를 검증한다. 형식 문제인가, 인코딩 문제인가, 아니면 업무 규칙이 막고 있는가? 4단계, 업무 처리 로그를 읽어 정확히 어디에서 멈췄는지, 시스템 오류로 멈췄는지 수동 보류로 멈췄는지 확인한다. 5단계, 확인 기록을 확인한다. 확인이 발송됐는가, 상대방이 이를 수락했는가?

직관에 반하는 부분은 여기다. 성공 응답이 업무 성공을 의미하지는 않는다. 많은 인터페이스는 주문이 생성됐다거나 재고가 올바르게 차감됐다고 말하기 위해서가 아니라 그저 "받았다"고 말하기 위해 200을 반환한다. 나는 두 팀이 이틀 동안 서로에게 200 로그를 흔들며 주문이 미들웨어 큐에 앉아 있는 것을 본 적이 있다. 응답 코드만으로 판단하지 말고 업무 문서 상태로 판단하라. 응답 코드는 전송이 깨지지 않았음을 증명할 뿐이다. 업무가 제대로 이뤄졌음을 증명하지는 않는다.

또 다른 전형적인 실패: 팀은 테스트 환경에서 해피 패스만 테스트하고 재전송, 순서가 바뀐 메시지, 빈 필드는 한 번도 테스트하지 않았다. 그 세 가지는 가동 시작 당일 밤 체크리스트에 별개의 테스트로 들어가야 한다. 재전송은 멱등성을 테스트하고, 순서가 바뀐 메시지는 문서 상태 머신을 테스트하며, 빈 필드는 시스템이 크게 오류를 내는지 문서를 조용히 버리는지를 테스트한다. 조용히 버리는 것이 세 가지 중 최악이다. 오류는 적어도 누군가에게 알리지만, 조용히 버려진 문서는 고객이 불평할 때야 비로소 발견되기 때문이다.

멈춘 주문: 이 체크리스트를 상자마다 처리하라

주문이 멈추면, API와 EDI 연동 문제 해결은 한 가지 규칙에서 시작한다. 그날을 넘기기 위해 주문을 손으로 만들지 마라. 손으로 만든 주문은 오늘의 출하를 해결하고 내일의 맞추기 문제를 보장한다. 중복이든 누락된 주문이든 말이다. 대신 이 체크리스트를 처리하고, 모든 상자에 대해 "보낸 것 같다"가 아니라 로그 항목이나 문서 상태 같은 증거를 요구하라. 문서 번호가 발신자 시스템에 존재하는가? 메시지가 게이트웨이에 도달했는가? 검증을 통과했는가? 상품 코드와 위치 코드가 매핑됐는가? 재고가 충분한가? 문서가 수동 보류 상태에 있는가?

근본 원인을 찾으면, 수리 순서가 중요하다. 먼저 출하를 보호하고, 다음으로 데이터를 고치고, 책임 논쟁은 마지막으로 하라. 매핑 문제라면, 정식 변경이 진행되는 동안 오늘의 출하를 보호하기 위해 임시 매핑을 넣어라. 재고 부족이라면, 주문을 풀기 전에 부족이 실제인지 아니면 오래된 재고 데이터 때문인지 확인하라. 데이터 지연은 맞추기가 필요하고, 실제 부족은 부족 처리 절차가 필요하며, 주문을 억지로 통과시키는 것은 누구에게도 도움이 되지 않는다. 한 건을 고친 뒤에는 나머지 배치도 같은 원인을 공유하는지 확인하라.

수작업 우회책이 확장되지 않는 이유를 계산해 보자. 하루에 400건의 주문이 멈추고, 건마다 수동 확인과 처리에 8분이 걸린다고 가정하자. 그것은 3,200분, 50시간이 넘으며, 두 사람이 야근을 해도 끝내지 못한다. 멈춘 주문이 일정 규모를 넘으면, 올바른 대응은 사람을 늘리는 것이 아니라 연결과 프로세스를 일괄로 고치는 것이다. 사람을 늘리면 시스템 문제가 인력 문제로 바뀌고, 비용만 더 커진다.

재고 불일치: 3단계 맞추기

재고 불일치에 대해서는, API와 EDI 연동 문제 해결이 세 단계로 귀결된다. 1단계, 합계를 맞춘다. WMS 보유 수량, 상대 시스템의 보유 수량, 양쪽이 마지막으로 합의한 수량을 놓고, 격차의 크기와 처음 나타난 날짜를 밝힌다. 2단계, 흐름을 맞춘다. 기준일부터 오늘까지 입고, 출하, 반품, 조정을 네 개의 별개 범주로 비교하고, 누적 격차가 총 격차와 같은 범주를 찾는다. 3단계, 문서를 맞춘다. 격차가 가장 큰 범주를 골라 몇 건의 거래를 표본으로 삼고, 중복, 누락, 정의 차이 여부를 한 건씩 확인한다.

정의 차이는 가장 간과되는 원인이다. 한쪽은 운송 중 재고를 보유 재고로 셀 수 있고, 다른 쪽은 그렇지 않을 수 있다. 누구도 틀리지 않았는데도 숫자가 어긋날 수 있다. 양쪽이 같은 것을 세고 있지 않기 때문이다. 맞추기 전에 보유, 가용, 운송 중이 무엇을 의미하는지 적어두고 양쪽이 합의하게 하라. 합의된 정의가 없으면 맞추기는 각자 옳다고 주장하며 끝난다.

마지막 운영 규칙 하나. 인터페이스는 가동 시작일에 완성되지 않는다. 처음 30일이 가장 위험한 기간으로, 상대방은 알리지 않고 코드를 바꾸거나, 인증서를 교체하거나, 발송 빈도를 바꿀 수 있다. 내 지금의 관행은 첫 달 동안 매주 맞추기를 하고, 만료 2주 전에 인증서를 교체하는 것이다. 인터페이스 운영은 이런 화려하지 않은 루틴을 지키는 것으로 이긴다.

Lin Xiao, WMS 구현 컨설턴트 지음

영어판 번역본입니다. 내용이 다를 경우 영어판을 우선합니다.