Skip to main content
홈블로그가이드첫 번째 Tracking API 요청: Postman과 Curl을 사용한 REST 클라이언트 안내

첫 번째 Tracking API 요청: Postman과 Curl을 사용한 REST 클라이언트 안내

17TRACK

첫 번째 tracking API 요청을 보내려면 REST 클라이언트에서 엔드포인트, 인증 헤더 및 JSON 본문을 구성하고 요청을 전송한 다음 HTTP 상태와 응답 본문을 모두 확인하세요. 이 안내에서는 17TRACK’s Tracking API를 사용하여 Postman과 curl에서 동일한 워크플로를 시연합니다. 배송을 등록하고, 배송 추적 정보를 요청하며, 결과를 애플리케이션에서 사용할 수 있는 상태인지 확인합니다.

첫 번째 Tracking API 요청: REST 클라이언트 안내

목표는 프로덕션 배포가 아니라 작고 재현 가능한 통합 테스트입니다. API 자격 증명과 처리 권한이 있는 운송장 번호가 필요합니다. 아래 명령은 v2.2 엔드포인트 패턴을 사용하므로, 실행하기 전에 17TRACK API documentation에서 엔드포인트 버전과 계정별 요구 사항을 확인하세요.

첫 번째 요청이 수행해야 할 작업 이해하기

배송 추적 통합에는 두 가지 별도 작업이 있습니다. 추적할 배송을 서비스에 알리는 작업과 해당 배송에 연결된 추적 정보를 가져오는 작업입니다. 여기서 설명하는 워크플로에서는 이들이 별도의 요청으로 처리됩니다. 등록되었다고 해서 소포가 이미 이동했다는 의미는 아니며, 등록이 성공했다고 해서 운송사 이벤트를 즉시 사용할 수 있다는 보장도 없습니다.

첫 번째 테스트에서는 일괄 처리 대신 배송 하나를 사용하세요. 그러면 인증 오류, 잘못된 운송장 번호 및 응답 해석 문제를 쉽게 분리할 수 있습니다. 첫 번째 유의미한 이정표는 단순히 “HTTP 200을 받았다”가 아닙니다. “API가 의도한 작업을 수락했고 배송 수준의 결과를 설명할 수 있다”가 되어야 합니다.

Postman은 요청을 편집하고 응답을 확인할 수 있는 시각적 인터페이스를 제공합니다. curl은 터미널에서 동일한 HTTP 교환을 재현할 수 있게 합니다. 어느 도구도 API의 인증 규칙, 배송 데이터 또는 처리 동작을 변경하지 않습니다. 요청을 더 명확하게 조사하는 데 도움이 되는 도구를 사용한 다음, 작동하는 구성을 다른 도구에서도 재현하세요.

자격 증명, 배송 및 요청 세부 정보 준비하기

어느 클라이언트를 열기 전에 다음을 준비하세요.

  • 승인된 API 자격 증명: 17TRACK API 계정 설정을 통해 발급받으세요. 일반 소비자용 추적 세션은 API 자격 증명을 대신할 수 없습니다.
  • 실제 운송장 번호: 소유하고 있거나 액세스 권한이 있는 배송을 사용하세요. 실제 추적 데이터를 테스트할 때는 최근에 활성화된 배송이 임의로 만든 번호보다 일반적으로 더 유용합니다.
  • 운송사(알고 있는 경우): 진단을 위해 운송사 이름을 준비하세요. 사례에 운송사 식별자가 필요하다면 추측하지 말고 API documentation에 정의된 값과 필드를 사용하세요.
  • 현재 요청 계약: API 버전, 인증 헤더, 요청 스키마 및 계정 제한 사항을 확인하세요.
  • 안전한 작업 공간: 자격 증명, 고객 정보 또는 전체 추적 응답을 공개 저장소, 스크린샷이나 공유 지원 메시지에 넣지 마세요.

최소 요청 예시는 다음 설정을 사용합니다.

설정예시 구성
Base URLhttps://api.17track.net/track/v2.2
등록 작업POST /register
추적 정보 작업POST /gettrackinfo
인증 헤더17token: YOUR_API_TOKEN
본문 형식Content-Type: application/json 및 배송 객체의 JSON 배열

운송장 번호는 문자열로 유지하세요. 숫자 형식으로 변환하면 앞의 0이 제거되거나 값이 달라질 수 있습니다. 아래의 YOUR_TRACKING_NUMBER 플레이스홀더는 실제 테스트 배송으로 교체해야 하며, 작동하는 샘플 번호가 아닙니다.

Postman에서 등록 요청 만들기

1. 간단한 테스트 환경 만들기

Postman에서 base_url, tracking_token, tracking_number라는 세 변수가 있는 환경을 만드세요. base_url에는 위의 Base URL을 설정하고 나머지 변수에는 자격 증명과 배송 번호를 입력하세요. 요청을 보내기 전에 해당 환경을 선택하세요.

토큰에는 Postman에서 제공하는 비밀 값 처리 기능을 사용하고, 작업 공간에서 무엇을 공유하거나 동기화하는지 확인하세요. 인터페이스에서 값을 숨기는 것만으로는 해당 값에 액세스할 수 있는 사람을 통제할 수 없습니다. 동료나 공개 문서용 컬렉션에 입력된 자격 증명을 포함하여 내보내지 마세요.

2. 메서드, URL 및 헤더 구성하기

HTTP 요청을 만들고 POST를 선택한 다음 URL로 {{base_url}}/register를 입력하세요. Headers 탭에서 다음을 추가합니다.

17token: {{tracking_token}}
Content-Type: application/json

이 예시에서는 자격 증명을 사용자 지정 17token 헤더에 넣습니다. 다른 API가 해당 패턴을 사용했다는 이유만으로 Bearer token 구성으로 바꾸지 마세요. 상속된 컬렉션 설정으로 인해 의도하지 않은 Authorization 헤더가 추가되지 않았는지도 확인하세요.

3. JSON 본문 추가하기

Body를 열고 raw를 선택한 다음 JSON을 선택하세요. 다음을 입력합니다.

[
  {
    "number": "{{tracking_number}}"
  }
]

바깥쪽 대괄호가 중요합니다. 배송 하나만 포함되어 있어도 이 요청은 배열을 사용합니다. 큰따옴표를 사용하고 후행 쉼표를 제거하며 JSON 안에 주석을 넣지 마세요. 문서에서 운송사 또는 배송에 대한 추가 정보를 요구한다면 전송 전에 문서에 정의된 필드를 추가하세요.

4. 전송하고 결과 확인하기

Send를 클릭하세요. 먼저 HTTP 응답을 실제로 받았는지 확인합니다. DNS 실패, TLS 오류, 프록시 문제 또는 시간 초과는 요청이 잘못되었다고 설명하는 응답과 다릅니다. 다음으로 응답 본문에서 작업 결과와 배송 수준의 승인 또는 거부 정보를 확인하세요.

요청을 “Register test shipment”로 저장하세요. 토큰은 복사하지 말고 HTTP 상태, API 결과 및 오류 메시지를 기록합니다. 등록에 실패하면 다음 단계로 넘어가기 전에 해당 실패를 해결하세요. 변경되지 않은 요청을 반복해서 제출하면 진단이 어려워지고 계정 리소스를 사용할 수 있습니다.

curl로 요청 재현하기

다음 명령은 Bash 또는 Zsh와 같은 POSIX 스타일 셸을 사용합니다. PowerShell과 Windows Command Prompt는 인용 부호 및 변수 규칙이 다릅니다. PowerShell에서는 필요한 경우 셸별 명령 별칭이 아닌 curl 실행 파일을 호출하도록 curl.exe를 사용하세요.

Base URL을 설정하고 일반적인 비밀 값 처리 방식에 따라 자격 증명을 환경 변수에 로드하세요.

export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# 계속하기 전에 TRACKING_API_TOKEN을 안전하게 설정하세요.

환경 변수를 사용하면 재사용 가능한 예시에 자격 증명이 노출되지 않지만, 이것만으로 완전한 비밀 관리 시스템이 되지는 않습니다. 로컬 테스트에서는 셸 기록에 남는 명령에 실제 토큰을 직접 입력하지 마세요. 자동화에서는 플랫폼의 비밀 저장소를 사용하고 로그 출력을 제한하세요.

shipment.json이라는 파일을 만들고 플레이스홀더를 테스트용 운송장 번호로 바꾸세요.

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

등록 요청을 전송합니다.

curl --request POST \
  --url "$TRACKING_BASE_URL/register" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output register-response.json \
  --write-out 'HTTP status: %{http_code}\n'

이 명령은 응답 본문을 register-response.json에 저장하고 HTTP 상태를 별도로 출력합니다. 연결 및 전체 시간 초과는 로컬 테스트를 위한 설정이며 17TRACK 서비스의 보장이 아닙니다. 저장된 파일을 열어 API 결과를 확인하세요. 상태 줄만으로는 충분하지 않습니다.

서버가 HTTP 오류 응답을 반환하더라도 curl은 전송을 성공적으로 완료할 수 있습니다. 반대로 전송 실패가 발생하면 사용할 수 있는 API 응답이 도착하지 않을 수 있습니다. 스크립트를 작성할 때 curl 종료 상태, HTTP 상태 및 애플리케이션 수준 결과를 서로 다른 신호로 처리하세요.

배송의 추적 정보 요청하기

등록을 확인한 후 Postman 요청을 복제하고 URL을 {{base_url}}/gettrackinfo로 변경하세요. POST 메서드, 인증 헤더, 콘텐츠 유형 및 배송 본문은 그대로 유지합니다. 데이터를 가져오려는 상황에서 실수로 배송을 다시 등록하지 않도록 별도로 저장하세요.

이에 해당하는 curl 요청은 다음과 같습니다.

curl --request POST \
  --url "$TRACKING_BASE_URL/gettrackinfo" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output tracking-response.json \
  --write-out 'HTTP status: %{http_code}\n'

새로 등록한 배송이 즉시 완전한 이벤트 이력을 반환한다고 가정하지 마세요. 데이터 사용 가능 여부는 배송과 서비스의 처리 상태에 따라 달라집니다. 정보가 아직 उपलब्ध하지 않다면 동일한 번호를 반복 등록하거나 짧은 간격으로 폴링하지 말고 문서에 설명된 조회 및 업데이트 지침을 따르세요.

응답을 세 가지 계층으로 읽기

  1. 전송: 클라이언트가 연결하여 HTTP 응답을 받았습니까?
  2. 작업: API가 요청을 수락했으며 개별 배송도 성공했습니까?
  3. 배송 정보: 반환된 데이터가 의도한 소포를 식별하며, 상태 또는 이벤트 이력이 실제로 무엇을 입증합니까?

공식 응답 스키마를 사용하여 상태, 운송사 및 이벤트 필드를 찾으세요. 정규화된 배송 상태와 운송사의 원래 이벤트 설명을 구분해야 합니다. 조회가 성공했다고 해서 배송이 완료되었다는 증거는 아니며, 이벤트가 없다고 해서 소포가 분실되었다는 증거도 아닙니다.

타임스탬프를 저장할 때 제공된 시간대 또는 오프셋 정보를 유지하세요. 서로 다른 형식의 원시 날짜 문자열을 정렬하여 올바른 시간 순서를 나타낸다고 가정하지 마세요. 또한 애플리케이션이 레코드를 가져온 시간과 배송 이벤트가 발생한 시간을 구분하세요.

한 번에 모든 것을 변경하지 않고 문제 해결하기

  • 응답 없음: 호스트 이름, 네트워크 액세스, 프록시 설정, TLS 구성 및 로컬 시간 초과를 확인하세요. 일반적인 해결책으로 인증서 검증을 비활성화하지 마세요.
  • 인증 실패: 토큰이 활성 상태인지, 17token 헤더가 있는지, 선택한 Postman 환경이 변수를 올바르게 확인하는지 확인하세요. 실수로 포함된 공백도 확인하세요.
  • 잘못된 요청: 문서를 기준으로 API 버전, 작업 경로, POST 메서드, 콘텐츠 유형 및 JSON 배열 구조를 확인하세요.
  • 배송 거부: 배송별 오류를 읽으세요. 모든 거부를 인증 문제로 처리하지 말고 번호와 필요한 운송사 정보를 확인하세요.
  • 추적 이벤트 없음: 등록과 의도한 배송 식별자를 확인하세요. 재시도하기 전에 운송사 정보가 필요한지, 업데이트를 사용할 수 있는지 확인하세요.
  • Postman은 작동하지만 curl은 실패: 확인된 URL, 실제 헤더 및 본문 바이트를 비교하세요. 셸 인용과 설정되지 않은 환경 변수 때문에 요청이 달라지는 경우가 많습니다.

테스트마다 변수 하나만 변경하고 결과를 간단히 기록하세요. Postman 콘솔을 확인하거나 curl의 자세한 출력을 사용하는 경우 해당 출력을 민감한 정보로 취급하세요. 요청 헤더에 자격 증명이 노출될 수 있습니다. 진단 정보를 공유하기 전에 비밀 값과 고객 정보를 삭제하세요.

안내가 완료된 시점 알기

두 클라이언트가 의도한 요청을 전송하고, 등록을 이해했으며, 조회가 해석 가능한 결과를 반환하고, API 실패와 새로운 정보가 없는 배송을 구분할 수 있다면 의미 있는 첫 통합 테스트를 완료한 것입니다. HTTP 상태 코드가 일치한다는 사실만으로 두 클라이언트가 동일하게 동작했다고 볼 수는 없습니다.

워크플로를 애플리케이션으로 옮기기 전에 자격 증명을 서버에 보관하고, 입력을 검증하며, 구조화된 오류 처리를 사용하세요. 계정에 적용되는 문서화된 요청 속도 제한, 일괄 처리 제한, 재시도 지침 및 업데이트 전달 옵션을 확인하세요. 시간 초과 후 등록을 무조건 안전하게 재시도할 수 있다고 가정하지 마세요. 클라이언트가 응답을 받지 못했더라도 서버가 요청을 처리했을 수 있습니다.

잘못된 자격 증명, 잘못된 JSON, 잘못된 배송 번호, 이미 등록된 배송, 사용할 수 없는 추적 데이터 및 네트워크 시간 초과에 대한 테스트를 추가하세요. 각 사례는 처리되지 않은 예외나 오해를 유발하는 고객 표시 상태가 아니라 의도적인 애플리케이션 결과로 이어져야 합니다.

FAQ

실제 운송장 번호 없이 테스트할 수 있나요?

잘못된 값으로 일부 요청 검증 동작을 테스트할 수는 있지만, 이것으로 배송 추적이 검증되는 것은 아닙니다. 실제 이벤트를 테스트하려면 권한이 있는 배송 또는 서비스에서 제공하는 문서화된 테스트 픽스처를 사용하세요. 임의의 샘플 번호가 sandbox에 속한다고 가정하지 마세요.

HTTP 200 응답에 왜 실패가 포함되어 있나요?

HTTP 상태와 애플리케이션 결과는 서로 다른 계층을 설명합니다. 서버는 요청을 성공적으로 수신하고 처리하면서도 개별 배송이 거부되었다고 보고할 수 있습니다. HTTP 상태만 보지 말고 응답 본문과 문서화된 배송 수준 결과를 읽으세요.

추적 정보를 가져오는 데 POST를 사용하는 이유는 무엇인가요?

엔드포인트 계약에 지정된 메서드를 사용하세요. 이 조회 예시는 POST를 통해 JSON 요청 본문으로 배송 식별자를 받습니다. 작업이 데이터를 읽는다는 이유로 GET으로 변경하면 문서화된 요청을 유지할 수 없습니다.

API 토큰을 브라우저 JavaScript에 넣어도 되나요?

공개적으로 전달되는 프론트엔드 코드에 개인 API 자격 증명을 포함하지 마세요. 자격 증명을 보호하고, 입력을 검증하며, 각 사용자가 액세스할 수 있는 배송 정보를 제어하는 승인된 백엔드를 통해 요청을 전달하세요.

프로덕션에 Postman과 curl이 모두 필요한가요?

아니요. 두 도구는 테스트 및 진단에 유용합니다. 프로덕션 애플리케이션에서는 적절한 HTTP 클라이언트를 사용할 수 있습니다. 실제 토큰이나 불필요한 고객 데이터를 포함하지 않은 정리된 Postman 요청 또는 curl 명령을 재현 가능한 참고 자료로 보관하세요.

Sources