방문택배 서비스 API·Batch 설계·구축

개요

GS Postbox 방문택배 서비스의 백엔드 API와 배치 시스템을 처음부터 설계·구축했습니다. 고객이 방문 접수·배송 조회·취소·반품까지 사용하는 전체 흐름을 담당했습니다.

• 회사: GS리테일 / 물류DX팀
• 기간: 2024.03 – 2024.10
• 역할: API·Batch 개발, 대한통운 연동 설계, 세션→JWT 마이그레이션 연동
• 스택: Java, Python, Spring Boot 3, Spring Batch 5, MWAA(Airflow), Datadog

배경

방문택배는 GS리테일에서 신규로 론칭하는 서비스였습니다. 내부 접수 상태와 대한통운의 실제 배송 상태를 주기적으로 동기화하는 배치가 필요했고, 취소·반품 처리도 외부 물류사 상태를 기준으로 정확히 수행해야 했습니다. 또한 기존 세션 클러스터링 기반의 택배홈페이지와의 연동도 풀어야 할 과제였습니다.

서비스 기능

주요 기여

1. 전체 서비스 흐름 설계

[고객 방문 접수 API]
    │
    ▼
[내부 DB 저장]
    │ @TransactionalEventListener(AFTER_COMMIT)
    ▼
[알림톡 발송]

[MWAA(Airflow) 배치 — 주기 실행]
    ├── 대한통운 운송장 상태 조회 → 내부 상태 동기화 → 대한통운 수신 확인 API 호출
    ├── 취소·반품 대상 추출 → 내부 처리 → 외부 물류사 요청
    └── 알림톡 발송 결과 처리

2. 대한통운 운송장 조회 배치 + 수신 확인 API

고객 접수 이후 대한통운의 실제 배송 상태를 주기적으로 가져와 내부 DB에 동기화하는 배치를 개발했습니다.

여기에 더해, 커밋 완료 후 대한통운에 상태 수신 완료를 알리는 확인 API를 호출하는 흐름을 추가해 안정성을 높였습니다.

[배치 실행]
    │
    ▼
1. 대한통운 운송장 조회 API 호출 → 최신 상태 수신
    │
    ▼
2. 내부 DB 상태 업데이트 + 커밋
    │
    ▼
3. 대한통운 수신 확인 API 호출 (Acknowledgment)
    └── 대한통운이 "전달 완료"를 인지 → 중복 전송 방지

• 커밋 전에 확인 API를 호출하면 DB 실패 시 대한통운과 내부 상태가 어긋날 수 있으므로, 반드시 커밋 이후 호출하도록 순서를 보장했습니다.
• 네트워크 오류 등으로 확인 API 호출이 실패해도 다음 배치 주기에 재시도되므로 데이터 유실이 없습니다.

3. 취소·반품 배치 처리

배송 상태를 조회한 결과에서 취소·반품 대상을 추출해 내부 상태를 갱신하고 외부 물류사에 처리를 요청하는 배치를 개발했습니다.

[대한통운 상태 조회]
    │
    ▼
[취소·반품 대상 필터링]
    ├── 접수 취소: 수거 전 취소 요청 건 → 내부 상태 CANCELLED 업데이트
    └── 반품: 배송 완료 후 반품 요청 건 → 내부 상태 RETURN_REQUESTED 업데이트
                                            └── 대한통운 반품 수거 요청 API 호출

• 상태 전이 조건을 명확히 정의해, 동일한 건이 중복 처리되지 않도록 멱등성을 보장했습니다.
• 처리 결과는 Datadog으로 수집해 취소·반품 건수 이상 여부를 모니터링할 수 있도록 했습니다.

4. 트랜잭션 이벤트 기반 알림톡 발송

알림톡이 DB 반영 전에 발송되는 문제를 방지하고자 @TransactionalEventListener(AFTER_COMMIT)을 적용했습니다.

@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void handleDeliveryStatusChanged(DeliveryStatusChangedEvent event) {
    kakaoNotificationService.send(event.getCustomerId(), event.getStatus());
}

• DB 커밋 완료 이후에만 알림톡 발송 이벤트가 실행되므로, 상태와 알림의 정합성이 보장됩니다.

5. 택배홈페이지 JWT 연동 — 세션 클러스터링 제거 기반 마련

기존 택배홈페이지는 세션 클러스터링 방식으로 운영되고 있었습니다. 세션 클러스터링은 서버 증설 시 세션 동기화 비용이 발생하고, 클러스터 장애가 인증 전체에 영향을 줍니다.

이를 개선하고자, 기존 세션 인증을 유지하면서 JWT 통신을 병행할 수 있도록 택배홈페이지에 JWT 연동을 추가했습니다.

[기존 택배홈페이지]              [방문택배 Backend]
세션 클러스터링 기반             JWT 기반

세션 인증 (기존 유지)  ────────▶ 세션에서 JWT 발급
                                  │
JWT 병행 통신 ─────────────────▶ JWT 기반 API 호출

• 홈페이지의 기존 세션 인증 흐름을 건드리지 않고, JWT를 추가로 발급해 방문택배 API와 통신하도록 연동했습니다.
• 이 연동을 기반으로 이후 세션 클러스터링을 JWT로 완전 대체하는 마이그레이션 방안을 추진할 수 있는 기반을 만들었습니다.
• Stateless JWT가 자리잡으면 세션 클러스터 인프라를 제거해 운영 복잡도와 비용을 낮출 수 있습니다.

6. Datadog 모니터링 및 배치 자원 튜닝

• 운송장 상태별 로그를 Datadog으로 수집해 누락·이상 구간을 운송장 단위로 추적 가능하게 구성
• MWAA(Airflow) DAG 의존 관계 재정의 및 executor/concurrency 조정으로 배치 실행 지연 개선

운영 지표 (Datadog APM 기준, 2025년 2월~3월 1주일 평균)

결과

• 오픈 당일 일 1,000건 이상 접수 정상 처리, 현재 일 최대 120만 건 요청 안정 처리 중
• P95 레이턴시 30ms 이하, 500 에러율 0.1% 미만으로 안정 운영 유지
• 대한통운 수신 확인 API 연동으로 상태 동기화 안정성 확보
• 취소·반품 배치 자동화로 수동 처리 제거
• 택배홈페이지 JWT 연동 완료 — 세션 클러스터링 제거 마이그레이션 기반 구축

회고

배치에서 외부 API와 연동할 때 가장 신경 쓴 부분은 “커밋과 외부 호출의 순서” 였습니다. 대한통운 수신 확인 API를 커밋 이전에 호출하면 실패 시 데이터가 불일치하고, 커밋 이후에 호출하면 안전합니다. 이처럼 외부 시스템과의 연동에서 순서 보장은 정합성의 핵심이었습니다.

세션 클러스터링에 JWT를 병행 연동한 것은 “Big Bang 전환”이 아닌 점진적 마이그레이션 전략이었습니다. 서비스를 중단하지 않고 레거시 인프라를 교체할 수 있는 방향을 열어두는 것이 중요하다는 것을 이 작업에서 배웠습니다.