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