Advanced Integrated Visibility Tracking Number Subscription API를 사용하면 Advanced Integrated Visibility 수신 등록자가 API 엔드포인트를 통해 배송 조회 번호를 웹훅 프로젝트에 연결할 수 있습니다. 배송 조회 번호 연결 기능은 다음 두 가지 처리 방식을 지원합니다.

• 배송 조회 번호 연결 – 동기식은 동일한 HTTP 응답으로 처리 결과를 반환합니다. 이 옵션은 적은 수의 배송 조회 번호를 연결하고 그 결과를 즉시 확인해야 하는 애플리케이션에 가장 적합합니다. 
• 배송 조회 번호 연결 – 비동기식은 백그라운드 처리를 위해 요청을 제출하고, 나중에 처리 상태와 결과를 가져오는 데 사용할 수 있는 작업 ID를 반환합니다. 이 옵션은 대규모 배송 조회 번호 배치를 처리하는 데 가장 적합합니다. 

애플리케이션의 성능 및 작업량 요건에 가장 적합한 처리 방식을 선택하세요.

참고:

• Advanced Integrated Visibility 프로젝트에 대한 Admin 또는 Contributor 액세스가 있어야 합니다
• Advanced Integrated Visibility 및 해당 기능에 대한 자세한 내용은 Advanced Integrated Visibility 문서 페이지를 참조하세요.

Advanced Integrated Visibility Tracking Number Subscription API는 다음과 같은 장점을 제공합니다.

• API 엔드포인트를 사용하여 Advanced Integrated Visibility 웹훅 프로젝트의 배송 조회 번호를 간편하게 연결, 업데이트 및 관리할 수 있습니다.
• 각 배송 조회 번호를 개별적으로 처리하는 대신 단일 API 요청으로 여러 배송 조회 번호를 연결할 수 있습니다.
• 즉각적인 결과를 위한 동기식 처리와 대규모 일괄 작업을 위한 비동기식 처리 중에서 선택할 수 있습니다.

다음 엔드포인트를 사용해 Advanced Integrated Visibility 프로젝트를 관리합니다.

• 배송 조회 번호 연결 – 동기식: 배송 조회 번호를 웹훅에 연결하고 동일한 HTTP 응답으로 최종 처리 상태를 받을 수 있습니다.
• 배송 조회 번호 연결 – 비동기식: 배송 조회 번호를 웹훅에 연결하고 반환된 jobId로 나중에 관련 엔드포인트를 통해 비동기식 작업의 상태를 확인하거나 세부정보를 다운로드할 수 있습니다.    
  • 배송 조회 번호 작업 상태
  • 배송 조회 번호 작업 세부정보

이 API는 Advanced Integrated Visibility 프로젝트 개요에서 이용할 수 있습니다.

이 API는 위 스크린샷에 표시된 것처럼 프로젝트 개요를 통해서만 액세스할 수 있습니다.

다음 표에서 동기식 및 비동기식 배송 조회 번호 연결 엔드포인트의 주요 차이점을 확인할 수 있습니다.
 

소규모 배송 조회 번호 배치의 처리 결과를 즉시 확인해야 하는 경우 동기식 엔드포인트를 사용하세요. 즉각적인 응답이 필요하지 않은 대규모 배치를 처리하는 경우 비동기식 엔드포인트를 사용하세요.

이 엔드포인트를 사용하여 하나 이상의 배송 조회 번호를 Advanced Integrated Visibility 웹훅 프로젝트에 연결하고 동일한 HTTP 응답 내에서 처리 결과를 받을 수 있습니다.

이 엔드포인트는 즉각적인 확인이 필요한 애플리케이션을 위한 것으로, 최대 150개의 배송 조회 번호가 포함된 요청을 지원합니다.

필수 입력 사항: 

• subscriptionID
• trackingNumber

장점

동기식 엔드포인트는 다음과 같은 장점을 제공합니다.

• 즉각적인 처리 결과
• 단일 응답으로 상세한 성공 및 실패 정보 제공
• 요청당 최대 150개의 배송 조회 번호 지원
• 처리 전 요청 검증 및 비즈니스 규칙 적용
• 기계 판독이 가능한 오류 코드 및 설명이 포함된 오류 메시지
• 요청 추적 및 문제 해결을 위한 트랜잭션 ID

배송 조회 번호 연결 – 동기식 엔드포인트에는 다음을 포함한 여러 검증 규칙이 적용됩니다.

• 유효하고 활성화된 subscriptionId 필요
• 요청당 하나의 subscriptionId만 허용
• trackingNumber 필요
• 배송 조회 번호가 6~22자리인지 등 FedEx 형식 요건 충족 여부 확인

오류 응답은 쉽게 구문 분석할 수 있도록 code와 message가 포함된 errors[]의 일관된 구조를 따릅니다.

"errors": [

{

"code": "ERROR.CODE",

"message": "설명이 포함된 오류 메시지"

}

배송 조회 번호 연결 – 동기식 엔드포인트는 부분 성공을 허용합니다. 일부 배송 조회 번호가 실패하더라도 Synchronous API는 200 OK를 반환하며 다음을 표시합니다.

• failedTrackingNumbers
• 설명이 포함된 메시지

{

"transactionId":

   "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

   "output": {

      "failedTrackingNumbers":

         [ "XXXXX",

         " YYYYY"

         ],

      "message": "검증 또는 시스템 오류로 인해 아래 배송 조회 번호를 업로드하지 못했습니다"

      }

    }

자세한 내용과 규칙은 비즈니스 규칙 섹션을 참조하세요.

이 엔드포인트를 사용하여 하나 이상의 수신 등록된 배송 조회 번호를 백그라운드 처리용으로 제출할 수 있습니다.

요청을 제출하면 작업 ID가 반환됩니다. 이 작업 ID를 배송 조회 번호 작업 상태 엔드포인트에 사용하여 처리 상태를 모니터링하고, 작업이 완료된 후 배송 조회 번호 작업 세부정보 엔드포인트에 사용하여 처리 결과를 다운로드할 수 있습니다.

필수 입력 사항:

• 선택 취소
• 배송 조회 번호 세부정보

한 번 요청 시 최대 1,000개의 배송 조회 번호를 연결할 수 있습니다.

장점

비동기식 엔드포인트는 다음과 같은 장점을 제공합니다.

• 최대 1,000개의 배송 조회 번호로 구성된 대규모 일괄 제출 지원
• 장시간 실행되는 요청을 백그라운드에서 처리 가능
• 작업 상태 모니터링 및 다운로드 가능한 처리 보고서 제공
• 대규모 작업에서 요청 시간 초과에 대한 우려 해소

이 엔드포인트를 사용해 비동기식 작업(대기열에 있는 한 개 이상의 연속 요청)의 상태 또는 제출된 모든 작업의 상태를 가져올 수 있습니다.

이 요청에 필요한 입력 정보는 다음과 같습니다.

• jobID – 상태를 가져올 작업 ID를 지정합니다.

참고: 작업 ID는 이 엔드포인트의 선택 입력 항목입니다. 작업 ID를 지정하지 않으면 제출된 모든 작업의 상태를 가져옵니다.

이 요청에 성공하면 응답에서 작업 ID, 현재 작업 상태, 작업 생성 및 작업 완료 타임스탬프가 반환됩니다. 응답에는 작업의 현재 상태가 표시됩니다. 또한 성공 메시지, 오류 또는 경고도 표시되어 문제가 발생한 경우 사용자가 확인하고 해결할 수 있습니다.

• 작업 상태가 완료됨으로 표시되면 모든 배송 조회 번호가 검증되었으며 성공적으로 처리되었다는 의미입니다.
  • 완료됨 상태는 배송 조회 번호가 검증되고 처리되었음을 의미합니다. 모든 배송 조회 번호가 Advanced Integrated Visibility 프로젝트에 추가되었다는 의미는 아닙니다.
  • 여러 배송 조회 번호가 포함된 작업의 경우, 일부 번호는 프로젝트 연결에 실패하고 나머지는 성공하더라도 상태가 완료됨으로 표시될 수 있습니다. 원본 연결 요청 내 각 배송 조회 번호의 상태를 확인하려면 일괄 보고서를 다운로드하세요.

참고: 작업 상태가 실패로 표시되면 여러 사유/심각한 오류로 인해 요청을 처리하지 못했다는 의미이며, 사용자는 다시 시도해야 합니다.

다음 표에서 작업 상태와 각 상태에 대한 설명을 확인할 수 있습니다.

이 엔드포인트를 사용해 완료됨 상태인 비동기식 작업의 JSON 보고서를 다운로드할 수 있습니다.

이 요청과 관련된 필수 입력 정보는 다음과 같습니다.

• jobID – 상태를 가져올 작업 ID를 지정합니다. 작업 ID는 이 엔드포인트의 필수 입력 항목입니다.

참고:

• 비동기식 작업 보고서는 한 번에 하나만 다운로드할 수 있습니다.
• 작업이 완료되지 않은 상태에서 보고서를 다운로드하면 오류 메시지가 표시됩니다.

이 요청에 성공하면 응답에서 JSON 형식의 작업 보고서가 제공됩니다.

공통 비즈니스 규칙

• Advanced Integrated Visibility 프로젝트에 연결할 수 있는 배송 조회 번호의 총수에는 제한이 없습니다.
• Advanced Integrated Visibility 프로젝트에 연결된 배송 조회 번호는 웹훅에 성공적으로 연결된 후 40일이 지나면 연결이 해제됩니다.
• 수취인 주소, 수취인 서명 및 민감한 배송 정보 등 보호된 배송 조회 정보는 Tracking Number Subscription API를 통해 이용할 수 없습니다.

동기식 엔드포인트 비즈니스 규칙

• 요청당 배송 조회 번호 150개를 초과할 수 없습니다.
• 모든 배송 조회 번호에 동일한 subscriptionId를 사용해야 합니다.
• 지정된 Advanced Integrated Visibility 웹훅 수신 등록은 유효하고 활성화된 상태여야 합니다.
• 요청에는 30초의 제한 시간이 적용됩니다.

비동기식 엔드포인트 비즈니스 규칙

• 요청당 배송 조회 번호 1,000개를 초과할 수 없습니다.
• 비동기식 요청의 작업 상태와 작업 세부정보는 배송 조회 번호가 Advanced Integrated Visibility 웹훅에 성공적으로 연결된 후 90일 동안 보관됩니다.