CASE STUDY
한눈에 보는 변화
SOAP를 REST 요청으로 바꾸는 개발 자체보다 어려웠던 부분은 법인마다 다른 배송 계정, 인증정보 관리 주체와 ETD 운영 정책을 하나의 전환 계획으로 묶는 일이었습니다. 첫 운영 반영에서 일부 계정의 인증 문제가 드러났을 때는 새 코드에서 장시간 진단하지 않고 기존 업무를 먼저 복구한 뒤 실패 경계를 다시 좁혔습니다.
외부 배송사의 SOAP 서비스 종료가 예고되어 REST 전환이 필요했습니다. 법인별 계정과 인증 준비 상태가 달랐고, ETD 적용 범위도 현업 운영 방식에 따라 달랐습니다. 기술 전환과 동시에 운송장 발급 중단을 막을 롤백 경로가 필요했습니다.
직접 담당한 범위
- API 문서와 기존 SOAP 요청을 비교해 필드·Validation 차이 분석
- 법인별 요구사항 협의, Gap Analysis, 개발·테스트·운영 반영
- 인증·계정·외부 Sandbox 문제를 애플리케이션 문제와 분리해 검증
| 구분 | 변경 전 | 변경 후 | 확인된 변화 |
|---|---|---|---|
| API 방식 | FedEx SOAP 요청·응답과 기존 운송장 생성 흐름 | OAuth 기반 REST JSON 요청·응답과 오류 검증 | SOAP 종료 기한 내 3개 운영 범위 전환 |
| 인증정보 선택 | 하나의 Production 인증정보로 여러 배송 계정을 처리할 수 있다는 전제 | 배송 계정 → 인증정보 관계로 본사·현지 관리 범위를 분리 선택 | 계정 관리 주체와 인증 경계 명시 |
| 통관서류 처리 | Commercial Invoice를 별도 출력·처리 | 대상 법인은 문서 업로드 결과로 운송장을 생성하는 ETD 흐름 적용 | 본사·칠레 ETD, 유럽 REST만 적용 |
| 실패 대응 | 운영 계정 관계가 배포 조건에서 완전히 검증되지 않음 | 백업 WAR 복구 기준과 법인별 인증·운송장·ETD 테스트 매트릭스 운영 | 업무 복구와 원인 분석 경로 분리 |
EVIDENCE CHAIN
문제를 좁힌 과정
- 01 · 문서와 기존 코드 분석
배송·통관 흐름을 필드 변환보다 먼저 구조화했습니다
REST 전용 SDK 없이 FedEx 문서와 기존 SOAP 요청을 대조해 필수 필드, Validation, OAuth 인증과 운송장 응답 차이를 정리했습니다. ETD는 문서 업로드와 운송장 생성이 연속되는 별도 업무 흐름으로 분리했습니다.
판단REST 전환, 인증정보 선택, ETD 적용 여부를 서로 다른 설계 책임으로 나눴습니다.
- 02 · Sandbox 검증
테스트 성공이 Production 계정 연결을 보장하지 않는다는 경계가 남았습니다
Sandbox에서 토큰 발급, 운송장 생성과 ETD 요청을 검증했지만 실제 배송 계정의 활성화와 운영 인증정보 연결은 별도 관리 영역이었습니다.
판단운영 배포 조건에는 코드 테스트뿐 아니라 법인별 운영 인증정보·배송 계정 관계 확인이 필요했습니다.
- 03 · 2026.04.23 운영 반영
같은 코드 경로에서 일부 계정만 인증 실패했습니다
REST 소스를 반영한 뒤 특정 관리 범위의 배송 계정에서 인증 문제가 발생했습니다. 운송장 발급 중단 시간을 늘리지 않기 위해 배포 전에 확보한 백업 WAR로 즉시 SOAP 버전을 복구했습니다.
판단원인 분석보다 업무 연속성을 먼저 확보하고, REST 실패 로그를 운영 업무와 분리해 점검했습니다.
- 04 · 원인 분리
Payload 전체가 아니라 실패 계정의 인증 관계를 좁혔습니다
일부 계정은 동일한 요청 코드로 정상 동작하고 실패가 특정 배송 계정에 한정된 점을 비교했습니다. 인증 단계와 운송장 요청 단계의 외부 응답을 분리한 결과 운영 인증정보와 배송 계정의 매핑 누락을 확인했습니다.
판단코드 결함, 인증정보 선택, 외부 계정 활성화를 각각 다른 원인 후보로 검증해야 했습니다.
- 05 · 재설계와 재배포
법인명이 아니라 실제 외부 계약인 계정 관계를 설정으로 표현했습니다
본사 관리 범위와 현지 관리 범위를 분리하고 배송 계정을 기준으로 알맞은 인증정보를 선택하도록 구성했습니다. ETD도 전 법인 일괄 적용 대신 운영 방침에 따라 본사·칠레와 유럽을 분리했고, 2026.05.20 칠레지사 운영 환경의 정상 동작을 확인했습니다.
판단법인별 계정·인증·ETD 흐름을 재검증한 뒤 SOAP 종료 기한 안에 전환을 완료했습니다.
DECISION LOG
검토한 대안과 선택 근거
하나의 운영 인증정보로 모든 계정 처리
배송 계정마다 관리 주체와 외부 활성화 상태가 달라 하나의 인증정보가 모든 계정 관계를 보장하지 않았습니다.
운영 환경에서 REST 상태로 원인 분석 지속
운송장 생성은 출고와 직접 연결되고 외부 계정 설정은 애플리케이션에서 즉시 해결할 수 없어 업무 중단 비용이 커집니다.
REST와 ETD를 모든 법인에 일괄 적용
REST는 종료 대응 범위로 적용하되 ETD는 각 법인의 통관서류 운영 정책을 기준으로 별도 결정했습니다.
배송 계정 기반 인증정보 매핑
법인명 조건문보다 실제 FedEx 계약 단위인 배송 계정과 인증정보의 관계를 명시적으로 관리할 수 있습니다.
IMPLEMENTATION
설계와 구현
REST 요청·응답
- SOAP 필드와 REST JSON 요청·응답 및 Validation 차이 매핑
- REST SDK 없이 요청 모델, 외부 오류 응답과 검증 로직 구성
- 서비스 타입과 국가 조건에 따라 달라지는 운송장 결과 처리
OAuth·계정 매핑
- OAuth Token Cache와 동시 요청 시 토큰 재사용 구조 구현
- 배송 계정 → 운영 인증정보 선택 관계를 설정으로 분리
- 테스트·운영 및 본사·현지 관리 인증정보 경계 분리
ETD 처리
- 상업송장 업로드 → 문서 식별 결과 수신 → 운송장 생성 흐름 구현
- ETD 적용 법인과 미적용 법인의 요청 경로 분리
- ETD 처리 실패 시 수동 Commercial Invoice 출력 절차를 운영 예외로 유지
배포·복구
- 운영 반영 전 정상 SOAP 버전의 백업 WAR 확보
- 1차 반영 실패 시 즉시 이전 버전으로 복구하고 운송장 발급 정상 여부 확인
- 계정 설정 보완 후 법인별 매트릭스로 재검증하고 단계 재배포
VERIFICATION
테스트 매트릭스
| 검증 영역 | 검증 방법 | 완료 기준 |
|---|---|---|
| OAuth 인증 | 법인별 운영 배송 계정으로 토큰 발급과 인증정보 선택 결과 확인 | 배송 계정에 매핑된 인증정보가 선택되고 인증 성공 |
| 운송장 생성 | 법인·서비스 타입별 요청과 외부 응답·Label 결과 비교 | 기존 업무에 필요한 운송장 생성과 결과 처리 유지 |
| ETD 적용 법인 | 문서 업로드, 식별 결과 수신, 운송장 생성까지 연속 검증 | 본사·칠레지사의 전자 통관서류 흐름 정상 처리 |
| ETD 미적용 법인 | ETD 필드 없이 REST 운송장 생성과 기존 서류 절차 확인 | 유럽법인은 REST만 적용하고 현행 통관서류 운영 유지 |
| 복구 가능성 | 백업 WAR 반영 후 기존 SOAP 운송장 발급 확인 | 외부 계정 문제 발생 시 출고 업무를 이전 정상 상태로 복구 |
OPERATION
운영 반영과 후속 안정화
일부 운영 계정 인증 실패
- 분리한 원인
- 동일 코드 경로의 성공 계정과 비교해 운영 인증정보 매핑 누락 확인
- 대응
- 본사·현지 관리 범위 분리 및 배송 계정 기반 선택 구조 적용
ETD 정책의 법인별 차이
- 분리한 원인
- 기술 가능 여부와 실제 통관서류 운영 방식이 일치하지 않음
- 대응
- 본사·칠레는 ETD, 유럽은 REST API만 적용
외부 설정 변경 전 업무 중단
- 분리한 원인
- 계정 발급·활성화는 애플리케이션 밖의 관리 절차가 필요
- 대응
- 백업 WAR로 SOAP를 복구한 뒤 설정 완료 후 재배포
유럽 독립 실행 환경 인증 설정
- 분리한 원인
- 공통 코드와 별개로 실행 환경별 인증정보 선택·설정 범위를 재확인
- 대응
- 2026.06 유럽 NGS 환경의 인증 설정 후속 안정화 완료
- SOAP 종료 기한 전에 본사·칠레지사·유럽법인의 REST 전환 완료
- 본사·칠레지사에는 ETD를 적용하고 유럽법인은 REST API만 적용
- 단계적 롤백과 재배포로 운송장 발급 중단 방지
- 2026.06 유럽 독립 실행 환경의 FedEx 인증 설정 후속 안정화 완료
TAKEAWAYS
이 사례에서 드러난 역량
- Sandbox 성공과 운영 배송 계정의 활성화·인증정보 연결은 별도의 검증 항목입니다.
- 외부 API 장애에서는 코드, 인증정보 선택, 외부 계정 설정과 운영 정책을 같은 원인으로 묶지 않아야 합니다.
- 롤백은 실패를 감추는 수단이 아니라 업무 기준선을 복원하고 원인 비교를 가능하게 하는 운영 장치입니다.
- 신규 도메인은 문서 분석 → 업무 가설 → 현업 확인 → 기술 검증의 순서로 빠르게 구조화할 수 있습니다.