FedEx API 모범 사례

본 문서는 API 사용자가 FedEx와의 통합 경험을 개선하고 설계, 속도, 보안의 측면에서 통합 솔루션의 품질을 보장할 수 있는 방법을 이해하도록 돕기 위한 빠른 참조 가이드입니다.

FedEx API와 효율적인 통합을 실천하려면, 개발자는 이러한 통합 모범 사례를 따라야 합니다.

API URI

• 테스트와 프로덕션 각각 별도의 API URI가 있습니다. 
• 개발자는 개발 및 통합 테스팅에 테스트 URI를 사용하고 프로덕션에는 프로덕션 URI를 사용해야 합니다.

API URI는 다음과 같습니다.

테스트: https://apis-sandbox.fedex.com/

프로덕션: https://apis.fedex.com/

자격 증명 관리

• API 키 및 시크릿 키

• API 키와 시크릿 키는 응용 프로그램을 식별하는 데 사용되며 OAuth 토큰을 요청할 때 필요합니다.

1. API 키와 시크릿 키는 보안을 철저하게 관리해야 합니다. 이메일이나 클라이언트측 JavaScript를 비롯한 배포 코드를 통해 API 키 또는 시크릿 키를 배포하지 마십시오.
2. API 키나 시크릿 키를 도난당하면 응용 프로그램의 보안이 위험해집니다. 자격 증명이 도난당했거나 유출되었다고 생각되면 즉시 시크릿 키를 다시 만드십시오.
3. 시크릿 키와 같은 민감한 정보는 로그 기록을 피하십시오.

• 코드에 API 키와 시크릿 키를 하드코드에 포함하지 마십시오.
• 응용 프로그램에서 API 키와 시크릿 키를 유동적으로 업데이트할 수 있어야 합니다.
• 클라이언트 자격 증명을 볼트(vault)/안전 위치에 저장해 유출되지 않도록 하십시오.

• OAuth 토큰

• 액세스 토큰은 웹 응용 프로그램 서버에만 저장해 브라우저에 노출되지 않도록 하십시오.
• 토큰을 응용 프로그램에 하드코드로 포함하지 마십시오.
• 액세스 토큰이 손상되지 않도록 안전하게 보관하십시오.
• 새 액세스 토큰을 받기 위해 OAuth 토큰 API를 여러 번 호출하지 마십시오. HTTP 오류 코드 401을 수신할 때까지 액세스 토큰을 캐시하는 것이 좋습니다. 오류 코드가 나타나면 OAuth 토큰을 다시 생성하십시오.
• 토큰을 최종 사용자 또는 응용 프로그램에 노출하지 마십시오.
• 모든 API 트랜잭션에는 HTTPS를 사용하십시오.

코딩 사례

• 가장 안전한 최신 데이터 암호화 통신 프로토콜을 준수하기 위해 전송 계층 보안(TLS) 버전 1.2 이상을 사용하는 것이 좋습니다.
• 각 API 요청에 필요한 올바른 API 헤더를 잊지 말고 설정하십시오. 이 헤더 정보는 각 API 문서 페이지에서 확인할 수 있습니다. 
• HTTP POST의 'Content-Type'은 'application/json'이어야 합니다.
• 각 API 작업을 시작할 때 샘플 코드를 참조하십시오. 각 API 엔드포인트에는 필수 요소, 형식 및 기타 세부 정보를 이해하는 데 도움이 되는 여러 샘플이 포함되어 있습니다.
• 사용자 또는 개발자가 여러 소수점이 있는 값을 전송하면 이상한 오류가 발생할 수 있습니다. 무게 및 통화 값/금액의 경우 명시적인 두 자리 소수점만 허용됩니다. 길이, 폭, 높이 등의 치수는 소수점을 지원하지 않습니다.

예: 무게: 45.26, 통화 값/금액: 100.52, 길이: 10, 폭: 25, 높이: 15.

• 빈 요소를 전송하지 마십시오.

예: “Streetlines”:””

• 요청을 처리하는 데 필요한 데이터만 전송하십시오.

예를 들어, 미국 국내 발송의 경우 상업송장 및 상품 데이터는 국제 발송에만 필요할 수 있으므로 전송하지 마십시오.

• 개발 시 운임처럼 비필수 응답 요소가 반환되지 않은 경우에 어떻게 반응할지 결정하십시오. 데이터를 사용하기 전 트랜잭션 응답에 누락된 요소는 없는지 평가하십시오.

예를 들어, 운임 확인이 작동하지 않아도 패키지를 발송할 수 있습니다. 데이터를 사용하기 전 트랜잭션 응답에 누락된 요소는 없는지 평가하십시오.

• 가능하면 FedEx API 통합에 대한 하드 의존성을 피하십시오.
• 지연 시간을 줄이고 정확한 결과를 얻으려면 다음을 사용해야 합니다.
  
  • 필터링 - 찾고 있는 매개 변수로 검색 범위를 좁힐 때 사용합니다.
  • 정렬 - 특정 매개 변수를 기준으로 검색 결과를 오름차순 또는 내림차순으로 정렬하는 데 사용합니다.
• 트랜잭션을 전송하기 전에 수취인 우편 번호 및 패키지 무게 등의 필수 필드에 데이터가 입력되었는지 확인하십시오. 데이터가 해당 필드에 적합한지 확인하십시오. 트랜잭션 오류를 최소화할 수 있습니다.
  

예를 들어, 미국 우편번호의 경우 필드 값이 모두 숫자이며, 5자리 또는 ZIP+4자리 우편번호 형식인지 확인합니다.

• FedEx 시스템의 가용성 및 안정성에 부정적인 영향을 피하는 방법.
  
  • 테스트 또는 프로덕션 환경에서 성능 테스트를 실행하지 마십시오.
  • 같은 트랜잭션이 반복해서 실패하는 일이 없도록 코딩 로직을 설정하십시오.
• 스로틀링 한계는 10초 동안 1400개 트랜잭션으로 설정되어 있습니다. 처음 몇 초 안에 이 한계에 도달하면 HTTP 오류 코드 429 Too many requests가 반환되고, 10초에 이를 때까지 트랜잭션이 제한되었다가 이후 다시 트랜잭션이 시작됩니다.
  

예를 들어, 첫 4초 동안 1400개 요청을 수신하는 경우 HTTP 오류 코드 429 Too many requests - '짧은 시간 동안 너무 많은 요청을 수신했습니다. 잠시 기다렸다가 다시 시도하십시오.'가 반환되고, 다음 6초 동안 트랜잭션이 제한되었다가 그 후에 다시 시작됩니다.

• 서비스 유형, 패키지 유형, 무게 한도 등 발송물에 대한 비즈니스 규칙은 변경될 가능성이 있으므로 하드코드로 포함하지 마십시오.

오류 처리

각 API 응답에는 HTTP 상태 코드와 응답 페이로드가 포함됩니다. 일부 응답에는 오류, 경고 또는 메모(해당하는 경우)가 포함됩니다. 경고 및 메모가 실패의 표시는 아니지만 오류 또는 경고 메시지는 로그 및 검토를 거쳐야 합니다. 적절한 오류 처리는 FedEx와의 원활한 통합이 이루어지게 해주고, 파손을 피하는 데 도움이 될 수 있습니다.

HTTP 상태 코드

요금

• 요금 견적을 알아보는 데에는 두 가지 방법이 있습니다.
  
  • 특정 서비스 유형의 요금 - 표시되는 결과가 serviceType 값으로 필터링됩니다. 회신 크기가 줄고, 트랜잭션 응답 시간이 감소합니다.
    

    예: STANDARD_OVERNIGHT

  • 요즘 선택 – serviceType이 표시되지 않는 경우에는 해당하는 모든 서비스와 해당 요금이 반환됩니다.
• 서비스 이용 가능성 API를 사용하여 특정 출발지-도착지 조합에 이용할 수 있는 서비스, 패키지 옵션 및 특별 서비스를 결정하고, 요금 요청에 serviceType 및 패키지 옵션을 전달하십시오.
  

  예를 들어, STANDARD_OVERNIGHT(특히)는 모든 우편 번호 간에 이용할 수 있는 것은 아닙니다.

• 발송에 적용해야 하는 특별 서비스가 있는 경우 특별 서비스의 유형 및 그 세부 정보를 포함해야 합니다. 
  
  • 참고: 일부 특별 서비스에는 세부 정보가 없습니다.
• 요금 API 문서를 참고하십시오.

발송

• 서비스 이용 가능성 API를 사용하여 특정 출발지-도착지 조합에 이용할 수 있는 서비스를 결정하고, 발송 요청에 serviceType 및 패키지 옵션을 전달하십시오.
• 발송에 적용해야 하는 특별 서비스가 있는 경우 특별 서비스의 유형 및 그 세부 정보를 포함해야 합니다. 
  • 참고: 일부 특별 서비스에는 세부 정보가 없습니다.
• 발송물을 픽업하기 전 발송일 종료 시 FedEx Ground 마감을 수행하십시오.
  
• 발송 API 문서를 참고하십시오.
  

배송 조회

• 싱글트랙 요청의 배송 조회 번호 개수는 30개로 제한하십시오. 회신 크기가 줄어들고, 트랜잭션 응답 시간이 감소합니다.
• 패키지 배송 조회 횟수는 비즈니스상 필요한 횟수로 제한하십시오.
• 일괄 배송 조회의 경우 배송 조회 상태를 "배송 완료"로 반환한 패키지는 일괄묶음에서 제거하십시오.
• 배송조회 API 문서를 참고하십시오.

주소 확인

• FedEx는 최종 결정이 아닌 제안으로 주소 확인 기능을 제공합니다. 해당 주소를 이용할 수 있을지는 제공된 데이터와 비즈니스상 필요성을 감안하여 최종 사용자가 결정해야 합니다. 주문을 계속 처리할 수 있도록 확인할 수 없는 주소를 해결하기 위한 프로세스가 마련되어 있어야 합니다.
• 더 나은 발송 서비스가 이루어지도록 하려면 주소 확인 같은 옵션 서비스에 발송 프로세스를 의존하지는 마십시오.

예를 들어, 주문 입력 또는 발송 시 주소 확인 API를 이용할 수 없는 경우에 대비해 발송을 완료하기 위한 비상대응방안이 마련되어 있어야 합니다.

• 주소 확인 API 문서를 참고하십시오.
  

FedEx 접수처 검색

• 특정 속성(예: 접수처 유형, 제공되는 서비스 등)을 제공하여 검색 범위를 좁힘으로써, 적합한 접수처 옵션을 확인하고 응답 시간을 줄이십시오.
• FedEx 접수처 검색 API 문서를 참고하십시오.
  

픽업 요청

• 픽업 예약 시 이미 지난 준비 시간이나 과거 날짜, 또는 너무 먼 향후 날짜를 입력하지 마십시오.
• 익명 픽업은 허용되지 않습니다.
  
• 픽업 요청 API 문서를 참고하십시오.
  

서비스 이용 가능성

• FedEx Express(FDXE), FedEx Ground(FDXG), FedEx Freight(FXFR) 및 FedEx Ground® Economy 등 여러 계열사의 결과를 확인하려면 여러 운송업체 코드를 지정할 수 없으므로 carrierCodes 요소를 생략하거나 별도의 서비스 이용 가능성 요청을 전송하십시오.
• 151파운드 이상의 개별 스키드 및 도합 2,200파운드를 초과하는 스키드에 대해 사전 승인을 받았는지 확인하십시오.
  
• 가변 옵션으로 SATURDAY_DELIVERY를 지정하면 토요일 배송이 옵션인 모든 서비스에 대해 토요일 배송 옵션과 일반 옵션이 모두 표시됩니다. 특별 서비스에는 SATURDAY_DELIVERY를 지정하지 마십시오. 그럴 경우 해당하는 토요일 배송 옵션만 반환됩니다.
• 서비스 이용 가능성 API 문서를 참고하십시오.

고객 지원

궁금한 점이 있거나 지원이 필요하시면 FedEx가 도와드리겠습니다! 지원 페이지에서 문의 방법 및 리소스에 대해 확인할 수 있습니다.