Cargo API

1. API 소개

3-3. 화물 등록 Request Body 예시

1. API 소개

Cargo Insight API는 화물의 이동 현황을 실시간으로 추적하고,
도착 예정 시간(ETA), 예측 도착 시간(PTA), 지연 여부까지 확인할 수 있도록 지원합니다.

본 API를 통해 고객은 주요 선박 정보, 이벤트 발생 시점,
도착 예측 정보 등을 통합적으로 조회할 수 있습니다.

화물 추적을 위해서는 아래 항목 중 하나 이상의 정보가 필요합니다.

•

Master B/L 번호

•

Booking 번호

•

Container 번호

2. 인증 방법

Cargo API는 사용자 인증을 위해 Swagger UI에서 Basic Authorize 인증 방식을 제공합니다.

인증 절차는 다음과 같습니다:

우측 상단의 [Authorize] 버튼을 클릭합니다.

팝업 창에 제공받은 인증 정보(아이디, 비밀번호)를 입력합니다.

입력 후 다시 [Authorize] 버튼을 클릭하여 인증을 진행합니다.

인증이 완료되면 [Close] 버튼을 클릭하여 인증 창을 닫습니다.

Swagger UI에서 호출되는 모든 API 요청에 인증 토큰이 자동으로 포함되어 전송됩니다.

3. 화물 등록

3-1. 요청 정보

Request URL: [POST] https://insight.seavantage.com/api/cargo

3-2. 실행 순서

Swagger 문서에서 우측 상단의 Select a definition 메뉴에서 Cargo 선택

/cargo 경로로 이동

[Try it Out] 클릭 → 입력창 활성화

요청 Body를 입력

[Execute] 버튼 클릭

하단 응답 영역에서 등록 결과 확인

Swagger 문서 바로가기

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)

4. 화물 추적

4-1. 요청 정보

Request URL : [GET] https://insight.seavantage.com/api/cargo/search

4-2. 실행 순서

Swagger 문서에서 우측 상단의 Select a definition 메뉴에서 Cargo 선택

/cargo/search 경로로 이동

[Try it out] 클릭 → 입력창 활성화

아래 항목 중 1개를 입력

•

containerNo : Container 번호

•

mblNo : M-B/L 번호

•

bookingNo : Booking 번호

[Execute] 버튼 클릭

 응답 영역에서 등록 결과 확인

Swagger 문서 바로가기

4-3. 응답 정보

요청이 성공하거나 실패했을 때 공통적으로 아래와 같은 형식으로 응답이 반환됩니다.

응답 예시

{
  "code": 200,
  "message": "OK",
  "error": false,
  "timestamp": "2024-12-01T12:00:00",
  "response": {
    "documentId": "string",
    "carrierCode": "string",
    "bookingNo": "string",
    "mblNo": "string",
    "containerNo": "string",
    "blStatus": "string",
    "initialEtd": "2025-05-14T02:06:00.647Z",
    "initialEta": "2025-05-14T02:06:00.647Z",
    "bookingRegno": "string",
    "srNo": "string",
    "customColumn1": "string",
    "customColumn2": "string",
    "customColumn3": "string",
    "locations": [
      {
        "locationSeq": 0,
        "locationType": "string",
        "carrierLocationCode": "string",
        "carrierLocationName": "string",
        "carrierTerminalName": "string",
        "carrierEta": "2025-05-14T02:06:00.647Z",
        "carrierEtb": "2025-05-14T02:06:00.647Z",
        "carrierEtd": "2025-05-14T02:06:00.647Z",
        "carrierAta": "2025-05-14T02:06:00.647Z",
        "carrierAtb": "2025-05-14T02:06:00.647Z",
        "carrierAtd": "2025-05-14T02:06:00.647Z",
        "carrierShipName": "string",
        "carrierVoyageNo": "string",
        "ata": "2025-05-14T02:06:00.647Z",
        "atb": "2025-05-14T02:06:00.647Z",
        "atd": "2025-05-14T02:06:00.647Z",
        "pta": "2025-05-14T02:06:00.647Z",
        "imoNo": "string",
        "port": {
          "portId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "portName": "string",
          "unlocode": "string",
          "nationCode": "string",
          "timezone": "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
복사

응답 필드 상세 설명

필드명 (Attr)	예시 값 (Example)	설명 (Desc)
code	200	응답 상태 코드 (HTTP status code와 동일하게 사용됨)코드 목록은 아래 참조
message	"OK"	응답 메시지 (상태에 따른 설명)
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)

응답 객체 상세 설명 (response 객체)

응답의 response 필드는 다음과 같은 구조의 객체이며, 주요 화물 정보와 상태값을 포함합니다.

Depth 1 필드 설명

Attr	Example	Desc
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. Location data 없을 때 2. POD 도착일이 정해지지 않았을 때 3. 등록하고 10일동안 추적 실패 NOT_FOUND: 등록하고 10일 이후 추적 실패
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 객체 참고

Depth 2 필드 설명 (locations 객체)

locations는 화물이 경유하는 각 항만(Location)의 정보를 나타냅니다.
Location 종류(POL, POD 등) 별로 ETA/ETD, ATA/ATD등의 시간 정보도 함께 확인 할 수 있습니다.

Attr	Example	Desc
locationSeq	0	Partial 별 Location 순번
locationType	POL	POR: Place of Receipt POL: Port of Loading TSD: Port of Transit Discharging TSL: Port of Transit 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 객체)

Attr	Example	Desc
portId	47941f60-13b8-4718-bead-aa7c3c61d530	내부적으로 사용하는 port 구분 값
portName	Busan	항구명
unlocode	KRPUS	항구 UNLOCODE
nationCode	KR	국가 코드

Depth 4 필드 설명 (hbls 객체)

hbls는 House B/L 단위의 화물 정보를 담는 객체이며,
하나의 Master B/L에 여러 개의 hbls가 포함될 수 있으며 하나도 입력하지 않을 경우 임의로 생성됩니다.

Attr	Example	Desc
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에 포함된 컨테이너별 상세 정보를 담는 객체입니다.

Attr	Example	Desc
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는  컨테이너에 발생한 이벤트 이력을 나타내며, 각 객체는 하나의 이벤트를 의미합니다.

Attr	Example	Desc
trackingSeq	0	컨테이너별 이벤트 순번
eventCode	EE	이벤트 코드 (아래 별도 이벤트 코드표 참조)
eventStatus	Actual	이벤트 상태 (Actual, Estimate)
eventDescription1	EmptyDeliveredToShipper	이벤트 상세 설명 1
eventDescription2	TRUCK	이벤트 상세 설명 2
carrierEventTime	2025-01-01 00:00	이벤트 발생 시각
carrierLocationName	SHEKOU	이벤트 발생 지역명
unlocode	CNSHK	이벤트 발생 항구의 UNLOCODE
locationType	POL	이벤트 발생 위치 유형 POL: Port of Loading TS: Port of Transit POD: Port of Discharging

4-4. 컨테이너 이벤트 코드 종류

이벤트 코드는 컨테이너의 상태, 위치 이동 등을 의미하는 코드입니다.

이벤트 코드	Description
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