# 택배 배송조회 국내 택배부터 일본·중국·유럽 국제배송까지 하나의 형식으로 실시간 배송현황을 조회합니다. 결과를 DB에 저장하지 않고 매 호출마다 택배사 시스템을 즉시 확인하며, 운송장번호만 있고 택배사를 모를 때는 자동조회(/rest/parcel_tracking_auto)를 이용할 수 있습니다. 인증: Authorization: Bearer $APICK_API_KEY 본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다. 인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다. ## POST /rest/parcel_tracking 응답 필드 - `data` (object): 조회 데이터 - `data.carrier` (object): 택배사 정보(code, name) - `data.carrier.code` (string): 아래 하위 항목을 확인하세요. - `data.carrier.name` (string): 아래 하위 항목을 확인하세요. - `data.trackingNumber` (string): 운송장번호 - `data.status` (string): 정규화된 배송상태. 아래 "배송상태(status) 값" 표 참고 - `data.carrierStatus` (string): 택배사 원문 상태 텍스트(예: "배달완료") - `data.events` (array): 배송 이력(오래된 순 → 최신 순). 각 항목: time, location, status, carrierStatus, description - `data.events[].time` (string): 아래 하위 항목을 확인하세요. - `data.events[].location` (string): 아래 하위 항목을 확인하세요. - `data.events[].status` (string): 아래 하위 항목을 확인하세요. - `data.events[].carrierStatus` (string): 아래 하위 항목을 확인하세요. - `data.events[].description` (string): 아래 하위 항목을 확인하세요. - `data.success` (integer): 과금 여부0: 실패(미과금)1: 성공(과금) - `api` (object): API 호출 공통 데이터 - `api.success` (boolean): API 서버 정상 응답 여부true: 서버가 요청을 정상 처리false: 서버 처리 실패 - `api.cost` (integer): API 호출 요금(포인트) - `api.ms` (integer): API 응답 시간(밀리초) - `api.pl_id` (integer): API 결제 로그 ID ## 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": "택배사 원문 상태 텍스트(예: \"배달완료\")" }, "events": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string" }, "location": { "type": "string" }, "status": { "type": "string" }, "carrierStatus": { "type": "string" }, "description": { "type": "string" } } }, "description": "배송 이력(오래된 순 → 최신 순). 각 항목: time, location, status, carrierStatus, description" }, "success": { "type": "integer", "description": "과금 여부0: 실패(미과금)1: 성공(과금)" } }, "description": "조회 데이터" }, "api": { "type": "object", "properties": { "success": { "type": "boolean", "description": "API 서버 정상 응답 여부true: 서버가 요청을 정상 처리false: 서버 처리 실패" }, "cost": { "type": "integer", "description": "API 호출 요금(포인트)" }, "ms": { "type": "integer", "description": "API 응답 시간(밀리초)" }, "pl_id": { "type": "integer", "description": "API 결제 로그 ID" } }, "description": "API 호출 공통 데이터" } } } ``` ### 정적 응답 예시 ```json { "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 } } ``` ### 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 '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): 조회 데이터 - `data.carrier` (object): 택배사 정보(code, name) - `data.carrier.code` (string): 아래 하위 항목을 확인하세요. - `data.carrier.name` (string): 아래 하위 항목을 확인하세요. - `data.trackingNumber` (string): 운송장번호 - `data.status` (string): 정규화된 배송상태. 아래 "배송상태(status) 값" 표 참고 - `data.carrierStatus` (string): 택배사 원문 상태 텍스트(예: "배달완료") - `data.events` (array): 배송 이력(오래된 순 → 최신 순). 각 항목: time, location, status, carrierStatus, description - `data.events[].time` (string): 아래 하위 항목을 확인하세요. - `data.events[].location` (string): 아래 하위 항목을 확인하세요. - `data.events[].status` (string): 아래 하위 항목을 확인하세요. - `data.events[].carrierStatus` (string): 아래 하위 항목을 확인하세요. - `data.events[].description` (string): 아래 하위 항목을 확인하세요. - `data.success` (integer): 과금 여부0: 실패(미과금)1: 성공(과금) - `api` (object): API 호출 공통 데이터 - `api.success` (boolean): API 서버 정상 응답 여부true: 서버가 요청을 정상 처리false: 서버 처리 실패 - `api.cost` (integer): API 호출 요금(포인트) - `api.ms` (integer): API 응답 시간(밀리초) - `api.pl_id` (integer): API 결제 로그 ID ## 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": "택배사 원문 상태 텍스트(예: \"배달완료\")" }, "events": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string" }, "location": { "type": "string" }, "status": { "type": "string" }, "carrierStatus": { "type": "string" }, "description": { "type": "string" } } }, "description": "배송 이력(오래된 순 → 최신 순). 각 항목: time, location, status, carrierStatus, description" }, "success": { "type": "integer", "description": "과금 여부0: 실패(미과금)1: 성공(과금)" } }, "description": "조회 데이터" }, "api": { "type": "object", "properties": { "success": { "type": "boolean", "description": "API 서버 정상 응답 여부true: 서버가 요청을 정상 처리false: 서버 처리 실패" }, "cost": { "type": "integer", "description": "API 호출 요금(포인트)" }, "ms": { "type": "integer", "description": "API 응답 시간(밀리초)" }, "pl_id": { "type": "integer", "description": "API 결제 로그 ID" } }, "description": "API 호출 공통 데이터" } } } ``` ### 정적 응답 예시 ```json { "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 } } ``` ### 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 '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): 목록 조회 성공 여부. - `updatedAt` (string): 목록의 최근 갱신 시각. ISO 8601 일시. 이력이 없으면 null. null 허용. - `summary` (object): 공개 조회 대상 상태 집계. - `summary.total` (integer): 상태 집계 대상 택배사 수. - `summary.active` (integer): 조회 가능한 택배사 수. - `summary.maintenance` (integer): 점검·확인 중인 택배사 수. - `activeCarriers` (array): ACTIVE 상태인 택배사 목록. 없으면 빈 배열. - `activeCarriers[].code` (string): 택배사 코드. 지정 조회의 carrier에 사용합니다. - `activeCarriers[].name` (string): 택배사 표시 이름. - `activeCarriers[].aliases` (array): 같은 택배사를 가리키는 이름 목록. - `activeCarriers[].serviceType` (string): 배송 서비스 분류. - `activeCarriers[].lookupType` (string): 조회 유형. - `activeCarriers[].publicTracking` (boolean): 공개 배송 조회 지원 여부. - `activeCarriers[].status` (string): ACTIVE=조회 가능, MAINTENANCE=점검 중, CHECKING=확인 중, UNAVAILABLE=상태 정보 없음. 허용값: ACTIVE, MAINTENANCE, CHECKING, UNAVAILABLE - `activeCarriers[].available` (boolean): 현재 조회 가능한지 여부. - `activeCarriers[].stale` (boolean): 상태 정보가 갱신 기준을 넘겼는지 여부. - `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): ACTIVE 이외 상태인 택배사 목록. 없으면 빈 배열. - `maintenanceCarriers[].code` (string): 택배사 코드. 지정 조회의 carrier에 사용합니다. - `maintenanceCarriers[].name` (string): 택배사 표시 이름. - `maintenanceCarriers[].aliases` (array): 같은 택배사를 가리키는 이름 목록. - `maintenanceCarriers[].serviceType` (string): 배송 서비스 분류. - `maintenanceCarriers[].lookupType` (string): 조회 유형. - `maintenanceCarriers[].publicTracking` (boolean): 공개 배송 조회 지원 여부. - `maintenanceCarriers[].status` (string): ACTIVE=조회 가능, MAINTENANCE=점검 중, CHECKING=확인 중, UNAVAILABLE=상태 정보 없음. 허용값: ACTIVE, MAINTENANCE, CHECKING, UNAVAILABLE - `maintenanceCarriers[].available` (boolean): 현재 조회 가능한지 여부. - `maintenanceCarriers[].stale` (boolean): 상태 정보가 갱신 기준을 넘겼는지 여부. - `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): 택배사 표시 이름. - `carriers[].aliases` (array): 같은 택배사를 가리키는 이름 목록. - `carriers[].serviceType` (string): 배송 서비스 분류. - `carriers[].lookupType` (string): 조회 유형. - `carriers[].publicTracking` (boolean): 공개 배송 조회 지원 여부. - `carriers[].status` (string): ACTIVE=조회 가능, MAINTENANCE=점검 중, CHECKING=확인 중, UNAVAILABLE=상태 정보 없음. 허용값: ACTIVE, MAINTENANCE, CHECKING, UNAVAILABLE - `carriers[].available` (boolean): 현재 조회 가능한지 여부. - `carriers[].stale` (boolean): 상태 정보가 갱신 기준을 넘겼는지 여부. - `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 '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); ``` ## 코드·오류 ## 상세 기능·요금 국내외 공개조회 40개 연동 국내 택배·편의점·당일배송과 일본우편·TNT·4PX 등 해외배송을 한 API로 조회 실시간 운송장 조회 결과를 저장하지 않고 매 호출마다 택배사 시스템을 즉시 조회 택배사 자동인식(오토모드) 운송장번호만으로 형식을 분석해 최대 5개 후보 택배사를 동시 조회 자동조회 사용 시 주의사항 국내 운송장번호와의 오인식을 막기 위해 일본 택배사의 숫자 10자리와 12자리는 자동조회 대상에서 제외합니다. 사가와급편은 carrier=sagawa_japan, 야마토운수는 carrier=yamato_japan, 일본우편 숫자 12자리는 carrier=japan_post를 지정해 호출하세요. 일본우편 숫자 11/13자리와 UPU S10 형식은 자동조회할 수 있습니다. CAPTCHA 검증값을 요구하는 SF Express와 ECMS, 별도 제외 요청된 롯데 국제조회는 목록과 1시간 상태 점검에 포함하지 않습니다. (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 GET https://apick.app/parcel_tracking/status ## 상세 요청 Header 이름 필수 설명 Authorization O Bearer 인증키 택배사 목록 조회(/rest/parcel_tracking_carriers)는 별도 파라미터가 필요 없습니다. 응답의 activeCarriers에는 현재 정상조회 가능한 목록, maintenanceCarriers에는 점검중인 목록이 담깁니다. ## 상세 응답 택배사 상태·목록 API 이름 타입 설명 updatedAtString|null가장 최근 상태 반영 시각 summaryObject전체·정상·점검중 택배사 수 activeCarriersArray현재 정상조회 가능한 택배사 목록 maintenanceCarriersArray점검중이거나 상태 확인 중인 택배사 목록 carriers[].statusStringACTIVE, MAINTENANCE, CHECKING, UNAVAILABLE carriers[].availableBoolean현재 정상조회 가능 여부 carriers[].checkedAtString|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서버 내부 오류 개인정보 보호를 위해 수취인 이름·전화번호·상세주소 등은 응답에 포함되지 않습니다. ## 상세 코드·정책 실시간 택배사 조회 상태 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 전체 예제 보기 요청 예시 — 택배사 자동조회 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 } }