해외 배송을 다루는 서비스라면 어느 시점엔가 같은 문제에 부딪힙니다. 고객은 한글로 주소를 넣는데, 물류사에 넘길 라벨은 영문이어야 합니다. 담당자가 매번 손으로 옮기는 방식은 주문이 늘면 무너집니다. 이 글은 변환 기능을 시스템에 붙일 때 어디서 부르고, 무엇을 저장하고, 실패하면 어떻게 할지를 정리합니다. 특정 언어 코드보다 설계 판단에 초점을 둡니다.
먼저 정할 것 — 호출 시점
가장 큰 갈림길입니다. 변환을 언제 실행하느냐에 따라 나머지 설계가 전부 달라집니다.
| 시점 | 장점 | 단점 |
|---|---|---|
| 주소 입력 시점 | 고객이 즉시 확인·수정 가능 | 입력할 때마다 호출, 미완성 주소도 호출됨 |
| 주문 확정 시점 | 호출 횟수가 주문 수와 같아 예측 가능 | 오류 발견 시 고객이 이미 떠남 |
| 라벨 출력 시점 | 정말 필요할 때만 호출 | 출고 직전에 오류가 터짐 |
실무에서는 입력 시점 + 주문 확정 시점 이중 구조가 무난합니다. 입력할 때 보여줘서 고객이 직접 확인하게 하고, 주문 확정 때 한 번 더 변환해 그 값을 저장합니다. 고객이 본 것과 실제 출고되는 것이 같아야 클레임이 줄어듭니다.
무엇을 저장할 것인가
변환 결과를 저장하지 않고 매번 다시 부르는 설계는 위험합니다. 주소 데이터는 갱신되기 때문에, 몇 달 뒤 같은 주소를 다시 변환하면 결과가 달라질 수 있습니다. 그러면 주문 당시 라벨과 재출력 라벨이 달라집니다.
저장할 항목은 최소 네 개입니다.
- 원본 한글 주소 — 모든 문제의 기준점입니다. 절대 덮어쓰지 않습니다.
- 변환된 영문주소 — 실제 출고에 쓰인 값입니다.
- 우편번호 — 별도 필드로 둡니다. 주소 문자열 안에만 있으면 나중에 뽑아내기 번거롭습니다.
- 변환 시각 — 언제 기준의 결과인지 알아야 문제 추적이 됩니다.
상세주소는 분리해서 다룬다
한국 주소에서 도로명 부분은 공식 표기가 있지만 동·호수는 자유 입력입니다. 이 둘을 한 문자열로 합쳐 저장하면 해외 쇼핑몰이나 물류사의 Address Line 1 / Line 2 구조에 맞출 수 없습니다.
line2: Apt 101-1502
postal_code: 06236
country: South Korea
이 구조로 저장해 두면 물류사마다 다른 양식에 조합만 바꿔 대응할 수 있습니다. 어떤 곳은 line2를 요구하고, 어떤 곳은 한 줄로 합쳐 달라고 합니다. 합쳐진 것을 나누기는 어렵지만 나뉜 것을 합치기는 쉽습니다. 유형별 표기 규칙은 건물 유형별 영문주소 표기를 참고하세요.
실패를 정상 경로로 취급하기
주소 변환은 반드시 일정 비율로 실패합니다. 신축 건물이라 아직 등록되지 않았거나, 고객이 오타를 냈거나, 애초에 주소가 아닌 값이 들어온 경우입니다. 실패를 예외 상황으로 두면 그때마다 주문이 멈춥니다.
- 변환 실패해도 주문은 진행 — 주문을 막지 말고 상태만 표시합니다.
- 실패 건을 한곳에 모읍니다 — 담당자가 하루 한 번 처리할 목록을 만듭니다.
- 수동 입력 경로를 남깁니다 — 담당자가 직접 영문주소를 넣을 수 있어야 합니다.
- 재시도는 즉시 하지 않습니다 — 같은 값으로 바로 다시 불러도 결과는 같습니다.
실패율을 지표로 관리하세요. 평소 2%였는데 갑자기 20%가 됐다면 고객 주소가 이상해진 게 아니라 연동 쪽에 문제가 생긴 것입니다. 이 지표 하나가 장애를 가장 먼저 알려줍니다.
호출을 줄이는 법
같은 주소가 반복해서 들어오는 경우가 많습니다. 재구매 고객, 회사 주소, 배송대행지 주소가 대표적입니다. 정규화한 한글 주소를 키로 결과를 캐시해 두면 호출량이 눈에 띄게 줄어듭니다.
캐시 키를 만들 때는 공백과 대소문자를 정리한 뒤 해시를 씁니다. 다만 영구 캐시는 피하세요. 주소 데이터가 갱신되므로 일정 기간이 지나면 다시 조회하는 편이 안전합니다.
입력 시점에 호출한다면 타이핑할 때마다 부르지 않도록 입력이 멈춘 뒤 잠깐 기다렸다 호출하는 처리가 필요합니다. 이것만 넣어도 호출량이 크게 떨어집니다.
개인정보 관점에서 볼 것
주소는 개인정보입니다. 연동을 설계할 때 기능만 보면 놓치는 부분이 있습니다.
- 변환 요청 로그에 전체 주소를 그대로 남기지 않습니다. 문제 추적용이라면 마스킹하거나 해시로 남깁니다.
- 캐시에 주소를 담는다면 보관 기간을 정하고 지웁니다.
- 외부로 나가는 요청이라면 처리 위탁에 해당하는지 확인이 필요합니다.
- 테스트 환경에 실제 고객 주소를 복사해 두지 않습니다.
세 번째 항목은 서비스 성격에 따라 판단이 달라지므로, 개인정보 처리 방침을 다루는 담당자와 확인하는 편이 안전합니다.
연동 전 점검표
- 원본 한글 주소를 덮어쓰지 않고 별도 보존하는가
- 도로명·상세주소·우편번호를 각각 다른 필드에 담는가
- 변환 실패 시에도 주문 흐름이 멈추지 않는가
- 실패 건을 담당자가 볼 수 있는 곳에 모으는가
- 실패율을 지표로 보고 있는가
- 로그에 전체 주소가 평문으로 남지 않는가
연동 없이 수동으로 처리하는 규모라면 대량 변환기로 충분합니다. 자동화가 필요한 시점의 판단 기준은 월 변환 건수보다 담당자가 손대는 빈도입니다. 하루에 여러 번 손이 간다면 연동을 검토할 때입니다. 자세한 사양은 영문주소 변환 API 문서를 참고하세요.
자주 묻는 질문
입력 시점과 주문 확정 시점 중 언제 부르는 게 좋나요?
둘 다 부르는 이중 구조를 권합니다. 입력할 때 보여줘 고객이 직접 확인하게 하고, 주문 확정 시점에 다시 변환해 그 값을 저장합니다. 고객이 본 주소와 출고되는 주소가 같아야 클레임이 줄어듭니다.
변환 결과를 저장해야 하나요, 매번 조회해야 하나요?
저장해야 합니다. 주소 데이터는 갱신되므로 나중에 다시 변환하면 결과가 달라질 수 있고, 그러면 주문 당시 라벨과 재출력 라벨이 달라집니다. 원본 한글 주소도 함께 보존하세요.
변환에 실패하면 주문을 막아야 하나요?
막지 마세요. 신축 건물이나 오타 때문에 일정 비율은 반드시 실패합니다. 주문은 진행시키고 상태만 표시한 뒤, 실패 건을 한곳에 모아 담당자가 처리하는 구조가 안정적입니다.
캐시는 얼마나 오래 두면 되나요?
영구 보관은 피하세요. 주소 데이터가 갱신되므로 일정 기간이 지나면 다시 조회하는 편이 안전하고, 개인정보 보관 기간 관점에서도 만료 정책이 필요합니다.
연동 없이 수동으로 처리해도 되는 규모는 어느 정도인가요?
건수보다 손대는 빈도가 기준입니다. 하루에 한 번 몰아서 처리하면 대량 변환기로 충분하고, 하루에 여러 번 손이 간다면 연동을 검토할 시점입니다.