외부 API 전환을 코드 교체로만 볼 수 없었던 이유
기존 운송장 생성 기능은 FedEx SOAP API를 사용하고 있었다. 서비스 종료 기한이 정해지면서 REST API로 전환해야 했고, 요청·응답 모델과 OAuth 인증뿐 아니라 ETD 전자 통관서류 처리까지 함께 검토했다.
문제는 하나의 애플리케이션이 여러 법인의 배송 업무를 처리한다는 점이었다. 본사, 칠레지사, 유럽법인 등은 사용하는 배송 계정이 달랐고 인증정보를 발급하고 관리하는 주체도 같지 않았다. REST 요청 코드가 정상이어도 운영 API Key에 해당 배송 계정이 연결되지 않으면 운송장을 생성할 수 없었다.
따라서 전환 범위를 다음 세 층으로 분리해 확인했다.
- 애플리케이션: SOAP 필드를 REST JSON 요청과 응답 검증으로 변환하는 코드
- 외부 계정: Production API Key와 실제 배송 계정 사이의 연결 및 활성화
- 운영 정책: 법인별 ETD 사용 여부와 예외 처리 방식
Sandbox에서 확인되지 않았던 Production 계정 관계
Sandbox에서는 REST 인증과 운송장 생성 흐름을 검증할 수 있었다. 그러나 테스트 성공은 운영 API Key에 실제 배송 계정이 연결돼 있다는 사실까지 보장하지 않았다. Sandbox용 계정과 Production 배송 계정은 활성화 상태와 관리 주체가 달랐기 때문이다.
개발 단계에서는 요청 필드, 인증 토큰 발급, 정상·실패 응답 처리를 확인했다. 운영 반영 전에는 법인별 Production Key와 배송 계정의 실제 연결 상태도 별도의 배포 조건으로 확인해야 했다. 이 관계가 초기 점검에서 완전히 닫히지 않은 것이 운영 장애로 이어졌다.
초기 운영 반영과 실제 장애
REST 전환 소스를 운영에 반영한 뒤 서로 다른 관리 주체에 속한 일부 배송 계정에서 인증 오류가 발생했다. 동일한 REST 코드가 모든 계정에 공통으로 적용됐지만 특정 계정에서만 실패했다. 운송장 생성은 출고 업무와 직접 연결되므로, 운영 환경에서 원인을 찾는 동안 새 버전을 그대로 유지하기 어려웠다.
이 시점에는 다음 가능성을 구분해야 했다.
- REST 요청 Payload나 Validation이 특정 법인 데이터와 맞지 않는가
- OAuth 인증정보 선택 로직이 잘못됐는가
- Production Key에 배송 계정이 연결되지 않았는가
- 외부 서비스에서 해당 계정이 아직 활성화되지 않았는가
즉시 롤백을 선택한 판단
원인 분석보다 먼저 배송 업무를 복구했다. 배포 전에 확보한 백업 WAR를 다시 반영해 기존 SOAP 방식으로 되돌렸고, 운송장 생성이 복구되는 것을 확인했다.
이 사례의 롤백 단위는 백업 WAR였다. 법인별 Feature Flag나 운영 중 REST와 SOAP을 실시간 전환하는 기능을 구현한 것은 아니다. 애플리케이션 버전 전체를 이전 WAR로 되돌리는 단순하지만 검증된 복구 경로였다.
새 버전 상태에서 장시간 진단하지 않은 이유는 명확했다. 외부 API의 계정 설정은 애플리케이션만으로 즉시 수정할 수 없고, 배송 업무 중단 시간은 계속 늘어나기 때문이다. 우선 기존 방식으로 업무 연속성을 확보한 뒤 REST 환경을 분리해 점검하는 편이 안전했다.
로그를 통해 코드와 외부 계정 설정을 분리한 과정
롤백 후 REST 실행 로그를 인증 단계와 운송장 요청 단계로 나눠 다시 확인했다. 특정 법인의 Payload만 공통 Validation에서 실패한 것이 아니라, 실패한 배송 계정들이 운영 인증 관계에서 거부되고 있었다.
다른 계정은 같은 코드 경로로 처리되고 실패 범위가 특정 배송 계정에 한정됐다는 점도 근거가 됐다. 요청 JSON이나 REST 전환 코드 전체의 문제보다 API Key와 계정의 연결 상태를 우선 확인했다.
확인 결과 Production Key와 배송 계정 사이의 매핑이 누락돼 있었다.
- 본사 관리 범위의 계정은 기존 운영 인증정보에 필요한 연결을 보완했다.
- 현지 관리 계정은 해당 관리 주체가 별도의 인증정보를 발급하고 운영 사용을 활성화해야 했다.
API Key와 Secret, 실제 배송 계정 번호는 공개 내용에서 제외했다. 중요한 것은 동일한 인증 오류를 코드 결함으로 단정하지 않고, 코드·인증정보 선택·외부 계정 설정을 분리해 확인한 과정이다.
계정과 API Key 매핑 구조 재설계
초기에는 하나의 Production 인증정보로 여러 배송 계정을 처리할 수 있다고 보았지만, 칠레 계정은 현지에서 별도로 관리해야 했다. 이후 본사 관리 Key와 칠레 관리 Key를 분리하고, 운송장 요청에 사용하는 배송 계정 번호를 기준으로 알맞은 인증정보를 선택하도록 매핑 구조를 적용했다.
이 구조에서는 법인 이름을 코드 곳곳에서 조건문으로 비교하기보다 실제 외부 계약의 기준인 배송 계정과 인증정보의 관계를 명시한다. 계정이 추가되거나 관리 주체가 달라질 때도 어떤 Key를 선택해야 하는지 설정 관계로 확인할 수 있다.
ETD 적용 범위를 법인별로 분리한 이유
REST 전환과 ETD 적용은 같은 배포에서 다뤘지만 동일한 의사결정은 아니었다. REST는 SOAP 종료에 대응하기 위해 대상 법인에 필요했지만, ETD는 각 법인의 통관서류 운영 방식에 따라 적용 여부가 달랐다.
본사와 칠레지사는 ETD 흐름을 적용하고, 유럽법인은 ETD를 사용하지 않는 방향으로 확정했다. 기술적으로 호출할 수 있다는 이유만으로 모든 법인에 일괄 적용하지 않고, 실제 서류 처리 정책을 기준으로 범위를 나눴다.
재배포 검증과 운영 결과
계정과 인증정보의 관계를 정리한 뒤 법인별로 다시 검증했다.
- 배송 계정 번호에 따라 의도한 Production 인증정보가 선택되는지 확인
- 토큰 발급과 운송장 생성의 성공·실패 응답을 구분해 확인
- 본사 관리 인증정보에 필요한 계정 연결이 반영됐는지 확인
- 현지 관리 인증정보의 발급·활성화 후 실제 운영 계정으로 재검증
- ETD 적용 법인과 미적용 법인의 요청 흐름을 각각 확인
- 실패 시 기존 배포본으로 복구할 수 있는 백업 WAR 유지
재검증과 운영 반영을 거쳐 SOAP 종료 기한 안에 본사·칠레지사·유럽법인의 REST 전환을 완료했다. ETD는 확정된 법인별 정책에 맞춰 분리 적용했다.
롤백 경로가 원인 분석에도 도움이 된 이유
롤백은 업무만 복구한 것이 아니다. 동일한 운영 계정이 기존 SOAP에서는 정상 동작하고 REST Production 인증에서만 실패한다는 비교 기준을 확보했다. 덕분에 배송 계정 자체의 업무 사용 가능 여부와 REST Key 매핑 문제를 분리할 수 있었다.
외부 API 전환에서 롤백 경로는 실패를 숨기는 장치가 아니다. 외부 설정을 즉시 통제할 수 없는 상황에서 업무 중단 시간을 줄이고, 정상 기준선을 복원해 코드와 외부 환경 중 어디에서 문제가 생겼는지 좁히는 수단이다.