{"openapi":"3.0.3","info":{"title":"APICK 택배 배송조회","version":"1.0.0","description":"국내 택배부터 일본·중국·유럽 국제배송까지 하나의 형식으로 실시간 배송현황을 조회합니다. 결과를 DB에 저장하지 않고 매 호출마다 택배사 시스템을 즉시 확인하며, 운송장번호만 있고 택배사를 모를 때는 자동조회(/rest/parcel_tracking_auto)를 이용할 수 있습니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/parcel_tracking":{"post":{"summary":"택배 배송조회","description":"국내 택배부터 일본·중국·유럽 국제배송까지 하나의 형식으로 실시간 배송현황을 조회합니다. 결과를 DB에 저장하지 않고 매 호출마다 택배사 시스템을 즉시 확인하며, 운송장번호만 있고 택배사를 모를 때는 자동조회(/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":"택배사 원문 상태 텍스트(예: \"배달완료\")"},"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 호출 공통 데이터"}}}}}},"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":"국내 택배부터 일본·중국·유럽 국제배송까지 하나의 형식으로 실시간 배송현황을 조회합니다. 결과를 DB에 저장하지 않고 매 호출마다 택배사 시스템을 즉시 확인하며, 운송장번호만 있고 택배사를 모를 때는 자동조회(/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":"택배사 원문 상태 텍스트(예: \"배달완료\")"},"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 호출 공통 데이터"}}}}}},"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":"국내 택배부터 일본·중국·유럽 국제배송까지 하나의 형식으로 실시간 배송현황을 조회합니다. 결과를 DB에 저장하지 않고 매 호출마다 택배사 시스템을 즉시 확인하며, 운송장번호만 있고 택배사를 모를 때는 자동조회(/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"}}}}