SHIPDA OPEN API (1.1.5)

Download OpenAPI specification:Download

쉽다API 소개

API 기술지원 : openapi@ship-da.com

변경 이력

본 문서에 대한 변경 이력은 다음과 같으며 버전을 클릭하여 이전 버전의 문서를 조회할 수 있습니다.

접기/펼치기

버전	변경사항
1.0.0	신규 생성
1.0.1	PO 발행, 수정, 운송 조회 API Parameter 추가
1.0.2	인증 탭 API-KEY 발급 설명 추가
1.0.3	의뢰 상태 및 세부 상태에 대한 설명 추가
1.0.4	URL Host 추가 및 PO 생성 파라미터 오자 수정
1.1.0	정산 조회
1.1.1	정산 조회 응답 필드 수정
1.1.2	운송 의뢰 응답 foreignPrice 타입 수정
1.1.3	운송 의뢰 관련 서류 다운로드 API 파라미터 수정 운송 의뢰 조회 API Endpoint 및 응답 필드 수정
1.1.4	청구서 목록 조회 API 응답 타입 수정
1.1.5	PO 생성시 파일 업로드 가능하도록 수정

쉽다API 소개

쉽다API는 쉽다의 주요 기능 또는 콘텐츠를 웹 프로토콜(HTTP API)로 호출해 사용 할 수 있도록 공개된 API입니다.

들어가기 전에

쉽다API를 사용하려면 쉽다에 가입 후 API-KEY를 발급하여 사용 권한을 획득해야 합니다.
개발사는 어드민 도구를 이용해 사용 권한을 획득 한 후 쉽다API를 호출 할 수 있으며, API 호출 시 인증 과정을 수행해야 합니다.
자세한 내용은 본 문서의 인증 항목에서 설명합니다.

RESTful API

쉽다API는 RESTful API 규격을 지향합니다.

Content Type

파일 업로드/다운로드 요청과 같은 예외적인 동작을 제외한 연동 메세지의 기본 형식은 JSON입니다.

Charset

요청 시 파라미터 및 메시지는 'UTF-8'로 인코딩되어야 합니다. 또한 응답 메시지는 'UTF-8'로 인코딩되어 있습니다.

문제해결

쉽다 API를 사용하면서 발생한 문제에 대하여 해결하는 방법에 대하여 아래 서술합니다.

오류 메세지

쉽다API에서 발생하는 오류는 두 가지로 구분됩니다.

API 게이트웨이 서버에서의 오류 (ex :GW.Unauthorized)
쉽다API 서버에서의 오류 (ex :E400)

이 중 API 게이트웨이 서버의 오류는 모든 쉽다API에 공통적으로 발생할 수 있는 오류이며 아래와 같은 규격의 메세지로 오류 정보를 제공하게 됩니다.

{
  "code": "GW.Unauthorized",
  "message": "인증에 실패하였습니다."
  "traceId": "4e2ba8f2-6326-11ee-a27a-ea9ad8372cd1"
}

응답 메세지의 각 JSON 필드 설명은 아래와 같습니다.

필드	설명
code	오류 코드, 두 서버의 구분을 위하여 G와 E로 시작합니다.
message	오류 메세지
traceId	API 요청시 생성되는 고유한 ID

Trace ID

쉽다API는 각 요청마다 Trace ID라는 고유한 ID를 생성한 후 관리하며 클라이언트에게 전달합니다. 쉽다API 사용에 대한 문의나 문제 확인 요청 시 Trace ID를 전달하면 더욱 신속한 원인 파악을 할 수 있게 됩니다.

Trace ID는 응답 메세지의 SH-Trace-ID 헤더에서 확인할 수 있으며,
API의 오류가 발생한 경우에는 응답 메세지의 traceId 필드에서 확인할 수 있습니다.

에러코드

구분	코드	설명	HTTP 상태 코드
공통	GW.BadRequest	요청 필수 파라미터 누락	400
공통	GW.Unauthorized	X-API-KEY 인증 실패	401
공통	GW.Forbidden	권한 부족	403
공통	GW.NotFound	잘못된 API Path	404
공통	GW.InternalServerError	게이트웨이 서버 문제 발생	500
공통	GW.BadGateway	서버 응답 문제 발생	502
공통	E500	예기치 못한 서버 문제 발생	500
공통	E511	유효성 검사 실패	400
발주관리	E503	PO Number에 대응하는 PO 미존재	404
발주관리	E502	중복되는 PO Number	409
발주관리	E504	완료된 PO로 인한 수정 불가	400
운송의뢰	E505	키에 대응하는 문서 미존재	404

인증

쉽다API는 인증키를 통한 인증을 진행합니다.
인증키는 [마이페이지 - Open API]에서 발급하실 수 있습니다. Open API 바로가기

인증키 발급 후 API 요청 시 헤더를 추가합니다.

Security Scheme Type	API Key
Header Name	X-API-KEY

운송 상태(Status) 설명

※쉽다에서는 고객님의 수입 요청을 의뢰 단위로 관리하고 있습니다.
수입 의뢰는 택배와는 달리 물건을 수령할때까지 긴 시간이 소요되며 수 많은 물리적/법률적 절차를 거쳐야 하기 때문에 필연적으로 많은 단계를 두어 관리하고 있습니다.

아래는 쉽다가 관리하는 의뢰의 상태 (status)와 세부상태 (projectStatus)에 대한 설명입니다.

상태(status)	세부상태(projectStatus)	설명
committed	null	의뢰가 등록된 상태입니다. 견적이 없는 구간을 의뢰 시 이 상태가 됩니다.
estimating	null	담당자가 의뢰를 확인하고 견적을 준비하는 상태입니다.
waiting	null	담당자가 견적을 제출했고, 고객의 승인을 기다리는 상태입니다.
waitingForExporterInfo	null	사용자가 견적을 수락하고, 고객의 수출자 정보 입력을 기다리는 상태입니다. 쉽다 홈페이지 - 해상/항공운임 조회에서 견적이 있는 구간에서 저희가 제시한 금액을 고객이 수락하면 바로 이 상태가 됩니다.
inProgress	하위 상태값 참고	고객이 저희가 제시한 견적으로 수출자 정보를 입력하면 실제 운송이 진행되며 해당 상태로 변경됩니다.
	beforeContactPartner	고객이 수출자 정보를 입력한 상태입니다. 아직 수출자와 연락 전입니다.
	contactingPartner	수출자와 연락 중입니다.
	scheduling	선적 스케줄을 조율 중입니다.
	containerCarryOut	(FCL 한정) 현지에서 회물을 픽업하기 위해 공컨테이너가 반출되었습니다. 이 정보를 제공하지 않는 선사의 경우 해당 정보가 입력되지 않을 수 있습니다.
	containerPickup	(FCL 한정) 현지에서 화물 픽업이 완료되었습니다. 이 정보를 제공하지 않는 선사의 경우 해당 정보가 입력되지 않을 수 있습니다.
	gateIn	(FCL 한정)현지 터미널 반입이 완료되었습니다. 이 정보를 제공하지 않는 선사의 경우 해당 정보가 입력되지 않을 수 있습니다.
	loaded	(FCL 한정) 화물 선적이 완료되었습니다. 이 정보를 제공하지 않는 선사의 경우 해당 정보가 입력되지 않을 수 있습니다.
	moving	고객의 화물을 싣은 선박/항공기가 목적지를 향해 이동 중입니다.
	portEntryAndPrepareCustoms	목적지에 입항 완료했으며, 통관 준비 중입니다.
	payment	쉽다에서 고객에게 정산을 요청했습니다.
	completeCustoms	통관이 완료되었습니다.
	delivering	내륙운송까지 의뢰하셨다면 최종 목적지까지 내륙 운송 중입니다.
	finished	운송 종료상태입니다.
finished	하위 상태값 참고	여러 사유로 운송이 종료되어 해당 상태로 변경됩니다.
	finished	운송이 정상적으로 종료된 상태입니다.
	canceled	여러 사유로 운송이 취소된 상태입니다.
	failed	고객이 저희가 제출한 견적을 거부한 상태입니다.

발주관리

무역단위로 관리되는 구매 발주서(PurchaseOrder, PO)에 대한 정보를 등록, 수정합니다.

PO 수정 API

상품명, 인보이스 금액 수정이 가능합니다.
상품명 필드가 비어 있으면 해당 PO에 연결된 품목명이 삭제되고, PO는 종료 처리됩니다.
- PO가 종료될 때, 운송중인 의뢰가 있다면 운송 의뢰도 모두 종료처리 됩니다.
종료된 PO는 수정할 수 없습니다.
- 품목명이 0건이 되어 종료된 PO에 다시 품목명을 연결하여 사용하는 것은 가능합니다.

header Parameters

X-API-KEY

required

string

팀 마스터가 발급한 API-KEY

Request Body schema: application/json
required

payload

poNumber required	string [ 1 .. 60 ] characters 데이터를 변경할 PO 번호
required	Array of objects (model.Product) 상품 정보
required	object 가격 정보

Responses

Request samples

Payload

Content type

application/json

{"poNumber": "1",
"product": [{"productName": "위스키",
"separator": "1"
}
],
"purchasePrice": {"currency": "USD",
"domesticPrice": 47556288.12,
"exchangeRate": 1300.21,
"foreignPrice": 36581.76
}
}

Response samples

200
404
500

Content type

application/json

{"poId": 1,
"poNumber": "501"
}

PO 발행 API

PO를 생성합니다.
수출자 정보 입력 시 업체 관리에도 자동 등록됩니다.

header Parameters

X-API-KEY

required

string

팀 마스터가 발급한 API-KEY

Request Body schema: application/json
required

payload

country required	string = 2 characters 수출자 국가
required	object 발주처 정보
freightType required	string Enum: "FCL" "LCL" "AIR" "all" 화물 타입
paymentOption required	string [ 1 .. 20 ] characters 결제 방법
	Array of objects or null (model.CreatePoFilePayload) 파일 정보 (최대 3장까지 등록 가능하며, 각 파일별로 5MB 용량 이하)
poManagerName	string [ 1 .. 30 ] characters 발주 생성 담당자명
poNumber required	string [ 1 .. 60 ] characters 지정할 PO 번호
required	Array of objects (model.Product) 상품 정보
required	object 가격 정보

Responses

Request samples

Payload

Content type

application/json

{"country": "KR",
"exporter": {"exporterCode": "OP-0001",
"exporterCompany": "(주) 셀러노트"
},
"freightType": "FCL",
"paymentOption": "T/T",
"poFiles": [{"fileBody": "skfviOdu...",
"fileName": "po-file.pdf"
}
],
"poManagerName": "홍길동",
"poNumber": "1",
"products": [{"productName": "위스키",
"separator": "1"
}
],
"purchasePrice": {"currency": "USD",
"domesticPrice": 47556288.12,
"exchangeRate": 1300.21,
"foreignPrice": 36581.76
}
}

Response samples

201
400
409
413
500

Content type

application/json

{"poId": 1,
"poNumber": "501"
}

운송의뢰

쉽다에 의뢰한 운송 의뢰에 대한 정보를 조회합니다.

운송 의뢰 조회 API

다음 항목이 일치하는 운송 의뢰 정보를 조회합니다.
- PO 번호 (발주번호)
- 발주처 코드
- 매입 유형 (수출 / 수입)
선적일(ETA)이 등록된 이후부터 의뢰 조회가 가능합니다.

query Parameters

poNumber required	string [ 1 .. 60 ] characters 조회할 PO 번호
separator	string 품목 구분자
exporterCode required	string [ 1 .. 45 ] characters 발주처 코드
purchaseType required	string Enum: "import" "export" 매입 유형(수출/수입)

header Parameters

X-API-KEY

required

string

팀 마스터가 발급한 고유 API-KEY

Responses

Response samples

200
400
500
502

Content type

application/json

{"list": [{"ATA": "2023-10-22",
"ATD": "2023-10-22",
"BL": "A12345678",
"ETA": "2023-10-22",
"ETD": "2023-10-22",
"cbm": 1,
"containers": [{"containerNumber": "WDFU3017474",
"containerType": "20DRY"
}
],
"currency": "USD",
"cw": 10,
"documents": {"ImportDeclaration": [{"key": "CI_PL/782c86f5-395d-496e-bc6a-25eee9fe7e32.pdf",
"name": "template.pdf"
}
],
"ciPl": [{"key": "CI_PL/782c86f5-395d-496e-bc6a-25eee9fe7e32.pdf",
"name": "template.pdf"
}
],
"co": [{"key": "CI_PL/782c86f5-395d-496e-bc6a-25eee9fe7e32.pdf",
"name": "template.pdf"
}
],
"etc": [{"key": "CI_PL/782c86f5-395d-496e-bc6a-25eee9fe7e32.pdf",
"name": "template.pdf"
}
],
"importTax": [{"key": "CI_PL/782c86f5-395d-496e-bc6a-25eee9fe7e32.pdf",
"name": "template.pdf"
}
]
},
"feu": 0.75,
"finalDestAddress": "인천광역시 중구 자유무역로 232 3층 쉽다 풀필먼트 센터",
"foreignPrice": 1200.07,
"forwardingManager": "김종하",
"freightType": "FCL",
"incoterms": "FOB",
"paymentOption": "Y/Y",
"pickUpAddress": "인천광역시 중구 자유무역로 232 3층 쉽다 풀필먼트 센터",
"pod": "KRPUS",
"pol": "CNSHK",
"projectStatus": "contactingPartner",
"purchaseType": "import",
"rton": 10,
"separator": ["1"
],
"shipmentId": 1,
"status": "inProgress",
"teu": 1.5,
"weight": 2400
}
],
"total": 10
}

운송 의뢰 관련 서류 다운로드 API

운송의뢰에 등록된 첨부파일을 다운로드합니다.
운송의뢰 조회 API에서 조회된 shipmentId와 key를 조건으로 검색합니다.

query Parameters

shipmentId required	integer 의뢰 ID
key required	string 파일 키

header Parameters

X-API-KEY

required

string

팀 마스터가 발급한 고유 API-KEY

Responses

Response samples

200
400
404
500

Content type

application/json

"string"

정산

쉽다에 의뢰한 운송의뢰의 거래명세서에 대한 정보를 조회합니다.

단일 수입 의뢰에 대한 청구서 목록 조회 API

BL(AWB)를 기반으로 정산내역 데이터를 조회합니다.
담당자가 거래명세서를 고객사에게 발송된 이후부터 조회가 가능합니다.
BL 혹은 shipmentId 둘 중 하나는 반드시 입력이 필요합니다.

query Parameters

shipmentId	number 의뢰번호
BL	string BL

header Parameters

X-API-KEY

required

string

팀 마스터가 발급한 고유 API-KEY

Responses

Response samples

200
400
404

Content type

application/json

{"ATA": "2023-10-22",
"ATD": "2023-10-22",
"ETA": "2023-10-22",
"allInvoicesTotalPrice": 71050,
"containersNumberInfo": ["TXGU1234567 (40HQ)",
"SKLU98765432 (20DRY)"
],
"currency": [{"currencyUnit": "USD",
"exchangeRate": 1329.5
}
],
"customsByImportDeclaration": 40050.1,
"customsClearanceDate": "2023-12-14T07:33:38.000Z",
"cw": 4.55,
"endAddress": "인천광역시 중구 자유무역로 232 3층 쉽다 풀필먼트 센터",
"feu": 4,
"freightType": "FCL",
"hBL": "A12345678",
"incoterms": "FOB",
"invoices": [{"documents": [{"category": "invoice",
"key": "invoice/782c86f5-395d-496e-bc6a-25eee9fe7e32.pdf",
"name": "쉽다_거래명세서.pdf"
}
],
"invoiceCreatedAt": "2023-07-10T15:00:00.000Z",
"invoiceItemDetail": [{"code": "SPC81",
"currencyUnit": "KRW",
"itemName": "local",
"supplyValue": 50000,
"taxExemptPrice": 0,
"taxType": "과세",
"totalPrice": 55000,
"vatPrice": 5000,
"zeroTaxPrice": 0
}
],
"invoiceResult": "입금완료",
"invoiceSupplyValueForeignToKrw": 25000,
"invoiceSupplyValueKrw": 20000,
"invoiceTaxExemptPrice": 0,
"invoiceTotalPrice": 50000,
"invoiceType": "invoice",
"invoiceVatPrice": 5000,
"invoiceZeroTaxPrice": 0,
"issuedDate": "2023-10-25",
"issuedResult": "발행 전",
"transactionAmount": 50000
}
],
"mBL": "A12345678",
"otherTaxByImportDeclaration": 20000.4,
"poNumbers": ["SHIPDA-PO-1",
"SHIPDA-PO-2"
],
"pod": "Busan port",
"pol": "Xiaolan port",
"productNames": ["원형 거울",
"유리 화병"
],
"rton": 4.55,
"shipmentId": 160000,
"shippers": ["홍콩익스프레스",
"동영해운"
],
"startAddress": "Zhejiang, China",
"teu": 3,
"userName": "홍길동",
"vatByImportDeclaration": 11000.2
}

SHIPDA OPEN API (1.1.5)

쉽다API 소개

변경 이력

쉽다API 소개

들어가기 전에

RESTful API

문제해결

오류 메세지

Trace ID

에러코드

인증

운송 상태(Status) 설명

발주관리

PO 수정 API

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

PO 발행 API

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

운송의뢰

운송 의뢰 조회 API

query Parameters

header Parameters

Responses

Response samples

운송 의뢰 관련 서류 다운로드 API

query Parameters

header Parameters

Responses

Response samples

정산

단일 수입 의뢰에 대한 청구서 목록 조회 API

query Parameters

header Parameters

Responses

Response samples

Request Body schema: application/json
required

Request Body schema: application/json
required