바닷길 관리자 테스트 연동 · 모의 응답

택배사 API 연동

연동 설정 및 오류 대응

API 사용 신청부터 운영 전환까지의 진행 상태와 연동 설정, 오류별 조치 방법을 한곳에서 관리합니다.

연동 진행 단계

  1. 1

    택배사 계약 및 고객코드 확인 담당 영업점

    계약 고객코드, 기존 발번 운송장번호 대역, 집하 영업점 정보를 확인합니다.

  2. 2

    API 사용 신청 영업 담당자 경유

    영업 담당자의 승인을 거쳐 API 포털 이용 안내를 받습니다.

  3. 3

    테스트 환경 연결 개발

    테스트 키로 주소 정제·분류코드 응답을 받아 정상·실패 사례를 확인합니다.

  4. 4

    운영 반영 요청 택배사 검토

    테스트 결과를 제출하고 운영 키 발급과 접속 서버 등록을 요청합니다.

  5. 5

    운영 전환 및 샘플 비교 관리자·개발

    택배사 시스템 출력 샘플과 분류코드·인쇄 위치를 비교한 뒤 전환합니다.

연동 설정

시연값
연동 환경

운영 환경은 4단계(운영 반영 요청)가 끝난 뒤 선택됩니다.

운송장번호 사용 방식

    오류 대응표

    연동 설정·오류 대응 문서의 일부

    E01 상세주소 누락 의심

    원인 공동주택 주소에 동·호수가 없습니다.

    조치 주문 메모와 주문자 연락으로 동·호수를 확인해 입력한 뒤 다시 정제합니다.

    E02 기본주소 인식 실패

    원인 한자·영문 표기나 오탈자가 섞여 도로명 주소를 찾지 못했습니다.

    조치 주소 검색 결과에서 도로명 주소를 골라 바꾼 뒤 다시 정제합니다.

    E03 우편번호 불일치

    원인 우편번호와 기본주소의 지역이 다릅니다.

    조치 기본주소 기준 우편번호로 바꾼 뒤 다시 정제합니다.

    E04 분류코드 미수신

    원인 주소 정제는 완료됐으나 응답에 분류코드가 없습니다. 도서·산간 지역이거나 배송 불가 지역일 수 있습니다.

    조치 다시 요청하고, 계속 없으면 담당 영업점에 확인한 분류코드를 수기 입력하거나 출고를 보류합니다.

    E05 인증 실패

    원인 연동 키가 만료됐거나 고객코드가 일치하지 않습니다.

    조치 연동 설정에서 키를 갱신합니다. 갱신 전까지 정제 요청은 대기열에 보관됩니다.

    E06 응답 시간 초과

    원인 택배사 서버 응답이 지연됐습니다.

    조치 3회까지 자동으로 다시 요청하고, 그래도 실패하면 실패 건 목록으로 옮깁니다.

    공고 요구사항 ↔ 시연 화면

    공고 대응표

    1. 우편번호·기본주소·상세주소 전송, 정제 결과 수신 주소 정제
    2. 동·호수 등 상세주소 누락 방지 주소 정제 · 상세주소 보존 표시
    3. 송장 인쇄용 분류코드(예: XC37-0) 수신 주소 정제 · 분류코드
    4. 주소 모호·분류코드 미수신 시 사유 표시, 수정 후 재처리 실패 건 처리
    5. 분류코드를 기존 송장 양식 지정 위치에 표시 송장 출력
    6. 택배사 샘플과 분류코드·인쇄 형식 비교 송장 출력 · 샘플 겹쳐 보기
    7. API 사용 신청·발급 지원, 연동 설정·오류 대응 문서 연동 설정

    이번 지원을 위해 만든 시연 화면입니다. 택배사 응답은 모두 모의 응답이며, 실제 응답 항목과 분류코드 형식은 API 문서와 출력 샘플을 받은 뒤 확정합니다.

    시연용 화면입니다. 표시된 이름과 숫자는 모두 예시 데이터입니다.