Cargo + Past Track API

1. API 소개

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

1. API 소개

이 API는 화물 추적 정보 뿐만 아니라, 선박이 선적지 및 환적지에서 출항한 시점부터 최신 위치까지의 과거 항적 정보를 제공합니다. 

다만, 양하지에서 하역한 경우에는 화역 완료 지점까지의 과거 항적 정보를 조회할 수 있습니다.

2. 인증 방법

Cargo + Past Track 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/past-track

4-2. 실행 순서

Cargo API  [Cargo API > /cargo/search/past-track]으로 이동 후 [Try it Out] 버튼을 클릭하면 조회 조건을 입력하는 폼이 열립니다.

아래 조건을 입력하신 후, [Execute]를 클릭하면 응답 정보를 확인할 수 있습니다.

•

containerNo : Container 번호

•

mblNo : MBL 번호

•

bookingNo : Booking 번호

*해당 API는 POST /cargo API를 통해 등록된 화물만 조회할 수 있습니다.

Swagger 문서 바로가기

4-3. 응답 정보

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

응답 예시

{
  "code": 200,
  "message": "OK",
  "error": false,
  "timestamp": "2024-12-01T12:00:00",
  "response": {
    "carrierCode": "string",
    "bookingNo": "string",
    "mblNo": "SOMEBILL2025001",
    "containerNo": "string",
    "blStatus": "BEFORE",
    "initialEtd": "2025-05-14T08:23:20.203Z",
    "initialEta": "2025-05-14T08:23:20.203Z",
    "bookingRegno": "00000000006201212335",
    "srNo": "SOMEBILL2025001",
    "customColumn1": "string",
    "customColumn2": "string",
    "customColumn3": "string",
    "locations": [
      {
        "locationSeq": 0,
        "locationType": "string",
        "carrierLocationCode": "string",
        "carrierLocationName": "string",
        "carrierTerminalName": "string",
        "carrierEta": "2025-05-14T08:23:20.203Z",
        "carrierEtb": "2025-05-14T08:23:20.203Z",
        "carrierEtd": "2025-05-14T08:23:20.203Z",
        "carrierAta": "2025-05-14T08:23:20.203Z",
        "carrierAtb": "2025-05-14T08:23:20.203Z",
        "carrierAtd": "2025-05-14T08:23:20.203Z",
        "carrierShipName": "string",
        "carrierVoyageNo": "string",
        "ata": "2025-05-14T08:23:20.203Z",
        "atb": "2025-05-14T08:23:20.203Z",
        "atd": "2025-05-14T08:23:20.203Z",
        "pta": "2025-05-14T08:23:20.203Z",
        "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"
              }
            ]
          }
        ]
      }
    ],
    "pastTrack": [
      {
        "shipId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "imoNo": "string",
        "mmsi": "string",
        "shipName": "string",
        "shipType": "string",
        "shipTypeName": "string",
        "shipTypeSize": "string",
        "shipTypeSizeName": "string",
        "nationCode": "string",
        "positions": [
          {
            "imoNo": "string",
            "mmsi": "string",
            "deviceType": "string",
            "callSign": "string",
            "shipName": "string",
            "aisShipType": 0,
            "aisDimA": 0,
            "aisDimB": 0,
            "aisDimC": 0,
            "aisDimD": 0,
            "aisEta": "string",
            "aisDestination": "string",
            "staticDateTime": "2025-05-14T08:23:20.203Z",
            "timestamp": "2025-05-14T08:23:20.203Z",
            "aisClass": "string",
            "nvgStatus": 0,
            "rateOfTurn": 0,
            "speedOverGround": 0,
            "positionAccuracy": 0,
            "longitude": 0,
            "latitude": 0,
            "courseOverGround": 0,
            "trueHeading": 0,
            "elapsed": 0,
            "utcSecond": 0,
            "dte": 0,
            "specialManeuverIndicator": "string",
            "raimFlag": "string",
            "staticMessageNo": 0,
            "locationMessageNo": 0,
            "aisMaxDraught": 0
          }
        ]
      }
    ]
  }
}
JavaScript
복사

응답 필드 상세 설명

필드명 (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)

Depth 1 필드 설명

Attr	Example	Desc
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. 등록하고 3일동안 추적 실패 NOT_FOUND: 등록하고 3일 이후 추적 실패
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 aArrival
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]	Basic port data created by SeaVantage

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 4 → 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 5 → 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

Depth 7 필드 설명 (pastTrack 객체)

Attr	Example	Desc
shipId	aaa9dcf0-6af2-4f89-a6d5-c25594ed9837	SeaVantage 자체 선박 고유 아이디
imoNo	9637076	선박 IMO 등록번호
mmsi	538005248	선박 고유 식별 번호
shipName	ARDMORE SEAVANTAGE	선명
shipType	CONTAINER	선종
shipTypeSize	CONTAINER03	선종/사이즈
nationCode	LR	국가 코드
positions	[object Object]	Depth7

Depth 8 필드 설명 (positions 객체)

Attr	Example	Desc
imoNo	9637076	선박 IMO 등록번호
mmsi	538005248	선박 고유 식별 번호
deviceType	AIS	AIS 장비 타입
callSign	V7CD9	UTC 기준 응답 받은 시간
shipName	ARDMORE SEAVANTAGE	선명
aisShipType	80	Vessel type classification code transmitted via the Automatic Identification System (AIS) (See separate AIS Ship Type table below)
aisDimA	150	Distance from the GPS antenna to the bow (See AIS dimension image below)
aisDimB	33	Distance from the antenna to the stern (See AIS dimension image below)
aisDimC	8	Distance from the antenna to the port (left) side (See AIS dimension image below)
aisDimD	24	Distance from the antenna to the starboard (right) side (See AIS dimension image below)
aisEta	05151000	AIS 예상 도착 시간
aisDestination	HOUSTON FOR ORDER	AIS 목적지
staticDateTime	2025-01-01T00:00:00Z	정적 정보 수신 시각
timestamp	2025-01-01T00:00:00Z	위치 정보 수신 시각
aisClass	A	AIS 종류
nvgStatus	0	운항 상태 코드
rateOfTurn	0	회전율
speedOverGround	1	선박 속도
positionAccuracy	0	위치 정확도
longitude	-92.09995833	경도
latitude	27.45900833	위도
courseOverGround	312.8999938964844	선박 이동 각
trueHeading	229	선수각
elapsed	0	지연
utcSecond	45	UTC 초
dte	0	Data terminal equipment (DTE) ready 0 = available 1 = not available = default
specialManeuverIndicator	0	0 = not available = default 1 = not engaged in special maneuver 2 = engaged in special maneuver (i.e.: regional passing arrangement on Inland Waterway)
raimFlag	0	Receiver autonomous integrity monitoring (RAIM) flag of electronic position fixing device 0 = RAIM not in use = default 1 = RAIM in use
staticMessageNo	5	정적 메시지 번호
locationMessageNo	1	위치 메시지 번호
aisMaxDraught	8.1	In 1/10 m, 255 = draught 25.5 m or greater 0 = not available = default; In accordance with IMO Resolution A.851

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

4-5. AIS Ship Type

Type Code	Description	Type Code	Description
0	Not available (default)	58	Medical Transport
1–19	Reserved for future use	59	Noncombatant ship according to RR Resolution No. 18
20	Wing in ground (WIG), all ships of this type	60	Passenger, all ships of this type
21	Wing in ground (WIG), Hazardous category A	61	Passenger, Hazardous category A
22	Wing in ground (WIG), Hazardous category B	62	Passenger, Hazardous category B
23	Wing in ground (WIG), Hazardous category C	63	Passenger, Hazardous category C
24	Wing in ground (WIG), Hazardous category D	64	Passenger, Hazardous category D
25–29	Wing in ground (WIG), Reserved for future use	65–68	Passenger, Reserved for future use
30	Fishing	69	Passenger, No additional information
31	Towing	70	Cargo, all ships of this type
32	Towing: length exceeds 200m or breadth exceeds 25m	71	Cargo, Hazardous category A
33	Dredging or underwater ops	72	Cargo, Hazardous category B
34	Diving ops	73	Cargo, Hazardous category C
35	Military ops	74	Cargo, Hazardous category D
36	Sailing	75–78	Cargo, Reserved for future use
37	Pleasure Craft	79	Cargo, No additional information
38–39	Reserved	80	Tanker, all ships of this type
40	High speed craft (HSC), all ships of this type	81	Tanker, Hazardous category A
41	High speed craft (HSC), Hazardous category A	82	Tanker, Hazardous category B
42	High speed craft (HSC), Hazardous category B	83	Tanker, Hazardous category C
43	High speed craft (HSC), Hazardous category C	84	Tanker, Hazardous category D
44	High speed craft (HSC), Hazardous category D	85–88	Tanker, Reserved for future use
45–48	High speed craft (HSC), Reserved for future use	89	Tanker, No additional information
49	High speed craft (HSC), No additional information	90	Other Type, all ships of this type
50	Pilot Vessel	91	Other Type, Hazardous category A
51	Search and Rescue vessel	92	Other Type, Hazardous category B
52	Tug	93	Other Type, Hazardous category C
53	Port Tender	94	Other Type, Hazardous category D
54	Anti-pollution equipment	95–98	Other Type, Reserved for future use
55	Law Enforcement	99	Other Type, no additional information
56–57	Spare - Local Vessel