이 API는 고객이 추적하고자 하는 화물 정보를 등록하여, 시스템을 통해 실시간 추적이 가능하도록 지원합니다.
화물 등록은 계약서에 명시된 등록 한도 내에서 허용됩니다. 등록 한도를 초과할 경우, 계약 조건에 따라 추가 요금이 부과될 수 있습니다.
1. 인증 방법
Cargo API는 사용자 인증을 위해 Swagger UI에서 Basic Authorize 인증 방식을 제공합니다.
인증 절차는 다음과 같습니다:
1.
우측 상단의 [Authorize] 버튼을 클릭합니다.
2.
팝업 창에 제공받은 인증 정보(아이디, 비밀번호)를 입력합니다.
3.
입력 후 다시 [Authorize] 버튼을 클릭하여 인증을 진행합니다.
4.
인증이 완료되면 [Close] 버튼을 클릭하여 인증 창을 닫습니다.
Swagger UI에서 호출되는 모든 API 요청에 인증 토큰이 자동으로 포함되어 전송됩니다.
2. 요청 정보
2-1. 요청 정보
Request URL: [POST] https://insight.seavantage.com/api/cargo
2-2. 실행 순서
1.
Swagger 문서에서 우측 상단의 Select a definition 메뉴에서 Cargo 선택
2.
/cargo 경로로 이동
3.
[Try it out] 클릭 → 입력창 활성화
4.
요청 Body를 입력
5.
[Execute] 버튼 클릭
6.
하단 응답 영역에서 등록 결과 확인
화물 등록 Request body 예시
carrierCode와 함께 아래 항목 중 하나 이상을 포함해야 합니다.
mblNo, bookingNo, containerNo를 조합하여 사용할 수 있습니다
M-B/L 번호만 입력하는 경우
{
"carrierCode": "string",
"mblNo": "string"
}
JSON
복사
Booking 번호만 입력하는 경우
{
"carrierCode": "string",
"bookingNo": "string"
}
JSON
복사
Container 번호만 입력하는 경우
container 번호만 입력하는 경우 House B/L 및 컨테이너, 화주 정보는 입력할 수 없습니다.
상세 화물 정보를 함께 등록할 경우에는 M-B/L 또는 Booking 번호를 기준으로 등록해야 합니다.{
"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",
"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. 응답 정보
응답 예시
{
"code": 201,
"message": "Created",
"error": false,
"timestamp": "2025-05-14 08:23",
"response": {
"documentId": "62ea3af6-344e-44f6-a114-432b5b92365c"
}
}
JSON
복사
응답 필드 상세 설명
응답 항목별 정의
필드명 | 예시 값 | 설명 |
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) |
응답 상세 설명
Depth 1 필드 설명 (response 객체)
필드명 | 예시 값 | 설명 | 데이터 타입 |
documentId | 62ea3af6-344e-44f6-a114-432b5b92365c | 내부적으로 사용하는 화물 구분 식별자 | varchar(36) - UUID |