택배 배송조회 API 연동 시 고려사항

API 작성 2026-09-16 · 수정 2026-09-16 · 글쓴이 미션비

배송조회는 '호출'보다 '예외'가 어렵다

배송조회 API 연동 자체는 간단합니다. 택배사 코드와 운송장 번호를 보내면 배송 단계 목록이 돌아옵니다. 운영을 시작하면 문제는 다른 곳에서 나옵니다. 송장이 아직 없는 주문, 운송장 번호에 하이픈이 섞인 입력, 응답이 느린 외부 서비스, 설정이 바뀌어 조용히 끊긴 인증 키 같은 것들입니다.

아래는 미션비가 운영하는 쇼핑몰 툴ON의 배송조회 기능을 다듬으며 정리한 기준입니다.

1. 송장 미발급과 장애를 구분한다

주문 직후에는 운송장 번호가 없는 것이 정상입니다. 이 상태에서 "배송조회를 일시적으로 사용할 수 없습니다"를 띄우면 고객은 장애로 받아들이고 문의가 늘어납니다. 그래서 검사 순서가 중요합니다.

1. 송장·택배사 코드가 있는가 — 없으면 외부 호출 없이 "송장번호 확인 중" 같은 정상 안내를 보여 줍니다.
2. 조회 키(API 키)가 있는가 — 없으면 호출하지 않고 장애 안내 + 운영자용 오류 로그를 남깁니다.
3. 외부 호출 — 실패하면 오류 페이지 대신 화면 안에 안내를 띄웁니다.

실제로 1번과 2번의 순서가 바뀌어 있으면, 키 설정에 문제가 생긴 날 송장이 없는 정상 주문까지 전부 장애 안내가 나갑니다. 정상 상태를 먼저 걸러야 안내가 정확해집니다.

2. 타임아웃은 반드시 지정한다

타임아웃 없이 외부 서비스를 호출하면, 그 서비스가 응답하지 않는 동안 웹 서버의 요청 처리 스레드가 붙잡힙니다. 조회가 몰리면 배송조회와 상관없는 페이지까지 느려집니다. 연결 시간과 응답 대기 시간을 각각 몇 초 단위로 짧게 지정하고, 시간을 넘기면 "잠시 후 다시 조회해 주세요"로 안내합니다.

3. 키와 설정의 위치를 단순하게

API 키를 설정 파일이 아니라 DB 공통코드 같은 곳에 두고, 그 코드의 위치를 다시 설정 파일에서 가리키는 식으로 간접 참조를 여러 번 걸면 공통코드 번호를 정리하는 작업 하나로 조회가 조용히 끊길 수 있습니다. 조회 실패는 사용자가 알려 주기 전까지 눈에 띄지 않습니다.

• 키는 한 곳(환경변수나 운영 설정)에 두고, 코드에 적지 않습니다.
• 키가 비어 있거나 조회가 연속으로 실패하면 운영자가 볼 수 있는 로그·알림을 남깁니다.
• 외부 연동 로그는 업무 로그와 분리해 두면 원인 추적이 빨라집니다.

4. 운송장은 주문이 아니라 박스에 붙는다

합포장이나 분할출고가 있으면 주문과 운송장은 1:1이 아닙니다. 운송장을 주문 테이블의 컬럼 하나로 두면 두 번째 박스의 운송장을 저장할 곳이 없습니다. 배송 건(박스) 단위로 택배사·운송장·상태를 두고, 고객 화면에서는 주문에 연결된 여러 운송장을 함께 보여 줍니다.

5. 입력 정규화와 코드 변환

• 운송장 번호 — 하이픈·공백을 제거한 숫자만 저장하고 조회합니다. 엑셀로 일괄 등록할 때 앞자리 0이 사라지지 않게 문자열로 다룹니다.
• 택배사 코드 — 조회 서비스, 오픈마켓, 송장 출력 프로그램마다 코드 체계가 다릅니다. 내부 코드를 하나 정하고 서비스별 변환표를 둡니다.
• 배송 상태 — 외부 서비스의 단계명을 그대로 쓰지 말고 내부 상태(집하·이동 중·배송 출발·배송 완료 등)로 변환해 저장합니다. 변환표에 없는 값은 버리지 말고 '미분류'로 남깁니다.

주의사항

• 조회 서비스는 호출 한도와 이용 조건이 있습니다. 주문 목록 전체를 주기적으로 조회하기 전에 한도를 확인하고, 배송 완료된 건은 조회 대상에서 뺍니다.
• 조회 결과에는 수령인 관련 정보가 포함될 수 있으므로 필요한 항목만 화면에 보여 주고 로그에 남기지 않습니다.
• 택배사 사정으로 단계 정보가 늦게 갱신되는 경우가 있어, 고객 안내에 조회 시각을 함께 표시하는 편이 문의를 줄입니다.

정리

배송조회 연동의 품질은 성공했을 때가 아니라 실패했을 때 드러납니다. 정상 상태와 장애를 구분하는 검사 순서, 짧은 타임아웃, 한 곳에 둔 키, 박스 단위 운송장, 내부 기준의 코드·상태 변환. 이 다섯 가지를 갖추면 외부 서비스가 흔들려도 쇼핑몰은 흔들리지 않습니다.