이 API는 carrier code와 MBL 번호 또는 booking 번호 중 하나를 사용하여 선박 스케줄을 일괄 저장할 수 있는 기능을 제공합니다. 운송사는 해당 API를 통해 화물의 세부 정보를 시스템에 등록하거나 업데이트할 수 있습니다.
입력된 데이터는 Cargo Insight 화면 구성에 활용됩니다. 또한, carrierCode는 사전에 승인된 코드만 등록 가능하며, 신규 carrierCode 추가가 필요한 경우 사전에 협의가 필요합니다.
인증 방법
Cargo API는 사용자 인증을 위해 Swagger UI에서 Basic Authorize 인증 방식을 제공합니다.
인증 절차는 다음과 같습니다:
1.
우측 상단의 [Authorize] 버튼을 클릭합니다.
2.
팝업 창에 제공받은 인증 정보(아이디, 비밀번호)를 입력합니다.
3.
입력 후 다시 [Authorize] 버튼을 클릭하여 인증을 진행합니다.
4.
인증이 완료되면 [Close] 버튼을 클릭하여 인증 창을 닫습니다.
Swagger UI에서 호출되는 모든 API 요청에 인증 토큰이 자동으로 포함되어 전송됩니다.
요청 정보
요청 정보
Request URL : [POST] https://insight.seavantage.com/api/cargo/bulk
2-2. 실행 순서
1.
2.
/cargo/bulk 경로로 이동
3.
[Try it out] 클릭 → 입력창 활성화
4.
아래 요청 Parameters 조건에 따라 결과 반환
•
Request body : 선사의 화물정보를 입력하면 화물의 세부 정보를 시스템에 등록하거나 업데이트
5.
[Execute] 버튼 클릭
6.
하단 응답 영역에서 등록 결과 확인
Request body 예시
{
"carrierCode": "ABCD",
"bookingNo": "BOOK123456",
"mblNo": "SOMEBILL2025001",
"customColumn1": "optional",
"customColumn2": "optional",
"customColumn3": "optional",
"schedules": [
{
"vessel": {
"imoNo": "1234567",
"vesselName": "MORNING CHAMPION",
"mmsi": "123456789",
"callSign": "D7AB"
},
"loading": {
"portCode": "KRPUS",
"portName": "Busan",
"etd": "20250125010000",
"atd": "20250125010000"
},
"discharge": {
"portCode": "USNYC",
"portName": "New York",
"eta": "20250215090000",
"ata": "20250215103000"
}
}
]
}
JavaScript
복사
필드 설명
필드 | 설명 |
carrierCode | SCAC 코드 |
bookingNo | Booking 번호 |
mblNo | M-B/L 번호 |
customColumn1 | 고객 정의 필드 1 |
customColumn2 | 고객 정의 필드 2 |
customColumn3 | 고객 정의 필드 3 |
imoNo | 선박 IMO 등록번호 |
vesselName | 선명 |
mmsi | 선박 고유 식별 번호 |
callSign | 호출부호 |
portCode | 선적지 UNLOCODE |
portName | 선적지 항구명 |
etd | 선적지에 대한 Estimated Time of Departure |
atd | 선적지에 대한 Actual Time of Departure |
portCode | 하역지 UNLOCODE |
portName | 하역지 항구명 |
eta | 하역지 Estimated Time of Arrival |
ata | 하역지 Actual Time of Arrival |
응답 정보
요청이 성공하거나 실패했을 때 공통적으로 아래와 같은 형식으로 응답이 반환됩니다.
응답 예시
{
"code": 201,
"message": "Created",
"error": false,
"timestamp": "2025-08-22T01:04:57.593170861",
"response": null
}
JSON
복사
응답 필드 상세 설명
응답 항목별 정의
필드명 | 예시 값 | 설명 |
code | 201 | 응답 상태 코드 (HTTP status code와 동일하게 사용됨)
(아래 별도 응답 상태 코드표 참조) |
message | success | 응답 메시지 (상태에 따른 설명) |
error | false | 오류 여부
true: 오류 발생
false: 정상 처리 |
timestamp | 2025-05-14T01:09:00.834665213 | 응답 생성 시각 (UTC 기준) |
response | null | 응답 성공 및 실패 시 null |
응답 코드 종류
코드 | 설명 |
201 | 정상 처리 (Created) |
400 | 잘못된 파라미터 (Bad request) |
401 | 인증 필요 (Unauthorized) |
403 | 권한 없음 (Forbidden) |
422 | 처리 불가 (Unprocessable entity) |
429 | 요청 과다 (Too many requests, 분당 100회 초과 호출 시 발생) |