# 택배 배송조회



국내 택배부터 일본·중국·유럽 국제배송까지 하나의 형식으로 배송현황을 조회합니다. 호출할 때마다 그 시점의 최신 배송현황을 돌려주며, 운송장번호만 있고 택배사를 모를 때는 자동조회(/rest/parcel_tracking_auto)를 쓰면 됩니다.



인증: Authorization: Bearer $APICK_API_KEY

본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다.

인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다.



## POST /rest/parcel_tracking 응답 필드

- `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

- `data.carrier` (object): 택배사 정보 묶음입니다. 택배사 코드와 표시 이름을 함께 제공하며, 코드는 이후 배송 조회 요청의 carrier 값으로 사용합니다.

- `data.carrier.code` (string): 택배사를 구분하는 코드입니다. 예: cj, hanjin, lotte. 같은 택배사는 조회마다 같은 코드로 오며, 배송 조회 요청의 carrier에 그대로 넣습니다.

- `data.carrier.name` (string): 택배사의 표시 이름입니다. 고객 화면에 보여 줄 이름이며, 코드와 달리 표기가 바뀔 수 있습니다.

- `data.trackingNumber` (string): 하이픈을 빼고 대문자로 맞춘 운송장번호입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.status` (string): 현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다.

- `data.carrierStatus` (string): 택배사가 표시한 상태 문구 그대로입니다. 예: 배달완료. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.queriedAt` (string): 조회 시각(ISO 8601)입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.lastEvent` (object): 가장 최근 배송 이력입니다. 이력이 없으면 null입니다. 항목 구조는 events[]와 같습니다. null 허용.

- `data.lastEvent.time` (string): 'time' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.lastEvent.location` (string): 위치·지역 정보입니다. 제공되지 않으면 null이거나 생략됩니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.lastEvent.status` (string): 현재 처리 상태입니다. 서비스별 상태 값과 다음 행동은 같은 문서의 상태 표를 확인하세요.

- `data.lastEvent.carrierStatus` (string): 'carrierStatus' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.lastEvent.description` (string): 대상의 설명문입니다. 게시자·서비스가 작성한 소개문이며, 줄바꿈과 이모지가 포함될 수 있습니다. 비어 있으면 설명이 등록되지 않은 것입니다.

- `data.events` (array): 배송 이벤트 목록입니다. 오래된 순서에서 최신 순서로 정렬되며, 이벤트가 없으면 빈 배열입니다.

- `data.events[].time` (string): 배송 이벤트가 발생한 시각입니다. 한국시간 ISO 8601 형식이며, 이벤트는 오래된 순서에서 최신 순서로 정렬됩니다.

- `data.events[].location` (string): 이벤트를 처리한 지점·지역입니다. 택배사가 제공하지 않으면 null이거나 생략됩니다.

- `data.events[].status` (string): 정규화된 배송 상태입니다. 택배사마다 다른 원문 문구를 공통 값으로 변환한 결과입니다. 가능한 값은 13가지입니다. UNKNOWN = 판별 불가, INFO_RECEIVED = 운송장 접수, PICKED_UP = 집화 완료, AT_ORIGIN = 출발 영업소 도착, IN_TRANSIT = 간선 이동 중, AT_HUB = 중간 허브 도착, AT_DESTINATION = 배송지 영업소 도착, OUT_FOR_DELIVERY = 배송 출발, DELIVERED = 배송 완료, DELIVERY_FAILED = 수취 실패, EXCEPTION = 분실·파손·주소 오류 등 예외, RETURNING = 반송 중, RETURNED = 반송 완료입니다. carrierStatus에는 택배사 원문이 그대로 오므로 두 값을 함께 보세요.

- `data.events[].carrierStatus` (string): 택배사가 표시한 원문 상태 문구입니다. 정규화 값과 함께 보관하면 문의 대응에 도움이 됩니다.

- `data.events[].description` (string): 이벤트 상세 설명입니다. 원문 상태와 같은 문구가 오는 경우가 많습니다.

- `data.success` (integer): 업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.

- `data.requestedCarrier` (object): 요청한 택배사가 다른 택배사에 배송을 맡긴 경우에만 옵니다. 요청한 택배사 {code, name}입니다.

- `data.actualCarrier` (object): 위 경우 실제로 배송하는 택배사입니다. 하위 필드에 코드·이름·상태 같은 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다.

- `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

- `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

- `api.cost` (integer): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

- `api.ms` (integer): 서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.

- `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

## API 요청: POST /rest/parcel_tracking



### 입력

- `carrier` (string, 필수): 택배사 코드 (예: cj, hanjin, lotte, logen, epost-domestic)

- `trackingNumber` (string, 필수): 조회할 운송장번호입니다. 택배사별 자릿수·형식이 다르며, 하이픈 없이 숫자만 입력하는 것을 권장합니다.



### 응답 명세

```json

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "carrier": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          },
          "description": "조회한 택배사 {code, name}입니다. 자동조회에서는 판별된 택배사입니다."
        },
        "trackingNumber": {
          "type": "string",
          "description": "하이픈을 빼고 대문자로 맞춘 운송장번호입니다."
        },
        "status": {
          "type": "string",
          "description": "표준 배송상태입니다. 아래 \"배송상태(status) 값\" 표를 보세요."
        },
        "carrierStatus": {
          "type": "string",
          "description": "택배사가 표시한 상태 문구 그대로입니다. 예: 배달완료."
        },
        "queriedAt": {
          "type": "string",
          "description": "조회 시각(ISO 8601)입니다."
        },
        "lastEvent": {
          "type": "object",
          "properties": {
            "time": {
              "type": "string"
            },
            "location": {
              "type": "string"
            },
            "status": {
              "type": "string"
            },
            "carrierStatus": {
              "type": "string"
            },
            "description": {
              "type": "string"
            }
          },
          "description": "가장 최근 배송 이력입니다. 이력이 없으면 null입니다. 항목 구조는 events[]와 같습니다.",
          "nullable": true
        },
        "events": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "time": {
                "type": "string",
                "description": "처리 시각(ISO 8601)입니다."
              },
              "location": {
                "type": "string",
                "description": "처리 장소입니다."
              },
              "status": {
                "type": "string",
                "description": "그 시점의 표준 배송상태입니다."
              },
              "carrierStatus": {
                "type": "string",
                "description": "택배사 상태 문구입니다."
              },
              "description": {
                "type": "string",
                "description": "이력 설명입니다."
              }
            }
          },
          "description": "배송 이력입니다. 오래된 순에서 최신 순으로 정렬됩니다."
        },
        "success": {
          "type": "integer",
          "description": "1이면 조회 성공(과금)입니다."
        },
        "requestedCarrier": {
          "type": "object",
          "description": "요청한 택배사가 다른 택배사에 배송을 맡긴 경우에만 옵니다. 요청한 택배사 {code, name}입니다."
        },
        "actualCarrier": {
          "type": "object",
          "description": "위 경우 실제로 배송하는 택배사입니다."
        }
      }
    },
    "api": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "cost": {
          "type": "integer",
          "description": "차감된 포인트입니다. 실패하면 0입니다."
        },
        "ms": {
          "type": "integer"
        },
        "pl_id": {
          "type": "integer",
          "description": "결제 기록 번호입니다. 문의할 때 함께 알려 주세요."
        }
      }
    }
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "carrier": {
      "code": "cj",
      "name": "CJ대한통운"
    },
    "trackingNumber": "123456789012",
    "status": "DELIVERED",
    "carrierStatus": "배달완료",
    "queriedAt": "2026-08-02T15:00:00.000Z",
    "lastEvent": {
      "time": "2026-08-02T14:00:00+09:00",
      "location": "서울",
      "status": "DELIVERED",
      "carrierStatus": "배달완료",
      "description": "배달완료"
    },
    "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
  }
}

```

### curl

```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 (서버 ESM)

```javascript

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

```python

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

```php

<?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);

```

## POST /rest/parcel_tracking_auto 응답 필드

- `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

- `data.carrier` (object): 택배사 정보 묶음입니다. 택배사 코드와 표시 이름을 함께 제공하며, 코드는 이후 배송 조회 요청의 carrier 값으로 사용합니다.

- `data.carrier.code` (string): 택배사를 구분하는 코드입니다. 예: cj, hanjin, lotte. 같은 택배사는 조회마다 같은 코드로 오며, 배송 조회 요청의 carrier에 그대로 넣습니다.

- `data.carrier.name` (string): 택배사의 표시 이름입니다. 고객 화면에 보여 줄 이름이며, 코드와 달리 표기가 바뀔 수 있습니다.

- `data.trackingNumber` (string): 하이픈을 빼고 대문자로 맞춘 운송장번호입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.status` (string): 현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다.

- `data.carrierStatus` (string): 택배사가 표시한 상태 문구 그대로입니다. 예: 배달완료. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.queriedAt` (string): 조회 시각(ISO 8601)입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.lastEvent` (object): 가장 최근 배송 이력입니다. 이력이 없으면 null입니다. 항목 구조는 events[]와 같습니다. null 허용.

- `data.lastEvent.time` (string): 'time' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.lastEvent.location` (string): 위치·지역 정보입니다. 제공되지 않으면 null이거나 생략됩니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.lastEvent.status` (string): 현재 처리 상태입니다. 서비스별 상태 값과 다음 행동은 같은 문서의 상태 표를 확인하세요.

- `data.lastEvent.carrierStatus` (string): 'carrierStatus' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.lastEvent.description` (string): 대상의 설명문입니다. 게시자·서비스가 작성한 소개문이며, 줄바꿈과 이모지가 포함될 수 있습니다. 비어 있으면 설명이 등록되지 않은 것입니다.

- `data.events` (array): 배송 이벤트 목록입니다. 오래된 순서에서 최신 순서로 정렬되며, 이벤트가 없으면 빈 배열입니다.

- `data.events[].time` (string): 배송 이벤트가 발생한 시각입니다. 한국시간 ISO 8601 형식이며, 이벤트는 오래된 순서에서 최신 순서로 정렬됩니다.

- `data.events[].location` (string): 이벤트를 처리한 지점·지역입니다. 택배사가 제공하지 않으면 null이거나 생략됩니다.

- `data.events[].status` (string): 정규화된 배송 상태입니다. 택배사마다 다른 원문 문구를 공통 값으로 변환한 결과입니다. 가능한 값은 13가지입니다. UNKNOWN = 판별 불가, INFO_RECEIVED = 운송장 접수, PICKED_UP = 집화 완료, AT_ORIGIN = 출발 영업소 도착, IN_TRANSIT = 간선 이동 중, AT_HUB = 중간 허브 도착, AT_DESTINATION = 배송지 영업소 도착, OUT_FOR_DELIVERY = 배송 출발, DELIVERED = 배송 완료, DELIVERY_FAILED = 수취 실패, EXCEPTION = 분실·파손·주소 오류 등 예외, RETURNING = 반송 중, RETURNED = 반송 완료입니다. carrierStatus에는 택배사 원문이 그대로 오므로 두 값을 함께 보세요.

- `data.events[].carrierStatus` (string): 택배사가 표시한 원문 상태 문구입니다. 정규화 값과 함께 보관하면 문의 대응에 도움이 됩니다.

- `data.events[].description` (string): 이벤트 상세 설명입니다. 원문 상태와 같은 문구가 오는 경우가 많습니다.

- `data.success` (integer): 업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.

- `data.requestedCarrier` (object): 요청한 택배사가 다른 택배사에 배송을 맡긴 경우에만 옵니다. 요청한 택배사 {code, name}입니다.

- `data.actualCarrier` (object): 위 경우 실제로 배송하는 택배사입니다. 하위 필드에 코드·이름·상태 같은 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다.

- `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

- `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

- `api.cost` (integer): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

- `api.ms` (integer): 서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.

- `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

## API 요청: POST /rest/parcel_tracking_auto



### 입력

- `trackingNumber` (string, 필수): 조회할 운송장번호입니다. 택배사별 자릿수·형식이 다르며, 하이픈 없이 숫자만 입력하는 것을 권장합니다.



### 응답 명세

```json

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "carrier": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          },
          "description": "조회한 택배사 {code, name}입니다. 자동조회에서는 판별된 택배사입니다."
        },
        "trackingNumber": {
          "type": "string",
          "description": "하이픈을 빼고 대문자로 맞춘 운송장번호입니다."
        },
        "status": {
          "type": "string",
          "description": "표준 배송상태입니다. 아래 \"배송상태(status) 값\" 표를 보세요."
        },
        "carrierStatus": {
          "type": "string",
          "description": "택배사가 표시한 상태 문구 그대로입니다. 예: 배달완료."
        },
        "queriedAt": {
          "type": "string",
          "description": "조회 시각(ISO 8601)입니다."
        },
        "lastEvent": {
          "type": "object",
          "properties": {
            "time": {
              "type": "string"
            },
            "location": {
              "type": "string"
            },
            "status": {
              "type": "string"
            },
            "carrierStatus": {
              "type": "string"
            },
            "description": {
              "type": "string"
            }
          },
          "description": "가장 최근 배송 이력입니다. 이력이 없으면 null입니다. 항목 구조는 events[]와 같습니다.",
          "nullable": true
        },
        "events": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "time": {
                "type": "string",
                "description": "처리 시각(ISO 8601)입니다."
              },
              "location": {
                "type": "string",
                "description": "처리 장소입니다."
              },
              "status": {
                "type": "string",
                "description": "그 시점의 표준 배송상태입니다."
              },
              "carrierStatus": {
                "type": "string",
                "description": "택배사 상태 문구입니다."
              },
              "description": {
                "type": "string",
                "description": "이력 설명입니다."
              }
            }
          },
          "description": "배송 이력입니다. 오래된 순에서 최신 순으로 정렬됩니다."
        },
        "success": {
          "type": "integer",
          "description": "1이면 조회 성공(과금)입니다."
        },
        "requestedCarrier": {
          "type": "object",
          "description": "요청한 택배사가 다른 택배사에 배송을 맡긴 경우에만 옵니다. 요청한 택배사 {code, name}입니다."
        },
        "actualCarrier": {
          "type": "object",
          "description": "위 경우 실제로 배송하는 택배사입니다."
        }
      }
    },
    "api": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "cost": {
          "type": "integer",
          "description": "차감된 포인트입니다. 실패하면 0입니다."
        },
        "ms": {
          "type": "integer"
        },
        "pl_id": {
          "type": "integer",
          "description": "결제 기록 번호입니다. 문의할 때 함께 알려 주세요."
        }
      }
    }
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "carrier": {
      "code": "cj",
      "name": "CJ대한통운"
    },
    "trackingNumber": "123456789012",
    "status": "DELIVERED",
    "carrierStatus": "배달완료",
    "queriedAt": "2026-08-02T15:00:00.000Z",
    "lastEvent": {
      "time": "2026-08-02T14:00:00+09:00",
      "location": "서울",
      "status": "DELIVERED",
      "carrierStatus": "배달완료",
      "description": "배달완료"
    },
    "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
  }
}

```

### curl

```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 (서버 ESM)

```javascript

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

```python

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

```php

<?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);

```

## POST /rest/parcel_tracking_carriers 응답 필드

- `success` (boolean): 목록 조회 성공 여부. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 해당 처리가 정상 완료된 경우, false = 실패·대상 없음으로 결과를 쓸 수 없는 경우입니다.

- `updatedAt` (string): 목록의 최근 갱신 시각. ISO 8601 일시. 이력이 없으면 null. null 허용.

- `summary` (object): 택배사 상태를 한눈에 보여 주는 요약 집계입니다. 전체·조회 가능·점검 중인 택배사 수를 담으며, 개별 목록은 아래 배열에서 확인하세요.

- `summary.total` (integer): 상태 집계 대상 택배사의 전체 수입니다. 조회 가능·점검 중인 수를 합한 값과 일치합니다.

- `summary.active` (integer): 현재 정상적으로 배송 조회를 지원하는 택배사 수입니다. 전체 중 점검·확인 중인 곳을 제외한 값입니다.

- `summary.maintenance` (integer): 점검·확인 중이어서 일시적으로 조회가 제한된 택배사 수입니다. 0이면 모든 택배사가 정상입니다.

- `activeCarriers` (array): 현재 조회 가능한 택배사 목록입니다. 각 항목의 코드·이름·별칭을 함께 제공하며, 없으면 빈 배열입니다.

- `activeCarriers[].code` (string): 택배사 코드. 지정 조회의 carrier에 사용합니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `activeCarriers[].name` (string): 택배사 표시 이름. 대상의 표시 이름입니다. 같은 API에서도 사람·상품·채널 이름을 뜻할 수 있습니다.

- `activeCarriers[].aliases` (array): 같은 택배사를 가리키는 다른 이름 목록입니다. 고객이 입력한 이름이 별칭과 일치하면 같은 택배사로 매핑할 수 있습니다.

- `activeCarriers[].serviceType` (string): 택배사의 배송 서비스 분류입니다. 택배·화물·국제 등 서비스 범위를 구분합니다.

- `activeCarriers[].lookupType` (string): 배송 조회에 필요한 입력 방식입니다. 운송장번호만으로 조회되는지, 택배사 코드가 필요한지 나타냅니다.

- `activeCarriers[].publicTracking` (boolean): 택배사가 고객용 배송 조회 페이지를 공개하는지 여부입니다. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 택배사가 고객용 배송 조회 페이지를 공개한 경우, false = 택배사가 공개 배송 조회 페이지를 제공하지 않는 경우입니다.

- `activeCarriers[].status` (string): ACTIVE=조회 가능, MAINTENANCE=점검 중, CHECKING=확인 중, UNAVAILABLE=상태 정보 없음. 가능한 값은 4가지입니다. ACTIVE = 정상 조회 가능한 상태입니다. 바로 요청할 수 있습니다. MAINTENANCE = 점검 중이라 조회할 수 없는 상태입니다. 복구된 뒤 같은 요청으로 다시 확인합니다. CHECKING = 상태를 확인 중인 값입니다. 잠시 후 같은 요청으로 다시 조회합니다. UNAVAILABLE = 상태 정보를 얻지 못한 값입니다. 일시 장애일 수 있으므로 재시도하고, 계속되면 문의하세요. 허용값: ACTIVE, MAINTENANCE, CHECKING, UNAVAILABLE

- `activeCarriers[].available` (boolean): 현재 이 택배사의 조회가 가능한지 여부입니다. false면 점검 중이거나 일시적으로 조회할 수 없는 상태입니다. true = 지금 조회 가능한 경우, false = 점검 등으로 지금은 조회할 수 없는 경우입니다.

- `activeCarriers[].stale` (boolean): 택배사 상태 정보가 갱신 기준 시간을 넘겼는지 여부입니다. true면 표시된 상태가 오래되었을 수 있습니다. true = 상태 정보가 갱신 기준 시간을 넘겨 오래된 경우, false = 최신 상태인 경우입니다.

- `activeCarriers[].checkedAt` (string): 최근 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `activeCarriers[].lastSuccessAt` (string): 최근 정상 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `activeCarriers[].lastFailureAt` (string): 최근 실패 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `activeCarriers[].errorCode` (string): 최근 상태 확인 코드. 문제가 없거나 이력이 없으면 null. 알려지지 않은 코드도 처리하세요. null 허용.

- `activeCarriers[].source` (string): 상태가 마지막으로 갱신된 방식의 구분값. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `maintenanceCarriers` (array): 점검·확인 중인 택배사 목록입니다. 조회가 제한된 기간에는 이 목록에만 나타날 수 있습니다.

- `maintenanceCarriers[].code` (string): 택배사 코드. 지정 조회의 carrier에 사용합니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `maintenanceCarriers[].name` (string): 택배사 표시 이름. 대상의 표시 이름입니다. 같은 API에서도 사람·상품·채널 이름을 뜻할 수 있습니다.

- `maintenanceCarriers[].aliases` (array): 점검 중인 택배사의 별칭 목록입니다. 고객 입력 이름을 정규화할 때 사용하세요.

- `maintenanceCarriers[].serviceType` (string): 점검 중인 택배사의 배송 서비스 분류입니다. 정상 복구 후 activeCarriers에서 다시 확인하세요.

- `maintenanceCarriers[].lookupType` (string): 점검 중인 택배사의 조회 입력 방식입니다. 복구 후에도 같은 방식으로 조회합니다.

- `maintenanceCarriers[].publicTracking` (boolean): 점검 중인 택배사의 공개 조회 페이지 제공 여부입니다. false면 고객 안내에 자체 조회 화면을 쓰세요. true = 택배사가 고객용 배송 조회 페이지를 공개한 경우, false = 택배사가 공개 배송 조회 페이지를 제공하지 않는 경우입니다.

- `maintenanceCarriers[].status` (string): ACTIVE=조회 가능, MAINTENANCE=점검 중, CHECKING=확인 중, UNAVAILABLE=상태 정보 없음. 가능한 값은 4가지입니다. ACTIVE = 정상 조회 가능한 상태입니다. 바로 요청할 수 있습니다. MAINTENANCE = 점검 중이라 조회할 수 없는 상태입니다. 복구된 뒤 같은 요청으로 다시 확인합니다. CHECKING = 상태를 확인 중인 값입니다. 잠시 후 같은 요청으로 다시 조회합니다. UNAVAILABLE = 상태 정보를 얻지 못한 값입니다. 일시 장애일 수 있으므로 재시도하고, 계속되면 문의하세요. 허용값: ACTIVE, MAINTENANCE, CHECKING, UNAVAILABLE

- `maintenanceCarriers[].available` (boolean): 점검 중인 택배사의 현재 조회 가능 여부입니다. 점검 중에는 false입니다. true = 지금 조회 가능한 경우, false = 점검 등으로 지금은 조회할 수 없는 경우입니다.

- `maintenanceCarriers[].stale` (boolean): 점검 중인 택배사의 상태 정보가 갱신 기준을 넘겼는지 여부입니다. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 상태 정보가 갱신 기준 시간을 넘겨 오래된 경우, false = 최신 상태인 경우입니다.

- `maintenanceCarriers[].checkedAt` (string): 최근 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `maintenanceCarriers[].lastSuccessAt` (string): 최근 정상 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `maintenanceCarriers[].lastFailureAt` (string): 최근 실패 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `maintenanceCarriers[].errorCode` (string): 최근 상태 확인 코드. 문제가 없거나 이력이 없으면 null. 알려지지 않은 코드도 처리하세요. null 허용.

- `maintenanceCarriers[].source` (string): 상태가 마지막으로 갱신된 방식의 구분값. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `carriers` (array): 전체 택배사 목록. 상태 집계 대상 밖의 항목은 UNAVAILABLE일 수 있습니다.

- `carriers[].code` (string): 택배사 코드. 지정 조회의 carrier에 사용합니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `carriers[].name` (string): 택배사 표시 이름. 대상의 표시 이름입니다. 같은 API에서도 사람·상품·채널 이름을 뜻할 수 있습니다.

- `carriers[].aliases` (array): 같은 택배사를 가리키는 이름 목록. 각 항목의 구성은 서비스에 따라 다르며, 값이 없으면 빈 배열입니다. 항목 수와 순서를 함께 확인하세요.

- `carriers[].serviceType` (string): 배송 서비스 분류. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `carriers[].lookupType` (string): 조회 유형. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `carriers[].publicTracking` (boolean): 공개 배송 조회 지원 여부. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 택배사가 고객용 배송 조회 페이지를 공개한 경우, false = 택배사가 공개 배송 조회 페이지를 제공하지 않는 경우입니다.

- `carriers[].status` (string): ACTIVE=조회 가능, MAINTENANCE=점검 중, CHECKING=확인 중, UNAVAILABLE=상태 정보 없음. 가능한 값은 4가지입니다. ACTIVE = 정상 조회 가능한 상태입니다. 바로 요청할 수 있습니다. MAINTENANCE = 점검 중이라 조회할 수 없는 상태입니다. 복구된 뒤 같은 요청으로 다시 확인합니다. CHECKING = 상태를 확인 중인 값입니다. 잠시 후 같은 요청으로 다시 조회합니다. UNAVAILABLE = 상태 정보를 얻지 못한 값입니다. 일시 장애일 수 있으므로 재시도하고, 계속되면 문의하세요. 허용값: ACTIVE, MAINTENANCE, CHECKING, UNAVAILABLE

- `carriers[].available` (boolean): 현재 조회 가능한지 여부. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 지금 조회 가능한 경우, false = 점검 등으로 지금은 조회할 수 없는 경우입니다.

- `carriers[].stale` (boolean): 상태 정보가 갱신 기준을 넘겼는지 여부. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 상태 정보가 갱신 기준 시간을 넘겨 오래된 경우, false = 최신 상태인 경우입니다.

- `carriers[].checkedAt` (string): 최근 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `carriers[].lastSuccessAt` (string): 최근 정상 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `carriers[].lastFailureAt` (string): 최근 실패 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `carriers[].errorCode` (string): 최근 상태 확인 코드. 문제가 없거나 이력이 없으면 null. 알려지지 않은 코드도 처리하세요. null 허용.

## API 요청: POST /rest/parcel_tracking_carriers



### 입력



### 응답 명세

```json

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "목록 조회 성공 여부."
    },
    "updatedAt": {
      "type": "string",
      "description": "목록의 최근 갱신 시각. ISO 8601 일시. 이력이 없으면 null.",
      "nullable": true
    },
    "summary": {
      "type": "object",
      "properties": {
        "total": {
          "type": "integer",
          "description": "상태 집계 대상 택배사 수."
        },
        "active": {
          "type": "integer",
          "description": "조회 가능한 택배사 수."
        },
        "maintenance": {
          "type": "integer",
          "description": "점검·확인 중인 택배사 수."
        }
      },
      "description": "공개 조회 대상 상태 집계."
    },
    "activeCarriers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "택배사 코드. 지정 조회의 carrier에 사용합니다."
          },
          "name": {
            "type": "string",
            "description": "택배사 표시 이름."
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "대체 이름."
            },
            "description": "같은 택배사를 가리키는 이름 목록."
          },
          "serviceType": {
            "type": "string",
            "description": "배송 서비스 분류."
          },
          "lookupType": {
            "type": "string",
            "description": "조회 유형."
          },
          "publicTracking": {
            "type": "boolean",
            "description": "공개 배송 조회 지원 여부."
          },
          "status": {
            "type": "string",
            "description": "ACTIVE=조회 가능, MAINTENANCE=점검 중, CHECKING=확인 중, UNAVAILABLE=상태 정보 없음.",
            "enum": [
              "ACTIVE",
              "MAINTENANCE",
              "CHECKING",
              "UNAVAILABLE"
            ]
          },
          "available": {
            "type": "boolean",
            "description": "현재 조회 가능한지 여부."
          },
          "stale": {
            "type": "boolean",
            "description": "상태 정보가 갱신 기준을 넘겼는지 여부."
          },
          "checkedAt": {
            "type": "string",
            "description": "최근 확인 시각. ISO 8601 일시. 이력이 없으면 null.",
            "nullable": true
          },
          "lastSuccessAt": {
            "type": "string",
            "description": "최근 정상 확인 시각. ISO 8601 일시. 이력이 없으면 null.",
            "nullable": true
          },
          "lastFailureAt": {
            "type": "string",
            "description": "최근 실패 확인 시각. ISO 8601 일시. 이력이 없으면 null.",
            "nullable": true
          },
          "errorCode": {
            "type": "string",
            "description": "최근 상태 확인 코드. 문제가 없거나 이력이 없으면 null. 알려지지 않은 코드도 처리하세요.",
            "nullable": true
          },
          "source": {
            "type": "string",
            "description": "상태가 마지막으로 갱신된 방식의 구분값. 이력이 없으면 null.",
            "nullable": true
          }
        },
        "description": "택배사 상태."
      },
      "description": "ACTIVE 상태인 택배사 목록. 없으면 빈 배열."
    },
    "maintenanceCarriers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "택배사 코드. 지정 조회의 carrier에 사용합니다."
          },
          "name": {
            "type": "string",
            "description": "택배사 표시 이름."
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "대체 이름."
            },
            "description": "같은 택배사를 가리키는 이름 목록."
          },
          "serviceType": {
            "type": "string",
            "description": "배송 서비스 분류."
          },
          "lookupType": {
            "type": "string",
            "description": "조회 유형."
          },
          "publicTracking": {
            "type": "boolean",
            "description": "공개 배송 조회 지원 여부."
          },
          "status": {
            "type": "string",
            "description": "ACTIVE=조회 가능, MAINTENANCE=점검 중, CHECKING=확인 중, UNAVAILABLE=상태 정보 없음.",
            "enum": [
              "ACTIVE",
              "MAINTENANCE",
              "CHECKING",
              "UNAVAILABLE"
            ]
          },
          "available": {
            "type": "boolean",
            "description": "현재 조회 가능한지 여부."
          },
          "stale": {
            "type": "boolean",
            "description": "상태 정보가 갱신 기준을 넘겼는지 여부."
          },
          "checkedAt": {
            "type": "string",
            "description": "최근 확인 시각. ISO 8601 일시. 이력이 없으면 null.",
            "nullable": true
          },
          "lastSuccessAt": {
            "type": "string",
            "description": "최근 정상 확인 시각. ISO 8601 일시. 이력이 없으면 null.",
            "nullable": true
          },
          "lastFailureAt": {
            "type": "string",
            "description": "최근 실패 확인 시각. ISO 8601 일시. 이력이 없으면 null.",
            "nullable": true
          },
          "errorCode": {
            "type": "string",
            "description": "최근 상태 확인 코드. 문제가 없거나 이력이 없으면 null. 알려지지 않은 코드도 처리하세요.",
            "nullable": true
          },
          "source": {
            "type": "string",
            "description": "상태가 마지막으로 갱신된 방식의 구분값. 이력이 없으면 null.",
            "nullable": true
          }
        },
        "description": "택배사 상태."
      },
      "description": "ACTIVE 이외 상태인 택배사 목록. 없으면 빈 배열."
    },
    "carriers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "택배사 코드. 지정 조회의 carrier에 사용합니다."
          },
          "name": {
            "type": "string",
            "description": "택배사 표시 이름."
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "대체 이름."
            },
            "description": "같은 택배사를 가리키는 이름 목록."
          },
          "serviceType": {
            "type": "string",
            "description": "배송 서비스 분류."
          },
          "lookupType": {
            "type": "string",
            "description": "조회 유형."
          },
          "publicTracking": {
            "type": "boolean",
            "description": "공개 배송 조회 지원 여부."
          },
          "status": {
            "type": "string",
            "description": "ACTIVE=조회 가능, MAINTENANCE=점검 중, CHECKING=확인 중, UNAVAILABLE=상태 정보 없음.",
            "enum": [
              "ACTIVE",
              "MAINTENANCE",
              "CHECKING",
              "UNAVAILABLE"
            ]
          },
          "available": {
            "type": "boolean",
            "description": "현재 조회 가능한지 여부."
          },
          "stale": {
            "type": "boolean",
            "description": "상태 정보가 갱신 기준을 넘겼는지 여부."
          },
          "checkedAt": {
            "type": "string",
            "description": "최근 확인 시각. ISO 8601 일시. 이력이 없으면 null.",
            "nullable": true
          },
          "lastSuccessAt": {
            "type": "string",
            "description": "최근 정상 확인 시각. ISO 8601 일시. 이력이 없으면 null.",
            "nullable": true
          },
          "lastFailureAt": {
            "type": "string",
            "description": "최근 실패 확인 시각. ISO 8601 일시. 이력이 없으면 null.",
            "nullable": true
          },
          "errorCode": {
            "type": "string",
            "description": "최근 상태 확인 코드. 문제가 없거나 이력이 없으면 null. 알려지지 않은 코드도 처리하세요.",
            "nullable": true
          }
        },
        "description": "택배사 정보."
      },
      "description": "전체 택배사 목록. 상태 집계 대상 밖의 항목은 UNAVAILABLE일 수 있습니다."
    }
  },
  "description": "data·api 래퍼 없이 반환되는 택배사 목록. 서비스 준비 중에는 result.error와 api.success가 반환될 수 있습니다."
}

```

### curl

```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 (서버 ESM)

```javascript

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

```python

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

```php

<?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);

```

## 사용 예시 1. 택배사를 알 때 지정조회

주문 시스템에 택배사 코드가 저장돼 있으면 지정조회가 빠르고 저렴합니다.

```bash

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'

```

- `data.status`가 `DELIVERED`이면 배송 완료 처리합니다. 화면 문구는 `data.carrierStatus`를 씁니다.

- `data.lastEvent`로 최근 위치·시각을 한 줄로 보여 줄 수 있습니다.

## 사용 예시 2. 우체국 택배 조회

택배사 코드는 목록 조회 결과의 `code` 값을 그대로 씁니다.

```bash

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

```

- `data.code`가 `NOT_FOUND`이면 발송 직후일 수 있으니 몇 시간 뒤 다시 조회합니다(과금 없음).

## 사용 예시 3. 택배사를 모를 때 자동조회

사용자가 운송장번호만 입력한 경우 택배사를 판별해 조회합니다.

```bash

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

```

- 판별된 택배사는 `data.carrier.code`에 담깁니다. 저장해 두고 다음부터는 지정조회를 씁니다.

- `data.code`가 `UNSUPPORTED_CARRIER`이면 택배사를 사용자에게 고르게 한 뒤 지정조회합니다.

## 사용 예시 4. 국제우편 번호 자동조회

국제우편 형식(영문 2자 + 숫자 9자 + 국가코드 2자)은 자동조회로 판별됩니다.

```bash

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

```

- 일본 택배사의 숫자 10·12자리 번호는 자동조회되지 않으므로 `carrier=yamato_japan`·`japan_post`로 지정조회합니다.

## 코드·오류

### 업무 실패 응답

입력 오류·대상 없음·일시 실패는 data.error(사유)와 data.success=0으로 오며 api.cost는 0(과금 없음)입니다. HTTP 상태는 400·404·408·424 중 하나입니다. 입력 오류는 값을 고쳐 다시 요청하고, 408·424는 잠시 후 한 번 다시 시도하세요.

```json

{
  "data": {
    "error": "입력값을 확인해 주세요.",
    "success": 0
  },
  "api": {
    "success": true,
    "cost": 0,
    "ms": 5
  }
}

```

## 상세 기능·요금

국내외 38개 택배사 지원 국내 택배·편의점·당일배송과 일본우편·TNT·4PX 등 해외배송을 한 API로 조회 통일된 배송상태 택배사마다 다른 상태 문구를 13가지 표준 상태값(status)으로 맞춰 제공 택배사 자동인식 운송장번호만으로 택배사를 판별해 조회 이용 전 확인 조회에 성공한 호출만 과금됩니다. 배송정보가 없거나 조회에 실패하면 data.error와 data.code로 응답하며 과금되지 않습니다. 택배사를 알면 지정조회(/rest/parcel_tracking)가 더 빠르고 저렴합니다. 자동조회는 택배사를 모를 때만 쓰세요. 국내 운송장번호와 헷갈리지 않도록 일본 택배사의 숫자 10자리·12자리 번호는 자동조회에서 판별하지 않습니다. 야마토운수는 carrier=yamato_japan, 일본우편 숫자 12자리는 carrier=japan_post를 지정해 호출하세요. 일본우편 숫자 11·13자리와 국제우편(UPU S10, 예: EE123456789JP) 형식은 자동조회할 수 있습니다. SF Express, ECMS, 롯데 국제조회는 현재 지원 목록에 없습니다. SF Express, ECMS, 롯데 국제조회는 지원하지 않습니다. (function () { function initializeParcelTrackingStatus() { var activeTarget = document.getElementById('parcel-active-carriers'); var maintenanceTarget = document.getElementById('parcel-maintenance-carriers'); if (!activeTarget || !maintenanceTarget) return; function appendCell(row, value, className) { var cell = document.createElement('div'); if (className) cell.className = className; cell.textContent = value; row.appendChild(cell); return cell; } function renderRows(target, carriers, active) { target.textContent = ''; if (!carriers.length) { var empty = document.createElement('div'); empty.className = 'turf-row parcel-status-empty'; appendCell(empty, '-'); appendCell(empty, active ? '현재 정상조회 가능한 택배사가 없습니다.' : '현재 점검중인 택배사가 없습니다.'); appendCell(empty, '-'); appendCell(empty, '-'); target.appendChild(empty); return; } carriers.forEach(function (carrier, index) { var row = document.createElement('div'); row.className = 'turf-row'; appendCell(row, String(index + 1)); appendCell(row, carrier.name || carrier.code); var codeCell = appendCell(row, ''); var code = document.createElement('code'); code.className = 'carrier-code'; code.textContent = carrier.code; codeCell.appendChild(code); var statusCell = appendCell(row, ''); var badge = document.createElement('span'); badge.className = 'parcel-status-badge ' + (active ? 'is-active' : 'is-maintenance'); badge.textContent = active ? '정상' : '점검중'; statusCell.appendChild(badge); target.appendChild(row); }); } function formatUpdatedAt(value) { if (!value) return '점검 결과 확인 중'; var date = new Date(value); if (Number.isNaN(date.getTime())) return '최근 상태 반영 완료'; return '최근 반영 ' + date.toLocaleString('ko-KR'); } function refresh() { fetch('/parcel_tracking/status', { credentials: 'same-origin', cache: 'no-store' }) .then(function (response) { if (!response.ok) throw new Error('STATUS_HTTP_' + response.status); return response.json(); }) .then(function (data) { if (!data || data.success !== true) throw new Error('STATUS_RESPONSE_INVALID'); var active = Array.isArray(data.activeCarriers) ? data.activeCarriers : []; var maintenance = Array.isArray(data.maintenanceCarriers) ? data.maintenanceCarriers : []; renderRows(activeTarget, active, true); renderRows(maintenanceTarget, maintenance, false); document.getElementById('parcel-active-count').textContent = String(active.length); document.getElementById('parcel-maintenance-count').textContent = String(maintenance.length); document.getElementById('parcel-status-updated-at').textContent = formatUpdatedAt(data.updatedAt); }) .catch(function () { document.getElementById('parcel-status-updated-at').textContent = '상태 정보를 불러오지 못했습니다.'; }); } refresh(); setInterval(refresh, 60 * 1000); } if (document.readyState === 'loading') { document.addEventListener('DOMContentLoaded', initializeParcelTrackingStatus, { once: true }); } else { initializeParcelTrackingStatus(); } })(); 비용 엔드포인트 비용 설명 택배사 지정조회/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

## 상세 요청

인증 헤더는 Authorization: Bearer 내 계정의 API 인증키입니다. 택배사 목록 조회(/rest/parcel_tracking_carriers)는 파라미터가 없고 무료입니다. 응답의 activeCarriers에는 지금 조회 가능한 택배사, maintenanceCarriers에는 점검중인 택배사가 담깁니다.

## 상세 응답

택배사 상태·목록 API 이름 타입 설명 updatedAtString|null가장 최근 상태 반영 시각 summaryObject전체·정상·점검중 택배사 수 activeCarriersArray현재 정상조회 가능한 택배사 목록 maintenanceCarriersArray점검중이거나 상태 확인 중인 택배사 목록 carriers[].statusStringACTIVE, MAINTENANCE, CHECKING, UNAVAILABLE carriers[].availableBoolean현재 정상조회 가능 여부 carriers[].checkedAtString|null해당 택배사의 최근 상태 반영 시각 배송 조회 응답(지정조회·자동조회 공통) 필드타입설명 data.carrierobject조회한 택배사 {code, name}입니다. 자동조회에서는 판별된 택배사입니다. data.trackingNumberstring하이픈을 빼고 대문자로 맞춘 운송장번호입니다. data.statusstring표준 배송상태입니다. 아래 "배송상태(status) 값" 표를 보세요. data.carrierStatusstring택배사가 표시한 상태 문구 그대로입니다. 예: 배달완료. data.queriedAtstring조회 시각(ISO 8601)입니다. data.lastEventobject가장 최근 배송 이력입니다. 이력이 없으면 null입니다. 항목 구조는 events[]와 같습니다. data.events[]array배송 이력입니다. 오래된 순에서 최신 순으로 정렬됩니다. data.events[].timestring처리 시각(ISO 8601)입니다. data.events[].locationstring처리 장소입니다. data.events[].statusstring그 시점의 표준 배송상태입니다. data.events[].carrierStatusstring택배사 상태 문구입니다. data.events[].descriptionstring이력 설명입니다. data.requestedCarrierobject요청한 택배사가 다른 택배사에 배송을 맡긴 경우에만 옵니다. 요청한 택배사 {code, name}입니다. data.actualCarrierobject위 경우 실제로 배송하는 택배사입니다. data.successinteger1이면 조회 성공(과금)입니다. api.costinteger차감된 포인트입니다. 실패하면 0입니다. api.pl_idinteger결제 기록 번호입니다. 문의할 때 함께 알려 주세요. 배송상태(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 코드이거나, 자동조회에서 택배사를 판별하지 못했습니다.택배사 목록의 code로 지정조회합니다. NOT_FOUND배송정보가 없습니다(아직 집화 전, 운송장 오탈자, 다른 택배사 등).번호와 택배사를 확인합니다. 발송 직후라면 몇 시간 뒤 다시 조회합니다. UPSTREAM_TIMEOUT택배사 응답이 늦어 조회하지 못했습니다.잠시 후 다시 조회합니다. UPSTREAM_NETWORK_ERROR일시적으로 택배사에 연결하지 못했습니다.잠시 후 다시 조회합니다. UPSTREAM_RATE_LIMITED택배사 조회가 일시적으로 제한됐습니다.몇 분 뒤 다시 조회합니다. 같은 번호를 짧은 간격으로 반복 조회하지 마세요. UPSTREAM_BLOCKED택배사 조회가 일시적으로 거부됐습니다.몇 분 뒤 다시 조회합니다. UPSTREAM_UNAVAILABLE택배사 조회 시스템이 일시적으로 응답하지 않습니다.택배사 상태 표를 확인하고 잠시 후 다시 조회합니다. RESPONSE_CHANGED일시적으로 결과를 읽지 못했습니다.잠시 후 다시 조회합니다. 계속되면 문의해 주세요. PARSE_FAILED일시적으로 결과를 읽지 못했습니다.잠시 후 다시 조회합니다. 계속되면 문의해 주세요. LOGIN_REQUIRED택배사 회원 로그인 후에만 볼 수 있는 운송장입니다.지원하지 않습니다. 택배사 앱·홈페이지에서 확인하도록 안내합니다. AUTH_REQUIRED이름·전화번호 같은 본인확인이 필요한 운송장입니다.지원하지 않습니다. 택배사 앱·홈페이지에서 확인하도록 안내합니다. PUBLIC_TRACKING_UNAVAILABLE공개 배송조회를 제공하지 않는 택배사·서비스입니다.지원하지 않습니다. INTERNAL_ERROR알 수 없는 이유로 실패했습니다.잠시 후 다시 조회합니다. 계속되면 문의해 주세요. 처음 보는 data.code가 와도 data.error가 있으면 실패로 처리하세요. 개인정보 보호를 위해 수취인 이름·전화번호·상세주소 등은 응답에 포함되지 않습니다.

## 상세 코드·정책

택배사별 현재 조회 상태 택배사별로 지금 조회할 수 있는지 보여 줍니다. 점검중인 택배사는 조회가 실패할 수 있으며, 실패한 호출은 과금되지 않습니다. 같은 목록을 /rest/parcel_tracking_carriers로 받아 화면에서 점검중인 택배사를 미리 안내할 수 있습니다. 정상조회 가능 0개 점검중 38개 상태 확인 중 정상조회 가능한 택배사 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 천일택배 chunil 확인 중 19 건영택배 kunyoung 확인 중 20 농협택배 nhlogis 확인 중 21 위니온택배 winionlogis 확인 중 22 합동택배 hdexp 확인 중 23 카카오T당일배송 todaypickup 확인 중 24 라스트마일 onedaylogis 확인 중 25 발렉스 특수물류 valex 확인 중 26 딜리래빗 drabbit 확인 중 27 성화기업택배 sunghwa 확인 중 28 EMS 국제우편 ems_international 확인 중 29 Cainiao(차이나/알리·테무 배후물류) cainiao_global 확인 중 30 LX판토스 국제특송 lx_pantos 확인 중 31 ACT&CORE 해상수입 actcore_ocean 확인 중 32 일본우편(Japan Post) japan_post 확인 중 33 야마토운수(일본) yamato_japan 확인 중 34 TNT Express tnt 확인 중 35 YunExpress yunexpress 확인 중 36 4PX Express four_px 확인 중 37 EFS efs 확인 중 38 eParcel eparcel 확인 중

## 상세 예제

요청 예시 — 택배사 지정조회 form-data 전체 예제 보기 요청 예시 — 택배사 자동조회 form-data 전체 예제 보기 응답 예시 { "data": { "carrier": { "code": "cj", "name": "CJ대한통운" }, "trackingNumber": "123456789012", "status": "DELIVERED", "carrierStatus": "배달완료", "queriedAt": "2026-08-02T15:00:00.000Z", "lastEvent": { "time": "2026-08-02T14:00:00+09:00", "location": "서울", "status": "DELIVERED", "carrierStatus": "배달완료", "description": "배달완료" }, "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 } }