이 API는 등록된 화물의 이동 현황, 도착 예정 시간(ETA), 예측 도착 시간(PTA), 화물 지연 등을 실시간으로 확인할 수 있습니다.
인증 방법
Cargo API는 사용자 인증을 위해 Swagger UI에서 Basic Authorize 인증 방식을 제공합니다.
인증 절차는 다음과 같습니다:
1.
우측 상단의 [Authorize] 버튼을 클릭합니다.
2.
팝업 창에 제공받은 인증 정보(아이디, 비밀번호)를 입력합니다.
3.
입력 후 다시 [Authorize] 버튼을 클릭하여 인증을 진행합니다.
4.
인증이 완료되면 [Close] 버튼을 클릭하여 인증 창을 닫습니다.
Swagger UI에서 호출되는 모든 API 요청에 인증 토큰이 자동으로 포함되어 전송됩니다.
화물 추적
요청 정보
Request URL : [GET] https://insight.seavantage.com/api/cargo/search
실행 순서
1.
2.
/cargo/search 경로로 이동합니다.
3.
[Try it out] 을 클릭하여 입력창을 활성화합니다.
4.
아래 항목 중 하나를 선택하여 입력합니다.
•
containerNo : Container 번호
•
mblNo : M-B/L 번호
•
bookingNo : Booking 번호
5.
[Execute] 버튼 클릭합니다.
6.
응답 영역에서 등록 결과를 확인합니다.
응답 정보
요청이 성공하거나 실패했을 때 공통적으로 아래와 같은 형식으로 응답이 반환됩니다.
응답 예시
{
"code": 200,
"message": "OK",
"error": false,
"timestamp": "2024-12-01T12:00:00",
"response": {
"documentId": "string",
"referenceType": "string",
"carrierCode": "string",
"bookingNo": "string",
"mblNo": "string",
"containerNo": "string",
"blStatus": "string",
"initialEtd": "2025-05-14 02:06",
"initialEta": "2025-05-14 02:06",
"bookingRegno": "string",
"srNo": "string",
"customColumn1": "string",
"customColumn2": "string",
"customColumn3": "string",
"locations": [
{
"locationSeq": 0,
"locationType": "string",
"carrierLocationCode": "string",
"carrierLocationName": "string",
"carrierTerminalName": "string",
"carrierEta": "2025-05-14 02:06",
"carrierEtb": "2025-05-14 02:06",
"carrierEtd": "2025-05-14 02:06",
"carrierAta": "2025-05-14 02:06",
"carrierAtb": "2025-05-14 02:06",
"carrierAtd": "2025-05-14 02:06",
"carrierShipName": "string",
"carrierVoyageNo": "string",
"ata": "2025-05-14 02:06",
"atb": "2025-05-14 02:06",
"atd": "2025-05-14 02:06",
"pta": "2025-05-14 02:06",
"imoNo": "string",
"port": {
"portId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"portName": "string",
"unlocode": "string",
"nationCode": "string"
}
}
],
"hbls": [
{
"hblNo": "string",
"ciNo": "1234567890",
"shipperCode": "string",
"shipperName": "string",
"consigneeCode": "string",
"consigneeName": "string",
"ownerCode": "string",
"ownerName": "string",
"containers": [
{
"containerNo": "string",
"hblNo": "string",
"size": "string",
"type": "string",
"commodity": "string",
"hscode": "string",
"qty": 0,
"gw": 0,
"sealNo1": "string",
"sealNo2": "string",
"sealNo3": "string",
"trackings": [
{
"trackingSeq": 0,
"eventCode": "string",
"eventStatus": "string",
"eventDescription1": "string",
"eventDescription2": "string",
"carrierEventTime": "string",
"carrierLocationName": "string",
"unlocode": "string",
"locationType": "POR"
}
]
}
]
}
]
}
}
JSON
복사
응답 필드 상세 설명
응답 필드 정의
필드명 | 예시 값 | 설명 |
code | 200 | 응답 상태 코드 (HTTP status code와 동일하게 사용됨)
(아래 별도 응답 상태 코드표 참조) |
message | OK | 응답 메시지 (상태에 따른 설명) |
error | false | 오류 여부
true: 오류 발생
false: 정상 처리 |
timestamp | 2025-05-14T01:09:00.834665213 | 응답 생성 시각 (UTC 기준) |
response | null 또는 Object | 화물 존재시 데이터 객체, 미존재시 null |
응답 코드 종류
코드 | 설명 |
200 | 정상 처리 (Success) |
400 | 잘못된 파라미터 (Bad request) |
401 | 인증 필요 (Unauthorized) |
403 | 권한 없음 (Forbidden) |
422 | 처리 불가 (Unprocessable entity) |
429 | 요청 과다 (Too many requests) |
응답 상세 설명
Depth 1 필드 설명 (response 객체)
필드명 | 예시 값 | 설명 |
documentId | 6ebec210-a072-43ef-a6d1-874fddbc4b36 | 내부적으로 사용하는 화물 구분 식별자 |
carrierCode | CMAL | SCAC 4자리 선사 코드 |
bookingNo | SHZ5400465 | Booking 번호 |
mblNo | SHZ5400465 | Master B/L 번호 |
containerNo | BEAU2789169 | Container 번호 |
blStatus | END | PROCESSING:
추적 요청 후 화물 추적이 진행 중인 상태
BEFORE:
POL에서 선박이 출항 전인 상태 (ATD 발생 이전)
ON:
POL에서 선박이 출항했고 POD에 입항 전 상태
END:
POD에 ATA 발생 (선박이 POD에 도착, POD에 입항)
PENDING:
1. 선적항 또는 하역항 정보를 찾지 못했을 때
2. 하역항의 도착일이 정해지지 않았을 때
3. 최초 등록 후 일정 기간 화물 추적시 실패 했을 때
NOT_FOUND:
최종적으로 화물 추적에 실패 한 경우 |
initialEtd | 2025-01-01 00:00 | 화물 등록 후 최초 수집된 ETD |
initialEta | 2025-01-01 00:00 | 화물 등록 후 최초 수집된 ETA |
bookingRegno | null | Booking confirm 번호 |
srNo | null | Shipping request 번호 |
customColumn1 | null | 고객 정의 필드 1 |
customColumn2 | null | 고객 정의 필드 2 |
customColumn3 | null | 고객 정의 필드 3 |
locations | [object Object] | Depth 2 → location 객체 참고 |
hbls | [object Object] | Depth 3 → hbls 객체 참고 |
referenceType | MBL | 화물 추적을 어떤 값으로 등록 했는지 나타내는 값
CONTAINER: 최초 등록시 Container 번호로 등록
BOOKING: 최초 등록시 Booking 번호로 등록
MBL: 최초 등록시 Master B/L 번호로 등록 |
Depth 2 필드 설명 (locations 객체)
locations는 화물이 경유하는 각 항만(Location)의 정보를 나타냅니다. Location 종류(POL, POD 등) 별로 ETA/ETD, ATA/ATD등의 시간 정보도 함께 확인 할 수 있습니다.
필드명 | 예시 값 | 설명 |
locationSeq | 0 | Partial 별 Location 순번 |
locationType | POL | POR: Place of Receipt
POL: Port of Loading
TSD: Transshipment Discharging
TSL: Transshipment Loading
POD: Port of Discharging
PVY: Place of Delivery |
carrierLocationCode | CNSHK | 선사에서 수집된 위치 코드 |
carrierLocationName | SHEKOU | 선사에서 수집된 위치명 |
carrierTerminalName | CMA CGM PSA LION TERMINAL | 선사에서 수집된 터미널명 |
carrierEta | 2025-01-01 00:00 | 선사에서 수집된
Estimated Time of Arrival |
carrierEtb | 2025-01-01 00:00 | 선사에서 수집된
Estimated Time of Berthing |
carrierEtd | 2025-01-01 00:00 | 선사에서 수집된
Estimated Time of Departure |
carrierAta | 2025-01-01 00:00 | 선사에서 수집된
Actual Time of Arrival |
carrierAtb | 2025-01-01 00:00 | 선사에서 수집된
Actual Time of Berthing |
carrierAtd | 2025-01-01 00:00 | 선사에서 수집된
Actual Time of Departure |
carrierShipName | ANL WANGARATTA | 선사에서 수집된 선박명 |
carrierVoyageNo | 0WWE9W1MA | 선사에서 수집된 항차 |
ata | 2025-01-01 00:00 | 씨벤티지 포트콜 데이터로 생성된
Actual Time of Arrival |
atb | 2025-01-01 00:00 | 씨벤티지 포트콜 데이터로 생성된
Actual Time of Berthing |
atd | 2025-01-01 00:00 | 씨벤티지 포트콜 데이터로 생성된
Actual Time of Departure |
pta | 2025-01-01 00:00 | Predicted Time of Arrival (씨벤티지) |
imoNo | 9334167 | IMO Number |
port | [object Object] | Depth 3 → port 객체 참고 |
Depth 3 필드 설명 (port 객체)
필드명 | 예시 값 | 설명 |
portId | 47941f60-13b8-4718-bead-aa7c3c61d530 | 내부적으로 사용하는 Port 구분 값 |
portName | Busan | 항구명 |
unlocode | KRPUS | 항구 UN/LOCODE |
nationCode | KR | 국가 코드 |
Depth 4 필드 설명 (hbls 객체)
hbls는 House B/L 단위의 화물 정보를 담는 객체이며, 하나의 Master B/L에 여러 개의 hbls가 포함될 수 있으며 하나도 입력하지 않을 경우 임의로 생성됩니다.
필드명 | 예시 값 | 설명 |
hblNo | SVH.SHZ5400465 | House B/L 번호
(임의로 생성된 값은 SVH. 로 값이 시작됩니다.) |
ciNo | null | Commercial Invoice 번호 |
shipperCode | null | 송하인 코드 |
shipperName | null | 송하인 이름 |
consigneeCode | null | 수하인 코드 |
consigneeName | null | 수하인 이름 |
ownerCode | null | 실화주 코드 |
ownerName | null | 실화주 이름 |
containers | [object Object] | Depth 5 → containers 객체 참고 |
Depth 5 필드 설명 (containers 객체)
containers는 각 House B/L에 포함된 컨테이너별 상세 정보를 담는 객체입니다.
필드명 | 예시 값 | 설명 |
containerNo | BEAU2789169 | 컨테이너 번호 |
hblNo | SVH.SHZ5400465 | House B/L 번호 |
size | 22 | 컨테이너 사이즈 |
type | G1 | 컨테이너 타입 코드 |
commodity | null | 화물 종류 |
hscode | null | 상품분류코드 (국제표준) |
qty | null | 개수 (수량) |
gw | null | 총 중량 (Gross Weight) |
sealNo1 | null | 봉인번호#1 |
sealNo2 | null | 봉인번호#2 |
sealNo3 | null | 봉인번호#3 |
trackings | [object Object] | Depth 6 → trackings 객체 참고 |
Depth 6 필드 설명 (trackings 객체)
trackings는 컨테이너에 발생한 이벤트 이력을 나타내며, 각 객체는 하나의 이벤트를 의미합니다.
필드명 | 예시 값 | 설명 |
trackingSeq | 0 | 컨테이너별 이벤트 순번 |
eventCode | EE | 이벤트 코드
(아래 별도 이벤트 코드표 참조) |
eventStatus | Actual | 이벤트 상태 (Actual, Estimate) |
eventDescription1 | EmptyDeliveredToShipper | 이벤트 상세 설명 1 |
eventDescription2 | TRUCK | 이벤트 상세 설명 2 |
carrierEventTime | 2025-01-01 00:00 | 이벤트 발생 시각 |
carrierLocationName | SHEKOU | 이벤트 발생 지역명 |
unlocode | CNSHK | 이벤트 발생 항구의 UN/LOCODE |
locationType | POL | 이벤트 발생 위치 유형
POL: Port of Loading
TS: Transshipment
POD: Port of Discharging |
부록
컨테이너 이벤트 코드 종류
이벤트 코드는 컨테이너의 이벤트 상태, 위치, 예상 시간, 실제 시간 등을 나타냅니다.
이벤트 코드 | 설명 |
I | In gate |
AE | Loaded on vessel |
VD | Vessel departure |
VA | Vessel arrival |
VB | Vessel berthing |
UV | Unloaded from vessel |
OA | Out gate |
D | Delivered to the consignee |
RD | Empty container returned |
A | Arrived |
AD | Appointment date/Time for delivery |
AG | ETA Changed |
AL | Loaded on rail |
AM | Loaded on truck |
AP | Loaded on feeder vessel |
AR | Rail arrival at destination intermodal ramp |
AV | Available for delivery |
CO | Cargo received at contractual place of receipt |
CR | Carrier release |
CT | Customs released |
CU | Carrier and customs released |
FT | Free time expired |
MT | Empty returned to CY |
P | Full container issued |
PA | Us customs hold |
RL | Rail departure from original intermodal ramp |
UR | Unloaded from rail |
VE | Estimated vessel arrival |
VT | Estimated vessel departure |
X2 | ETA at consignee location |
C | Estimated to depart terminal location |
CI | Passing |
X6 | En route to delivery location |
R | Received from prior carrier |
NO | Ocean charges paid |
AW | Awaiting export |
U | Unloading |