택배 배송조회

기능·제공 범위

인증: Bearer 키
요청: form-data
응답: JSON
요금·이용 조건: 기본 단가 5P · 건당

빠른 시작

서버의 APICK_API_KEY를 준비하고 입력값을 바꾸세요. 아래에서 경로별 입력·응답·실행 환경을 함께 확인할 수 있습니다.

요청과 응답

API 요청 예제직접 실행하지 않습니다POST /rest/parcel_tracking

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

curl --fail-with-body --request POST 'https://apick.app/rest/parcel_tracking' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'carrier=cj' \
  --form-string 'trackingNumber=123456789012'

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

const form = new FormData();
form.append("carrier", "cj");
form.append("trackingNumber", "123456789012");
const response = await fetch("https://apick.app/rest/parcel_tracking", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

import os
import requests
parts = [
    ("carrier", (None, "cj")),
    ("trackingNumber", (None, "123456789012")),
]
response = requests.request("POST", "https://apick.app/rest/parcel_tracking",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'carrier' => 'cj',
    'trackingNumber' => '123456789012',
];
$curl = curl_init('https://apick.app/rest/parcel_tracking');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

curl --fail-with-body --request POST 'https://apick.app/rest/parcel_tracking' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --connect-timeout 10 --max-time 120 \
  --form-string 'carrier=cj' \
  --form-string 'trackingNumber=123456789012'

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

const form = new FormData();
form.append("carrier", "cj");
form.append("trackingNumber", "123456789012");
const response = await fetch("https://apick.app/rest/parcel_tracking", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
if (result.error || result.data?.error || result.result?.error || result.success === false || result.api?.success === false) {
  throw new Error(JSON.stringify(result));
}
console.log(result);

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

import os
import requests
parts = [
    ("carrier", (None, "cj")),
    ("trackingNumber", (None, "123456789012")),
]
response = requests.request("POST", "https://apick.app/rest/parcel_tracking",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
if result.get("error") or (isinstance(result.get("data"), dict) and result["data"].get("error")) or (isinstance(result.get("result"), dict) and result["result"].get("error")) or result.get("success") is False or (result.get("api") or {}).get("success") is False:
    raise RuntimeError(result)
print(result)

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'carrier' => 'cj',
    'trackingNumber' => '123456789012',
];
$curl = curl_init('https://apick.app/rest/parcel_tracking');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if (!empty($result["error"]) || !empty($result["data"]["error"]) || !empty($result["result"]["error"]) || ($result["success"] ?? true) === false || ($result["api"]["success"] ?? true) === false) {
    throw new RuntimeException($body);
}
print_r($result);

1. API 요청

POST/rest/parcel_tracking

Bearer 인증 · multipart/form-data · JSON 응답

입력 항목

폼 항목·타입

필수

설명·예제

carrierstring

필수

택배사 코드 (예: cj, hanjin, lotte, logen, epost-domestic)예: cj

trackingNumberstring

필수

운송장번호예: 123456789012

응답과 성공 판정

HTTP 성공과 업무 결과를 구분하세요. 아래 서비스별 결과 필드가 실제 성공·실패를 나타냅니다.

응답 상태

{
  "data": {
    "carrier": {
      "code": "cj",
      "name": "CJ대한통운"
    },
    "trackingNumber": "123456789012",
    "status": "DELIVERED",
    "carrierStatus": "배달완료",
    "events": [
      {
        "time": "2026-08-01T09:00:00+09:00",
        "location": "서울",
        "status": "PICKED_UP",
        "carrierStatus": "집화완료",
        "description": "집화완료"
      },
      {
        "time": "2026-08-02T14:00:00+09:00",
        "location": "서울",
        "status": "DELIVERED",
        "carrierStatus": "배달완료",
        "description": "배달완료"
      }
    ],
    "success": 1
  },
  "api": {
    "success": true,
    "cost": 5,
    "ms": 1820,
    "pl_id": 1595644
  }
}

필드·타입

의미·조건

dataobject

조회 데이터

data.carrierobject

택배사 정보(code, name)

data.carrier.codestring

아래 하위 항목을 확인하세요.

data.carrier.namestring

아래 하위 항목을 확인하세요.

data.trackingNumberstring

운송장번호

data.statusstring

정규화된 배송상태. 아래 "배송상태(status) 값" 표 참고

data.carrierStatusstring

택배사 원문 상태 텍스트(예: "배달완료")

data.eventsarray

배송 이력(오래된 순 → 최신 순). 각 항목: time, location, status, carrierStatus, description

data.events[].timestring

아래 하위 항목을 확인하세요.

data.events[].locationstring

아래 하위 항목을 확인하세요.

data.events[].statusstring

아래 하위 항목을 확인하세요.

data.events[].carrierStatusstring

아래 하위 항목을 확인하세요.

data.events[].descriptionstring

아래 하위 항목을 확인하세요.

data.successinteger

과금 여부0: 실패(미과금)1: 성공(과금)

apiobject

API 호출 공통 데이터

api.successboolean

API 서버 정상 응답 여부true: 서버가 요청을 정상 처리false: 서버 처리 실패

api.costinteger

API 호출 요금(포인트)

api.msinteger

API 응답 시간(밀리초)

api.pl_idinteger

API 결제 로그 ID

정적 연동 예시입니다. 실제 계정·개인정보를 조회하지 않습니다.

API 요청 예제직접 실행하지 않습니다POST /rest/parcel_tracking_auto

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

curl --fail-with-body --request POST 'https://apick.app/rest/parcel_tracking_auto' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'trackingNumber=123456789012'

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

const form = new FormData();
form.append("trackingNumber", "123456789012");
const response = await fetch("https://apick.app/rest/parcel_tracking_auto", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

import os
import requests
parts = [
    ("trackingNumber", (None, "123456789012")),
]
response = requests.request("POST", "https://apick.app/rest/parcel_tracking_auto",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'trackingNumber' => '123456789012',
];
$curl = curl_init('https://apick.app/rest/parcel_tracking_auto');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

curl --fail-with-body --request POST 'https://apick.app/rest/parcel_tracking_auto' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --connect-timeout 10 --max-time 120 \
  --form-string 'trackingNumber=123456789012'

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

const form = new FormData();
form.append("trackingNumber", "123456789012");
const response = await fetch("https://apick.app/rest/parcel_tracking_auto", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
if (result.error || result.data?.error || result.result?.error || result.success === false || result.api?.success === false) {
  throw new Error(JSON.stringify(result));
}
console.log(result);

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

import os
import requests
parts = [
    ("trackingNumber", (None, "123456789012")),
]
response = requests.request("POST", "https://apick.app/rest/parcel_tracking_auto",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
if result.get("error") or (isinstance(result.get("data"), dict) and result["data"].get("error")) or (isinstance(result.get("result"), dict) and result["result"].get("error")) or result.get("success") is False or (result.get("api") or {}).get("success") is False:
    raise RuntimeError(result)
print(result)

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'trackingNumber' => '123456789012',
];
$curl = curl_init('https://apick.app/rest/parcel_tracking_auto');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if (!empty($result["error"]) || !empty($result["data"]["error"]) || !empty($result["result"]["error"]) || ($result["success"] ?? true) === false || ($result["api"]["success"] ?? true) === false) {
    throw new RuntimeException($body);
}
print_r($result);

2. API 요청

POST/rest/parcel_tracking_auto

Bearer 인증 · multipart/form-data · JSON 응답

입력 항목

폼 항목·타입

필수

설명·예제

trackingNumberstring

필수

운송장번호예: 123456789012

응답과 성공 판정

HTTP 성공과 업무 결과를 구분하세요. 아래 서비스별 결과 필드가 실제 성공·실패를 나타냅니다.

응답 상태

{
  "data": {
    "carrier": {
      "code": "cj",
      "name": "CJ대한통운"
    },
    "trackingNumber": "123456789012",
    "status": "DELIVERED",
    "carrierStatus": "배달완료",
    "events": [
      {
        "time": "2026-08-01T09:00:00+09:00",
        "location": "서울",
        "status": "PICKED_UP",
        "carrierStatus": "집화완료",
        "description": "집화완료"
      },
      {
        "time": "2026-08-02T14:00:00+09:00",
        "location": "서울",
        "status": "DELIVERED",
        "carrierStatus": "배달완료",
        "description": "배달완료"
      }
    ],
    "success": 1
  },
  "api": {
    "success": true,
    "cost": 5,
    "ms": 1820,
    "pl_id": 1595644
  }
}

필드·타입

의미·조건

dataobject

조회 데이터

data.carrierobject

택배사 정보(code, name)

data.carrier.codestring

아래 하위 항목을 확인하세요.

data.carrier.namestring

아래 하위 항목을 확인하세요.

data.trackingNumberstring

운송장번호

data.statusstring

정규화된 배송상태. 아래 "배송상태(status) 값" 표 참고

data.carrierStatusstring

택배사 원문 상태 텍스트(예: "배달완료")

data.eventsarray

배송 이력(오래된 순 → 최신 순). 각 항목: time, location, status, carrierStatus, description

data.events[].timestring

아래 하위 항목을 확인하세요.

data.events[].locationstring

아래 하위 항목을 확인하세요.

data.events[].statusstring

아래 하위 항목을 확인하세요.

data.events[].carrierStatusstring

아래 하위 항목을 확인하세요.

data.events[].descriptionstring

아래 하위 항목을 확인하세요.

data.successinteger

과금 여부0: 실패(미과금)1: 성공(과금)

apiobject

API 호출 공통 데이터

api.successboolean

API 서버 정상 응답 여부true: 서버가 요청을 정상 처리false: 서버 처리 실패

api.costinteger

API 호출 요금(포인트)

api.msinteger

API 응답 시간(밀리초)

api.pl_idinteger

API 결제 로그 ID

정적 연동 예시입니다. 실제 계정·개인정보를 조회하지 않습니다.

API 요청 예제직접 실행하지 않습니다POST /rest/parcel_tracking_carriers

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

printf '%s\r\n' '--apick-empty--' | curl --fail-with-body --request POST 'https://apick.app/rest/parcel_tracking_carriers' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --header 'Content-Type: multipart/form-data; boundary=apick-empty' \
  --data-binary @-

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

const form = new FormData();
const response = await fetch("https://apick.app/rest/parcel_tracking_carriers", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

import os
import requests
response = requests.request("POST", "https://apick.app/rest/parcel_tracking_carriers",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"], "Content-Type": "multipart/form-data; boundary=apick-empty"},
    data=b"--apick-empty--\r\n",
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$headers[] = "Content-Type: multipart/form-data; boundary=apick-empty";
$form = "--apick-empty--\r\n";
$curl = curl_init('https://apick.app/rest/parcel_tracking_carriers');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

printf '%s\r\n' '--apick-empty--' | curl --fail-with-body --request POST 'https://apick.app/rest/parcel_tracking_carriers' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --connect-timeout 10 --max-time 120 \
  --header 'Content-Type: multipart/form-data; boundary=apick-empty' \
  --data-binary @-

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

const form = new FormData();
const response = await fetch("https://apick.app/rest/parcel_tracking_carriers", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
if (result.error || result.data?.error || result.result?.error || result.success === false || result.api?.success === false) {
  throw new Error(JSON.stringify(result));
}
console.log(result);

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

import os
import requests
response = requests.request("POST", "https://apick.app/rest/parcel_tracking_carriers",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"], "Content-Type": "multipart/form-data; boundary=apick-empty"},
    data=b"--apick-empty--\r\n",
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
if result.get("error") or (isinstance(result.get("data"), dict) and result["data"].get("error")) or (isinstance(result.get("result"), dict) and result["result"].get("error")) or result.get("success") is False or (result.get("api") or {}).get("success") is False:
    raise RuntimeError(result)
print(result)

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$headers[] = "Content-Type: multipart/form-data; boundary=apick-empty";
$form = "--apick-empty--\r\n";
$curl = curl_init('https://apick.app/rest/parcel_tracking_carriers');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if (!empty($result["error"]) || !empty($result["data"]["error"]) || !empty($result["result"]["error"]) || ($result["success"] ?? true) === false || ($result["api"]["success"] ?? true) === false) {
    throw new RuntimeException($body);
}
print_r($result);

3. API 요청

POST/rest/parcel_tracking_carriers

Bearer 인증 · multipart/form-data · JSON 응답

입력 항목

추가 폼 항목이 없습니다. 인증 헤더는 필요합니다.

응답과 성공 판정

HTTP 성공과 업무 결과를 구분하세요. 아래 서비스별 결과 필드가 실제 성공·실패를 나타냅니다.

공개된 정적 응답 예제가 없는 경로입니다. 필드 명세에서 제공 범위를 확인하세요.

필드·타입

의미·조건

successboolean

목록 조회 성공 여부.

updatedAtstring

목록의 최근 갱신 시각. ISO 8601 일시. 이력이 없으면 null. null 허용.

summaryobject

공개 조회 대상 상태 집계.

summary.totalinteger

상태 집계 대상 택배사 수.

summary.activeinteger

조회 가능한 택배사 수.

summary.maintenanceinteger

점검·확인 중인 택배사 수.

activeCarriersarray

ACTIVE 상태인 택배사 목록. 없으면 빈 배열.

activeCarriers[].codestring

택배사 코드. 지정 조회의 carrier에 사용합니다.

activeCarriers[].namestring

택배사 표시 이름.

activeCarriers[].aliasesarray

같은 택배사를 가리키는 이름 목록.

activeCarriers[].serviceTypestring

배송 서비스 분류.

activeCarriers[].lookupTypestring

조회 유형.

activeCarriers[].publicTrackingboolean

공개 배송 조회 지원 여부.

activeCarriers[].statusstring

ACTIVE=조회 가능, MAINTENANCE=점검 중, CHECKING=확인 중, UNAVAILABLE=상태 정보 없음.허용값: ACTIVE, MAINTENANCE, CHECKING, UNAVAILABLE

activeCarriers[].availableboolean

현재 조회 가능한지 여부.

activeCarriers[].staleboolean

상태 정보가 갱신 기준을 넘겼는지 여부.

activeCarriers[].checkedAtstring

최근 확인 시각. ISO 8601 일시. 이력이 없으면 null. null 허용.

activeCarriers[].lastSuccessAtstring

최근 정상 확인 시각. ISO 8601 일시. 이력이 없으면 null. null 허용.

activeCarriers[].lastFailureAtstring

최근 실패 확인 시각. ISO 8601 일시. 이력이 없으면 null. null 허용.

activeCarriers[].errorCodestring

최근 상태 확인 코드. 문제가 없거나 이력이 없으면 null. 알려지지 않은 코드도 처리하세요. null 허용.

activeCarriers[].sourcestring

상태 갱신의 출처 구분. 이력이 없으면 null. null 허용.

maintenanceCarriersarray

ACTIVE 이외 상태인 택배사 목록. 없으면 빈 배열.

maintenanceCarriers[].codestring

택배사 코드. 지정 조회의 carrier에 사용합니다.

maintenanceCarriers[].namestring

택배사 표시 이름.

maintenanceCarriers[].aliasesarray

같은 택배사를 가리키는 이름 목록.

maintenanceCarriers[].serviceTypestring

배송 서비스 분류.

maintenanceCarriers[].lookupTypestring

조회 유형.

maintenanceCarriers[].publicTrackingboolean

공개 배송 조회 지원 여부.

maintenanceCarriers[].statusstring

ACTIVE=조회 가능, MAINTENANCE=점검 중, CHECKING=확인 중, UNAVAILABLE=상태 정보 없음.허용값: ACTIVE, MAINTENANCE, CHECKING, UNAVAILABLE

maintenanceCarriers[].availableboolean

현재 조회 가능한지 여부.

maintenanceCarriers[].staleboolean

상태 정보가 갱신 기준을 넘겼는지 여부.

maintenanceCarriers[].checkedAtstring

최근 확인 시각. ISO 8601 일시. 이력이 없으면 null. null 허용.

maintenanceCarriers[].lastSuccessAtstring

최근 정상 확인 시각. ISO 8601 일시. 이력이 없으면 null. null 허용.

maintenanceCarriers[].lastFailureAtstring

최근 실패 확인 시각. ISO 8601 일시. 이력이 없으면 null. null 허용.

maintenanceCarriers[].errorCodestring

최근 상태 확인 코드. 문제가 없거나 이력이 없으면 null. 알려지지 않은 코드도 처리하세요. null 허용.

maintenanceCarriers[].sourcestring

상태 갱신의 출처 구분. 이력이 없으면 null. null 허용.

carriersarray

전체 택배사 목록. 상태 집계 대상 밖의 항목은 UNAVAILABLE일 수 있습니다.

carriers[].codestring

택배사 코드. 지정 조회의 carrier에 사용합니다.

carriers[].namestring

택배사 표시 이름.

carriers[].aliasesarray

같은 택배사를 가리키는 이름 목록.

carriers[].serviceTypestring

배송 서비스 분류.

carriers[].lookupTypestring

조회 유형.

carriers[].publicTrackingboolean

공개 배송 조회 지원 여부.

carriers[].statusstring

ACTIVE=조회 가능, MAINTENANCE=점검 중, CHECKING=확인 중, UNAVAILABLE=상태 정보 없음.허용값: ACTIVE, MAINTENANCE, CHECKING, UNAVAILABLE

carriers[].availableboolean

현재 조회 가능한지 여부.

carriers[].staleboolean

상태 정보가 갱신 기준을 넘겼는지 여부.

carriers[].checkedAtstring

최근 확인 시각. ISO 8601 일시. 이력이 없으면 null. null 허용.

carriers[].lastSuccessAtstring

최근 정상 확인 시각. ISO 8601 일시. 이력이 없으면 null. null 허용.

carriers[].lastFailureAtstring

최근 실패 확인 시각. ISO 8601 일시. 이력이 없으면 null. null 허용.

carriers[].errorCodestring

최근 상태 확인 코드. 문제가 없거나 이력이 없으면 null. 알려지지 않은 코드도 처리하세요. null 허용.

정적 연동 예시입니다. 실제 계정·개인정보를 조회하지 않습니다.

추가 입력 조건·전송 규칙

Header

이름

필수

설명

Authorization

O

Bearer 인증키

택배사 목록 조회(/rest/parcel_tracking_carriers)는 별도 파라미터가 필요 없습니다. 응답의 activeCarriers에는 현재 정상조회 가능한 목록, maintenanceCarriers에는 점검중인 목록이 담깁니다.

응답 상세

서비스 고유 응답·필드 상세 설명

택배사 상태·목록 API

이름

타입

설명

updatedAt

String|null

가장 최근 상태 반영 시각

summary

Object

전체·정상·점검중 택배사 수

activeCarriers

Array

현재 정상조회 가능한 택배사 목록

maintenanceCarriers

Array

점검중이거나 상태 확인 중인 택배사 목록

carriers[].status

String

ACTIVE, MAINTENANCE, CHECKING, UNAVAILABLE

carriers[].available

Boolean

현재 정상조회 가능 여부

carriers[].checkedAt

String|null

해당 택배사의 최근 상태 반영 시각

Body — 조회 성공 시

이름

타입

설명

data

Object

조회 데이터

carrier

Object

택배사 정보(code, name)

trackingNumber

String

운송장번호

status

String

정규화된 배송상태. 아래 "배송상태(status) 값" 표 참고

carrierStatus

String

택배사 원문 상태 텍스트(예: "배달완료")

events

Array

배송 이력(오래된 순 → 최신 순). 각 항목: time, location, status, carrierStatus, description

success

Integer

과금 여부
0: 실패(미과금)
1: 성공(과금)

api

Object

API 호출 공통 데이터

success

Boolean

API 서버 정상 응답 여부
true: 서버가 요청을 정상 처리
false: 서버 처리 실패

cost

Integer

API 호출 요금(포인트)

ms

Integer

API 응답 시간(밀리초)

pl_id

Integer

API 결제 로그 ID

배송상태(status) 값

data.status와 각 events[].status는 아래 값 중 하나만 반환합니다. 택배사별 원문 문구는 carrierStatus에 그대로 담깁니다.

status

의미

INFO_RECEIVED

접수·발송준비·수거지정 등 집화 전 상태

PICKED_UP

집화 완료(상품 인수·수거 완료)

AT_ORIGIN

출발지 거점 도착/처리

IN_TRANSIT

이동 중(간선·터미널·상하차 등 운송 구간)

AT_HUB

허브·교환국 등 주요 거점 도착

AT_DESTINATION

배송지(도착지) 인근 거점 도착

OUT_FOR_DELIVERY

배송 출발(배달원 배송 중)

DELIVERED

배달 완료

DELIVERY_FAILED

배달 실패·미배달(부재 등)

EXCEPTION

예외 상황(취소·분실·지연·사고 등)

RETURNING

반송 진행 중

RETURNED

반송 완료

UNKNOWN

정규화 불가(원문 상태만 carrierStatus로 제공)

오류 코드(data.code) 값

배송정보를 찾지 못했거나 조회에 실패하면 data.error(안내 문구)와 data.code(오류 코드)가 담기며 과금되지 않습니다. data.code는 아래 값 중 하나입니다.

code

의미

INVALID_TRACKING_NUMBER

운송장번호 형식이 해당 택배사 규칙과 맞지 않음

UNSUPPORTED_CARRIER

지원하지 않거나 비활성인 carrier 코드

NOT_FOUND

해당 운송장 정보를 찾을 수 없음(미등록·오탈자 등)

UPSTREAM_TIMEOUT

택배사 시스템 응답 지연

UPSTREAM_NETWORK_ERROR

택배사 시스템 네트워크 오류

UPSTREAM_RATE_LIMITED

택배사 시스템이 요청을 제한함

UPSTREAM_BLOCKED

택배사 시스템이 요청을 차단함

UPSTREAM_UNAVAILABLE

택배사 시스템 일시 장애(5xx 등)

RESPONSE_CHANGED

택배사 응답 형식이 예상과 달라 해석 실패

PARSE_FAILED

응답 파싱 실패

LOGIN_REQUIRED

계정 로그인 없이는 조회할 수 없는 운송장

AUTH_REQUIRED

이름·전화번호 등 추가 본인확인 정보가 필요한 조회

PUBLIC_TRACKING_UNAVAILABLE

공개 운송장 조회를 제공하지 않는 택배사/서비스

INTERNAL_ERROR

서버 내부 오류

개인정보 보호를 위해 수취인 이름·전화번호·상세주소 등은 응답에 포함되지 않습니다.

경로별 응답 예시와 필드 명세는 위 API 요청 설명에 붙어 있습니다. JSON을 파일로 저장하기 전에는 Content-Type과 오류를 확인하세요.

상태·오류·재시도

HTTP 상태 → API 처리 여부 → 업무 상태 순서로 확인하세요. 결과 유무와 과금 여부는 서로 다릅니다.

서비스별 코드·조건 전체 보기

실시간 택배사 조회 상태

1시간 단위 자동 점검과 실제 사용자의 마지막 조회 결과를 Redis에 반영합니다. 운송장 미등록(NOT_FOUND)은 택배사 시스템의 정상 응답으로 판단하며, 연결·응답·파싱 오류가 발생한 택배사는 점검중으로 전환됩니다.

정상조회 가능 0개 점검중 40개 상태 확인 중

정상조회 가능한 택배사

No

택배사

carrier 코드

상태

-

상태 확인 중입니다.

-

확인 중

점검중인 택배사

No

택배사

carrier 코드

상태

1

CJ대한통운

cj

확인 중

2

한진택배

hanjin

확인 중

3

롯데글로벌로지스

lotte

확인 중

4

로젠택배

logen

확인 중

5

우체국 국내등기/소포

epost_domestic

확인 중

6

경동택배

kdexp

확인 중

7

일양로지스

ilyang

확인 중

8

컬리넥스트마일

kurlynextmile

확인 중

9

딜리박스

dbox

확인 중

10

CU편의점택배

cu_postbox

확인 중

11

대신택배

daesin

확인 중

12

SLX택배

slx

확인 중

13

우리택배

woori_delivery

확인 중

14

용마로지스

yongma

확인 중

15

레터스

letus

확인 중

16

두발히어로

doobalhero

확인 중

17

지니고 당일배송

geniego

확인 중

18

핑퐁

pingpong

확인 중

19

천일택배

chunil

확인 중

20

건영택배

kunyoung

확인 중

21

농협택배

nhlogis

확인 중

22

위니온택배

winionlogis

확인 중

23

합동택배

hdexp

확인 중

24

카카오T당일배송

todaypickup

확인 중

25

라스트마일

onedaylogis

확인 중

26

발렉스 특수물류

valex

확인 중

27

딜리래빗

drabbit

확인 중

28

성화기업택배

sunghwa

확인 중

29

EMS 국제우편

ems_international

확인 중

30

Cainiao(차이나/알리·테무 배후물류)

cainiao_global

확인 중

31

LX판토스 국제특송

lx_pantos

확인 중

32

ACT&CORE 해상수입

actcore_ocean

확인 중

33

일본우편(Japan Post)

japan_post

확인 중

34

야마토운수(일본)

yamato_japan

확인 중

35

사가와급편(일본)

sagawa_japan

확인 중

36

TNT Express

tnt

확인 중

37

YunExpress

yunexpress

확인 중

38

4PX Express

four_px

확인 중

39

EFS

efs

확인 중

40

eParcel

eparcel

확인 중

공통 폼 입력 오류

FORM_DATA_INVALID · HTTP 400: 필드 이름·타입·배열 인덱스를 확인하세요. 인덱스는 0부터 연속으로 사용합니다.

FORM_DATA_FIELD_CONFLICT · HTTP 400: 같은 값과 중첩 경로를 동시에 지정하지 마세요.

MULTIPART_LIMIT_OR_PARSE_ERROR · HTTP 400/413: boundary·파일 크기·필드 개수를 확인하세요. 서비스별 제한이 우선 적용됩니다.

요금·제한·이용 조건

기능·제공 범위·요금·제한 전체 보기

자동조회 사용 시 주의사항

국내 운송장번호와의 오인식을 막기 위해 일본 택배사의 숫자 10자리와 12자리는 자동조회 대상에서 제외합니다. 사가와급편은 carrier=sagawa_japan, 야마토운수는 carrier=yamato_japan, 일본우편 숫자 12자리는 carrier=japan_post를 지정해 호출하세요. 일본우편 숫자 11/13자리와 UPU S10 형식은 자동조회할 수 있습니다.

CAPTCHA 검증값을 요구하는 SF Express와 ECMS, 별도 제외 요청된 롯데 국제조회는 목록과 1시간 상태 점검에 포함하지 않습니다.

비용

엔드포인트

비용

설명

택배사 지정조회
/rest/parcel_tracking

5pt

carrier + trackingNumber 지정 조회

택배사 자동조회
/rest/parcel_tracking_auto

10pt

최대 5개 후보 택배사 동시 조회

택배사 목록 조회
/rest/parcel_tracking_carriers

무료

파라미터 없이 정상조회 가능·점검중 택배사 목록 조회

택배사 조회에 실패(배송정보 없음, 택배사 시스템 오류 등)하면 과금되지 않습니다.

Method

URL

POST

https://apick.app/rest/parcel_tracking

POST

https://apick.app/rest/parcel_tracking_auto

POST

https://apick.app/rest/parcel_tracking_carriers

GET

https://apick.app/parcel_tracking/status

연동 시 확인할 내용

예제는 경로별로 최소 요청과 오류 처리 포함 모드를 제공합니다. 실제 사용 환경의 시간 제한·취소·업무 성공 판정을 적용하세요.

추가 예제·서비스별 연동 안내

요청 예시 — 택배사 지정조회

form-data 전체 예제 보기

요청 예시 — 택배사 자동조회

form-data 전체 예제 보기

응답 예시


{
    "data": {
        "carrier": { "code": "cj", "name": "CJ대한통운" },
        "trackingNumber": "123456789012",
        "status": "DELIVERED",
        "carrierStatus": "배달완료",
        "events": [
            { "time": "2026-08-01T09:00:00+09:00", "location": "서울", "status": "PICKED_UP", "carrierStatus": "집화완료", "description": "집화완료" },
            { "time": "2026-08-02T14:00:00+09:00", "location": "서울", "status": "DELIVERED", "carrierStatus": "배달완료", "description": "배달완료" }
        ],
        "success": 1
    },
    "api": {
        "success": true,
        "cost": 5,
        "ms": 1820,
        "pl_id": 1595644
    }
}

기능·제공 범위

빠른 시작

요청과 응답

1. API 요청

입력 항목

응답과 성공 판정

2. API 요청

입력 항목

응답과 성공 판정

3. API 요청

입력 항목

응답과 성공 판정

Header

응답 상세

택배사 상태·목록 API

Body — 조회 성공 시

배송상태(status) 값

오류 코드(data.code) 값

상태·오류·재시도

실시간 택배사 조회 상태

정상조회 가능한 택배사

점검중인 택배사

요금·제한·이용 조건

자동조회 사용 시 주의사항

비용

연동 시 확인할 내용

요청 예시 — 택배사 지정조회

요청 예시 — 택배사 자동조회

응답 예시

개발가이드 검색

AI•LLM

전체상품

API 체험하기

요금정책

고객지원

개발가이드