1. API 소개
Cargo Insight API는 화물의 이동 현황을 실시간으로 추적하고,
도착 예정 시간(ETA), 예측 도착 시간(PTA), 지연 여부까지 확인할 수 있도록 지원합니다.
본 API를 통해 고객은 화물 정보를 추적할 수 있도록 저장하는 기능을 제공합니다.
화물 추적을 위해서는 아래 항목 중 하나 이상의 정보로 화물 저장이 가능합니다.
•
Master B/L 번호
•
Booking 번호
•
Container 번호
2. 인증 방법
Cargo API는 사용자 인증을 위해 Swagger UI에서 Basic Authorize 인증 방식을 제공합니다.
인증 절차는 다음과 같습니다:
1.
우측 상단의 [Authorize] 버튼을 클릭합니다.
2.
팝업 창에 제공받은 인증 정보(아이디, 비밀번호)를 입력합니다.
3.
입력 후 다시 [Authorize] 버튼을 클릭하여 인증을 진행합니다.
4.
인증이 완료되면 [Close] 버튼을 클릭하여 인증 창을 닫습니다.
Swagger UI에서 호출되는 모든 API 요청에 인증 토큰이 자동으로 포함되어 전송됩니다.
3. 화물 등록
3-1. 요청 정보
Request URL: [POST] https://insight.seavantage.com/api/cargo
3-2. 실행 순서
1.
Swagger 문서에서 우측 상단의 Select a definition 메뉴에서 Cargo 선택
2.
/cargo 경로로 이동
3.
[Try it Out] 클릭 → 입력창 활성화
4.
요청 Body를 입력
5.
[Execute] 버튼 클릭
6.
하단 응답 영역에서 등록 결과 확인
3-3. 화물 등록 Request Body 예시
carrierCode와 함께 아래 항목 중 하나 이상을 포함해야 합니다.
mblNo, bookingNo, containerNo를 조합하여 사용할 수 있습니다
M-B/L 번호만 입력하는 경우 {
"carrierCode": "string",
"mblNo": "string"
}
JSON
복사
Booking 번호만 입력하는 경우{
"carrierCode": "string",
"bookingNo": "string"
}
JSON
복사
Container 번호만 입력하는 경우{
"carrierCode": "string",
"containerNo": "string"
}
JSON
복사
M-B/L 번호와 Booking 번호를 함께 입력하는 경우{
"carrierCode": "string",
"mblNo": "string",
"bookingNo": "string"
}
JavaScript
복사
M-B/L 또는 Booking 번호 + 상세 화물 정보 입력하는 경우carrierCode와 M-B/L 번호 또는 Booking 번호만 를 기준으로,
여러 개의 House B/L 및 컨테이너, 화주 정보를 함께 등록해야 할 경우 아래 구조로 요청합니다.
{
"carrierCode": "string",
"mblNo": "string",
"bookingNo": "string",
"containerNo": "string",
"bookingRegno": "string",
"srNo": "string",
"customColumn1": "string",
"customColumn2": "string",
"customColumn3": "string",
"hbls": [
{
"hblNo": "string",
"ciNo": "string",
"shipperCode": "string",
"shipperName": "string",
"consigneeCode": "string",
"consigneeName": "string",
"ownerCode": "string",
"ownerName": "string",
"containers": [
{
"containerNo": "string",
"size": "string",
"type": "string",
"commodity": "string",
"hscode": "string",
"qty": 0,
"gw": 0,
"sealNo1": "string",
"sealNo2": "string",
"sealNo3": "string"
}
]
}
]
}
JavaScript
복사
3-4. 응답 정보
요청이 성공하거나 실패했을 때 공통적으로 아래와 같은 형식으로 응답이 반환됩니다.
응답 예시{
"code": 201,
"message": "Created",
"error": false,
"timestamp": "2025-05-14T01:09:00.834665213",
"response": null
}
JSON
복사
응답 필드 상세 설명필드명 (Attr) | 예시 값 (Example) | 설명 (Desc) |
code | 201 | 응답 상태 코드 (HTTP status code와 동일하게 사용됨)코드 목록은 아래 참조 |
message | "Created" | 응답 메시지 (상태에 따른 설명) |
error | false | 오류 여부
(true: 오류 발생, false: 정상 처리) |
timestamp | "2025-05-14T01:09:00.834665213" | 응답 생성 시각 (UTC 기준) |
response | null 또는 Object | 응답 본문 데이터. 상황에 따라 null 또는 데이터 객체 |
응답 코드 종류 (code 필드 기준)코드 | 설명 |
201 | 정상 처리 (Created) |
400 | 잘못된 파라미터 (Bad Request) |
401 | 인증 필요 (Unauthorized) |
403 | 권한 없음 (Forbidden) |
422 | 처리 불가 (Unprocessable Entity) |
429 | 요청 과다 (Too Many Requests) |