홈블로그UPS Tracking API 사용 방법: 단계별 설정 가이드

UPS Tracking API 사용 방법: 단계별 설정 가이드

17TRACK

UPS Tracking API를 사용하려면 UPS Developer 계정을 만들고, 애플리케이션을 등록하고, OAuth 2.0 자격 증명을 발급받고, 액세스 토큰을 요청한 다음, 유효한 UPS 추적 번호를 사용해 인증된 추적 요청을 보내야 합니다. 정확한 포털 레이블, 승인 단계 및 API 요구 사항은 변경될 수 있으므로, 프로덕션 통합을 활성화하기 전에 공식 UPS Developer Portal에서 최신 지침을 확인하세요.

How to Use the Ups Tracking Api Step By Step

이 가이드는 온라인 스토어, 주문 관리 시스템, 창고 워크플로, 고객 서비스 도구 또는 내부 대시보드에서 배송 상태를 확인해야 하는 개발자와 이커머스 운영팀을 위한 것입니다. 통합 순서, 안정성에 영향을 미치는 결정 사항, 일반적인 추적 실패를 방지하는 점검 항목에 중점을 둡니다.

UPS Tracking API의 기능

API 통합을 사용하면 직원이나 고객이 배송업체의 추적 페이지를 직접 열지 않고도 소프트웨어가 UPS에 배송 정보를 요청할 수 있습니다. 애플리케이션은 응답을 사용해 최신 확인 상태를 표시하고, 배송 이벤트를 식별하고, 고객 서비스 조사를 지원하거나, 내부 워크플로를 트리거할 수 있습니다.

API는 추적 페이지와 동일하지 않습니다. 추적 페이지는 사람이 읽도록 설계되었지만, API 응답은 소프트웨어가 파싱하고 저장하고 표시해야 하는 구조화된 데이터입니다. 인증, 오류 처리, 폴링 또는 이벤트 수집, 데이터 보존, 사용자 인터페이스 설계 및 배송 이벤트를 기반으로 구축된 비즈니스 규칙은 계속해서 귀사의 시스템이 담당합니다.

시작하기 전에

개발자 포털을 열기 전에 다음 항목을 준비하세요.

  • UPS Developer 계정 또는 현재 UPS 온보딩 절차에서 요구하는 계정 유형
  • 등록된 애플리케이션과 해당 애플리케이션에 발급된 자격 증명
  • 테스트 추적 번호 또는 승인된 다른 테스트 방법. UPS 문서에서 별도의 테스트 환경이나 테스트 절차를 제공하는 경우 실제 고객 데이터로 시작하지 마세요.
  • 배송 기록, 추적 이벤트 및 고객에게 표시되는 상태 메시지를 어느 시스템이 관리할지에 대한 명확한 결정
  • 클라이언트 자격 증명과 액세스 토큰을 저장할 안전한 장소. 브라우저 코드, 공개 저장소, 스크린샷 또는 사용자가 검사할 수 있는 모바일 애플리케이션에 비밀 정보를 절대 저장하지 마세요.

또한 애플리케이션에 추적 기능만 필요한지, 아니면 더 광범위한 UPS 통합이 필요한지도 결정해야 합니다. 추적, 요금 조회, 배송, 주소 검증 및 문서 서비스에는 서로 다른 제품, 권한, 요청 형식 및 운영 요구 사항이 적용될 수 있습니다.

1단계: UPS Developer Portal 열기

공식 UPS Developer Portal에서 시작하세요. 최신 API 카탈로그, 인증 안내, 온보딩 요구 사항, 약관 및 환경 정보를 검토하세요. 다른 UPS 서비스에 대한 지침도 추적에 적용된다고 가정하지 말고 Tracking API 문서를 찾아보세요.

포털은 현재 요청 필드, 권한 범위, 응답 정의, 요청 한도, 오류 코드 및 환경 세부 정보를 확인하기에 적절한 출처입니다. 이러한 세부 정보는 변경될 수 있으며, 타사 코드 예제는 이전 UPS 인터페이스나 오래된 인증 방식을 사용할 수 있습니다.

2단계: 애플리케이션 등록

개발자 포털에서 애플리케이션을 만들고 애플리케이션에 실제로 필요한 UPS API를 선택하세요. 추적 전용 프로젝트라면 워크플로에 추가 서비스가 필요한 경우가 아니면 추적 기능만 요청하세요. 권한을 제한하면 구성이 단순해지고 이후 문제 해결도 쉬워집니다.

애플리케이션 식별자와 비밀 정보를 서버 측 시크릿 관리자 또는 보호된 환경 변수 시스템에 저장하세요. 비밀 정보는 비밀번호처럼 취급해야 합니다. 노출된 경우 UPS가 제공하는 절차를 통해 이를 교체하고 무단 사용 여부를 로그에서 검토하세요.

포털에서 계정, 결제, 비즈니스 또는 애플리케이션 정보를 요구하는 경우 정확한 정보를 제공하세요. 테스트를 완료하기 위해 프로덕션 사용 사례를 허위로 작성하거나 다른 사람의 계정 정보를 사용하지 마세요. 서비스 액세스는 계정 구성과 현재 UPS 승인 절차에 따라 달라질 수 있습니다.

3단계: OAuth 2.0 인증 구현

현재 UPS 개발자 문서에서는 API에 OAuth 기반 인증을 사용합니다. 일반적으로 서버는 문서에 명시된 토큰 플로를 통해 애플리케이션 자격 증명을 교환하고 액세스 토큰을 받습니다. 그런 다음 API 요청의 인증 헤더에 해당 토큰을 포함합니다.

인증 로직과 추적 로직을 분리하세요. 실용적인 설계에서는 유효한 토큰을 발급받아 캐시하는 구성 요소와 추적 엔드포인트를 호출하는 구성 요소를 별도로 둡니다. 토큰 구성 요소는 다음을 수행해야 합니다.

  • 문서에 명시된 UPS 인증 엔드포인트로만 자격 증명을 전송합니다.
  • 현재 UPS 문서에 지정된 콘텐츠 유형과 grant 매개변수를 사용합니다.
  • 토큰을 임시로 저장하고 만료될 때까지 재사용합니다. 추적 번호마다 새 토큰을 요청하지 마세요.
  • 문서에 명시된 만료 조건이 발생하면 토큰을 갱신하거나 다시 발급받습니다.
  • 애플리케이션 로그, 오류 보고서 및 지원 티켓에서 자격 증명과 토큰을 마스킹합니다.

브라우저 세션에서 토큰을 복사해 영구 통합에 사용하지 마세요. 백엔드 서비스는 비밀 정보를 공개 클라이언트 코드에서 분리할 수 있으므로 일반적으로 자격 증명을 관리하기에 더 안전한 장소입니다.

4단계: 추적 요청 구축

공식 Tracking API 참조 문서에 제시된 요청 형식을 사용하세요. 일반적인 요청에는 경로 또는 요청 매개변수의 추적 번호, 인증 헤더의 액세스 토큰 및 UPS API에 필요한 헤더가 포함됩니다. 추적 번호만 필요하다고 가정하지 마세요. 현재 참조 문서에서 버전, 트랜잭션, 콘텐츠 유형 또는 상관관계 헤더를 지정할 수 있습니다.

단순화된 요청 형식은 다음과 같습니다.

GET [UPS tracking endpoint]/[tracking-number]
Authorization: Bearer [access-token]
Accept: application/json

이는 구조를 보여 주는 예시일 뿐, 그대로 복사해 사용할 수 있는 엔드포인트가 아닙니다. 애플리케이션에 대해 UPS 문서에 게시된 엔드포인트, 버전, 헤더 및 매개변수 이름을 사용하세요. 추적 번호는 자체 주문 데이터 규칙에 따라 정규화하되, 운송업체 문서에서 안전하다고 확인하지 않은 이상 문자를 제거하지 마세요.

5단계: 이벤트를 데이터 모델에 매핑

운송업체 응답에는 단일 상태 레이블보다 많은 정보가 포함되는 경우가 많습니다. 고객에게 표시되는 페이지를 코딩하기 전에 응답을 배송 식별자, 운송업체, 최신 상태, 이벤트 코드, 이벤트 설명, 이벤트 타임스탬프, 위치, 예상 배송 정보 및 가능한 경우 배송 완료 타임스탬프와 같은 내부 모델에 매핑하세요.

보존 및 개인정보 보호 정책이 허용하는 경우 원래 운송업체 응답을 보존하세요. 원시 응답은 매핑 오류를 진단하거나 정규화된 상태가 운송업체의 표현과 다른 이유를 설명하는 데 도움이 됩니다. 동시에 기술적인 이벤트 코드를 읽기 쉬운 설명 없이 고객에게 표시하지 마세요.

모든 상태를 최종 배송 결과로 취급하지 마세요. 예를 들어 운송 중 이벤트, 예외, 배송 시도 및 배송 완료 이벤트를 동일한 고객 메시지로 통합해서는 안 됩니다. 명시적인 매핑을 만들고 UPS가 코드에서 인식하지 못하는 이벤트 값을 추가했을 때 어떻게 처리할지 정의하세요.

6단계: 재시도, 검증 및 모니터링 추가

프로덕션 통합에는 개발 콘솔에서 성공적으로 요청하는 것 이상의 작업이 필요합니다. 검증 및 운영 안전장치를 추가하세요.

  • 입력 검증: 요청을 보내기 전에 비어 있거나 형식이 잘못되었거나 명백히 불완전한 추적 번호를 거부합니다.
  • 타임아웃: 느린 운송업체 응답으로 인해 전체 결제, 지원 또는 창고 워크플로가 차단되지 않도록 합니다.
  • 재시도 규칙: 일시적인 네트워크 또는 서비스 장애는 백오프를 적용해 신중하게 재시도합니다. 인증 오류나 잘못된 추적 번호는 반복해서 재시도하지 마세요.
  • 요청 한도 인지: UPS 문서의 한도와 사용 규칙을 따르세요. 비즈니스 프로세스에서 허용하는 경우 최근 결과를 캐시합니다.
  • 알 수 없는 상태: 인식하지 못한 이벤트를 배송 완료 또는 분실로 잘못 표시하지 말고 검토를 위해 보존합니다.
  • 관측 가능성: 비밀 정보나 불필요한 개인정보를 기록하지 않고 요청 시간, 응답 범주 및 상관관계 정보를 기록합니다.

추적 시스템은 배송을 얼마나 자주 새로 고칠지도 정의해야 합니다. 지나치게 공격적인 폴링은 불필요한 부하를 만들 수 있으며 새로운 정보를 제공하지 않을 수 있습니다. 너무 드물게 폴링하면 고객에게 표시되는 페이지가 오래된 것처럼 보일 수 있습니다. 배송량, 운영상의 긴급성, 운송업체 규칙 및 사용자가 실제로 필요로 하는 최신성을 기준으로 간격을 선택하세요.

7단계: 현실적인 시나리오로 테스트

배송 완료된 배송의 성공 사례만 테스트하지 마세요. 알 수 없는 추적 번호, 운송 중인 배송, 예외, 여러 이벤트가 있는 배송, 만료된 토큰, 타임아웃, 인증 실패 및 파서가 예상하지 못한 필드가 포함된 응답을 테스트에 포함하세요. UPS가 별도의 테스트 환경이나 테스트 자격 증명을 제공한다면 먼저 해당 절차를 따르세요.

요청부터 사용자 인터페이스까지 전체 경로를 점검하세요. 올바른 주문에 올바른 배송이 연결되는지, 타임스탬프가 의도한 시간대로 표시되는지, 중복 이벤트가 중복 고객 메시지를 만들지 않는지, 운송업체 장애로 인해 이전의 유효한 상태가 오해의 소지가 있는 텍스트로 덮어써지지 않는지 확인하세요.

멀티 운송업체 Tracking API가 더 적합한 경우

운영에서 주로 UPS를 사용하고 운송업체 워크플로를 세밀하게 제어해야 한다면 UPS 직접 통합이 적합할 수 있습니다. 주문이 여러 운송업체, 마켓플레이스, 우편 사업자 또는 지역 배송업체를 통해 이동할 수 있다면 직접 통합은 덜 편리해집니다. 이 경우 별도의 자격 증명, 응답 형식, 상태 용어 및 재시도 규칙으로 인해 유지 관리 작업이 증가할 수 있습니다.

17TRACK Tracking API와 같은 멀티 운송업체 서비스는 여러 운송업체에 걸친 추적이 필요한 애플리케이션에 대체 통합 모델을 제공할 수 있습니다. 지원 운송업체, 요청 형식, 인증, 사용 약관 및 제공 기능은 개발자 문서에서 직접 확인해야 합니다. 그렇다고 해서 직접 UPS 연결보다 자동으로 더 나은 것은 아닙니다. 적절한 선택은 운송업체 구성, 데이터 요구 사항, 통합 제어 수준 및 상업적 또는 규정 준수상의 제약에 따라 달라집니다.

개발자 통합이 아닌 소비자용 조회가 목적이라면 API 연결을 구축하는 것보다 17TRACK’s tracking page가 더 적합할 수 있습니다. 브랜드화된 구매 후 업데이트가 필요한 온라인 스토어라면 스토어에 필요하지 않은 API 작업을 추가하기보다는 관련 플랫폼 통합을 별도로 검토하세요.

일반적인 구현 실수

  • 오래된 예제 사용: 코드 샘플이 폐기된 버전, 오래된 인증 방식 또는 다른 UPS 서비스를 참조할 수 있습니다.
  • 프런트엔드 코드에 비밀 정보 저장: 브라우저로 전송되는 모든 항목은 검사될 수 있다고 간주해야 합니다.
  • 빈 결과가 배송되지 않았다는 의미라고 가정: 비즈니스 결론을 내리기 전에 추적 번호, 계정 권한, 환경 및 응답 메시지를 확인하세요.
  • 텍스트만 매핑: 상태 설명은 달라질 수 있습니다. 문서화된 코드를 사용하고 알 수 없는 값은 검토를 위해 보존하세요.
  • 계정 및 사용 요구 사항 무시: 기술 코드는 올바르더라도 애플리케이션이 요청한 서비스에 맞게 구성되지 않았을 수 있습니다.
  • 비즈니스 규칙 없이 새로 고침: 불필요한 폴링은 고객 경험을 개선하지 못한 채 비용, 부하 및 운영상 잡음을 증가시킬 수 있습니다.

실용적인 출시 전 체크리스트

  1. 애플리케이션이 최신 UPS 문서와 승인된 환경을 사용하는지 확인합니다.
  2. 자격 증명이 서버 측에 저장되고 교체될 수 있는지 확인합니다.
  3. 인증 실패, 운송업체 오류, 형식이 잘못된 입력 및 타임아웃을 테스트합니다.
  4. 대표적인 배송에 대해 정규화된 상태를 원래 응답과 비교합니다.
  5. 새로 고침 정책을 설정하고 요청량을 모니터링합니다.
  6. 식별되지 않은 이벤트, 지연된 업데이트 및 고객 에스컬레이션에 대한 담당 주체를 정의합니다.
  7. 다른 개발자가 자격 증명, 엔드포인트 버전 및 상태 매핑을 안전하게 업데이트할 수 있도록 통합 내용을 문서화합니다.

FAQ

Tracking API를 사용하려면 UPS 계정이 필요한가요?

Developer Portal에서 최신 UPS 온보딩 및 액세스 요구 사항을 확인해야 합니다. API 액세스는 애플리케이션 등록, 자격 증명, 계정 구성 및 요청하는 특정 서비스에 따라 달라질 수 있습니다. 공개 추적 페이지 로그인이 개발자 API 액세스와 동일하다고 가정하지 마세요.

UPS Tracking API는 무료인가요?

API 액세스에 상업적 또는 사용 조건이 없다고 가정하지 마세요. UPS는 공식 채널을 통해 최신 서비스 및 계정 정보를 게시하며, 일부 요구 사항은 제품, 계정 또는 계약에 따라 달라질 수 있습니다. 프로덕션 예산을 계획하기 전에 적용되는 약관을 직접 확인하세요.

브라우저의 JavaScript에서 UPS API를 직접 호출할 수 있나요?

브라우저 기반 호출은 애플리케이션 자격 증명을 노출하고 교차 출처, 보안 및 사용 제어 문제를 일으킬 수 있습니다. 일반적으로 서버 측 통합이 비밀 정보 저장, 토큰 발급, 재시도 규칙 적용 및 배송 데이터 액세스 제한에 더 안전한 방식입니다.

애플리케이션에서 추적 업데이트를 얼마나 자주 요청해야 하나요?

운송업체의 문서화된 한도, 배송량, 운영상의 긴급성 및 사용자에게 필요한 최신성을 기준으로 새로 고침 정책을 사용하세요. 적절한 경우 최근 결과를 캐시하고, 일시적인 오류 후에는 백오프를 적용하며, 반복적인 폴링을 문서화된 이벤트 또는 알림 기능의 대체 수단으로 사용하지 마세요.

UPS 직접 통합과 멀티 운송업체 API 중 무엇을 사용해야 하나요?

운송업체별 제어가 필요한 UPS 중심 워크플로에는 UPS 직접 통합이 적합할 수 있습니다. 여러 운송업체를 사용하는 경우 멀티 운송업체 API를 이용하면 통합 수를 줄일 수 있습니다. 선택하기 전에 지원 운송업체, 인증, 데이터 필드, 안정성 요구 사항, 사용 약관 및 구현 작업량을 비교하세요.

출처

Loading