AI 택배 배송조회

## 사용 방법 ### 요청 ```http POST /api/v1/delivery/track Content-Type: application/json X-API-Key: YOUR_API_KEY ``` ### 요청 파라미터 | 필드명 | 타입 | 필수 | 설명 | | :--- | :---: | :---: | :--- | | carrier_id | String | N* | 조회할 택배사 식별 ID (하단 목록 참조). 배송조회 시 필수 | | track_id | String | N* | 조회할 운송장번호 (숫자만 입력). 배송조회 시 필수 | | ai | Boolean / Integer | N | AI 분석 및 기사님 문자 추천 활성화 여부 (1 또는 true 시 실행, 기본값: 0) | | situation | String | N | 택배 수령 상황 (ai가 1일 때 동작, `door`: 문 앞[기본], `security`: 경비실, `box`: 택배함, `call`: 배송전 연락) | | tone | String | N | 메시지 어조 (ai가 1일 때 동작, `polite`: 공손함[기본], `short`: 간결함, `friendly`: 친근함) | 💡 **Tip (하이브리드 동작)**: `carrier_id`와 `track_id`를 입력하지 않고 `situation`, `tone` 파라미터만 전달하여 호출하는 경우, 실시간 배송조회를 건너뛰고 **오직 AI 기사님 문자 추천 메시지만 단독으로 반환**합니다. ### 응답 파라미터 | 필드명 | 타입 | 설명 | | :--- | :---: | :--- | | success | Boolean | API 호출 성공 여부 | | carrier | Object | 택배사 정보 (id, name, name_ko, tel) (배송조회 미수행 시 null) | | state | Object | 현재 배송 상태 정보 (id, text) (배송조회 미수행 시 null) | | progresses | Array | 상세 배송 진행 경로 히스토리 목록 (배송조회 미수행 시 빈 배열) | | ai_analysis | String | AI가 분석한 지연 진단 및 예상 도착일 리포트 (ai가 0이거나 미작동 시 null) | | recommend_message | String | AI 또는 Fallback으로 생성된 기사님 문자메시지 본문 (ai가 0이거나 미작동 시 null) | | api | String | 호출된 API 식별값 (delivery-tracking) | | remaining | Integer | 잔여 호출 횟수 | ### 지원 택배사 ID 목록 (29개) | 택배사 ID | 택배사 한글 명칭 | | :--- | :--- | | kr.cjlogistics | CJ대한통운 | | kr.epost | 우체국택배 | | kr.hanjin | Hanjin 한진택배 | | kr.lotte | 롯데택배 | | kr.logen | 로젠택배 | | kr.kdexp | 경동택배 (합동) | | kr.daesin | 대신택배 | | kr.hdexp | 합동택배 | | kr.cupost | CU 편의점택배 | | kr.cvsnet | GS Postbox 편의점택배 | | kr.actcore.ocean-inbound | ACT&CORE (해상 수입통관) | | kr.coupangls | 쿠팡 로지스틱스 (CLS) | | kr.chunilps | 천일택배 | | kr.cway | CWAY (우리에스피) | | kr.delibox | 데리버리박스 | | kr.epantos | LX 판토스 | | kr.epost.ems | 우체국 EMS | | kr.goodstoluck | 굿투럭 | | kr.homepick | 홈픽 | | kr.honamlogis | 호남로지스 | | kr.ilyanglogis | 일양로지스 | | kr.kunyoung | 건영택배 | | kr.slx | SLX택배 | | kr.swgexp.epost | 성원글로벌 (우체국 연동) | | kr.swgexp.cjlogistics | 성원글로벌 (CJ 연동) | | kr.today | 오늘의픽업 | | kr.todaypickup | 투데이픽업 | | kr.yongmalogis | 용마로지스 | | kr.hanips | 한의사랑택배 | ### 오류 코드 | 코드 | 메시지 | 설명 | | :--- | :--- | :--- | | 400 | Bad Request | 필수 파라미터 누락 | | 401 | Unauthorized | 유효하지 않은 API Key | | 403 | Forbidden | 해당 API 미구독 | | 429 | Too Many Requests | 호출 한도 초과 또는 배송 API 속도 제한 락 대기 시간초과 | ### 실시간 테스트 방법 (cURL) 다음 cURL 명령어를 사용하여 로컬 또는 서버 환경에서 즉시 API를 테스트할 수 있습니다. `YOUR_API_KEY` 부분을 본인의 API Key로 변경 후 터미널에서 실행해 보세요. #### 1. 배송조회 + AI 분석 + 문자 추천 통합 테스트 (ai=1) ```bash curl -X POST "https://engines.ai.kr/api/v1/delivery/track" \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{ "carrier_id": "kr.cjlogistics", "track_id": "1234567890", "ai": 1, "situation": "door", "tone": "polite" }' ``` #### 2. 순수 배송조회만 테스트 (ai=0) ```bash curl -X POST "https://engines.ai.kr/api/v1/delivery/track" \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{ "carrier_id": "kr.cjlogistics", "track_id": "1234567890", "ai": 0 }' ``` #### 3. 기사님 문자 추천 기능만 단독 테스트 (하이브리드 모드) ```bash curl -X POST "https://engines.ai.kr/api/v1/delivery/track" \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{ "ai": 1, "situation": "security", "tone": "friendly" }' ``` ### 응답 예시 (배송조회 및 AI 추천 동시 수행) ```json { "success": true, "carrier": { "id": "kr.lotte", "name": "Lotte", "name_ko": "롯데택배", "tel": "+8215882121" }, "state": { "id": "in_transit", "text": "구간도착" }, "progresses": [ { "time": "2026-06-16T20:00:00+09:00", "status": { "id": "at_pickup", "text": "집하" }, "location": { "name": "부산서부지점" }, "description": "물품을 보내셨습니다." } ], "ai_analysis": "현재 물품은 부산서부지점에 집하되어 이동을 준비 중입니다. 예상 물동량에 비추어 볼 때 목요일 이내 배송완료될 것으로 보입니다.", "recommend_message": "기사님, 늘 배송해주셔서 정말 감사드립니다. 부재중이오니 물건은 문 앞에 놓아주시고 가볍게 문자 한 통 부탁드리겠습니다. 오늘 하루도 안전 운전 하세요! 😊", "api": "delivery-tracking", "remaining": 999999999 } ```