{"openapi":"3.0.3","info":{"title":"APICK 택배 배송조회","version":"1.0.0","description":"국내 택배부터 일본·중국·유럽 국제배송까지 하나의 형식으로 배송현황을 조회합니다. 호출할 때마다 그 시점의 최신 배송현황을 돌려주며, 운송장번호만 있고 택배사를 모를 때는 자동조회(/rest/parcel_tracking_auto)를 쓰면 됩니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/parcel_tracking":{"post":{"summary":"택배 배송조회","description":"국내 택배부터 일본·중국·유럽 국제배송까지 하나의 형식으로 배송현황을 조회합니다. 호출할 때마다 그 시점의 최신 배송현황을 돌려주며, 운송장번호만 있고 택배사를 모를 때는 자동조회(/rest/parcel_tracking_auto)를 쓰면 됩니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"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":"결제 기록 번호입니다. 문의할 때 함께 알려 주세요."}}}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"carrier":{"type":"string","description":"택배사 코드 (예: cj, hanjin, lotte, logen, epost-domestic) (string)","example":"cj"},"trackingNumber":{"type":"string","description":"조회할 운송장번호입니다. 택배사별 자릿수·형식이 다르며, 하이픈 없이 숫자만 입력하는 것을 권장합니다. (string)","example":"123456789012"}},"required":["carrier","trackingNumber"]}}}}}},"/rest/parcel_tracking_auto":{"post":{"summary":"택배 배송조회","description":"국내 택배부터 일본·중국·유럽 국제배송까지 하나의 형식으로 배송현황을 조회합니다. 호출할 때마다 그 시점의 최신 배송현황을 돌려주며, 운송장번호만 있고 택배사를 모를 때는 자동조회(/rest/parcel_tracking_auto)를 쓰면 됩니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"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":"결제 기록 번호입니다. 문의할 때 함께 알려 주세요."}}}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"trackingNumber":{"type":"string","description":"조회할 운송장번호입니다. 택배사별 자릿수·형식이 다르며, 하이픈 없이 숫자만 입력하는 것을 권장합니다. (string)","example":"123456789012"}},"required":["trackingNumber"]}}}}}},"/rest/parcel_tracking_carriers":{"post":{"summary":"택배 배송조회","description":"국내 택배부터 일본·중국·유럽 국제배송까지 하나의 형식으로 배송현황을 조회합니다. 호출할 때마다 그 시점의 최신 배송현황을 돌려주며, 운송장번호만 있고 택배사를 모를 때는 자동조회(/rest/parcel_tracking_auto)를 쓰면 됩니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스 응답","content":{"application/json":{"schema":{"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가 반환될 수 있습니다."}}}},"503":{"description":"택배사 상태를 조회할 수 없습니다. 잠시 후 다시 요청하세요.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","enum":["TRACKING_HEALTH_STATUS_UNAVAILABLE"]}}}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":false,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{}}}}}}}},"x-code-tables":[{"title":"택배사별 현재 조회 상태","columns":["No","택배사","carrier 코드","상태"],"rows":[]},{"title":"택배사별 현재 조회 상태","columns":["No","택배사","carrier 코드","상태"],"rows":[]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}