Create a shipment in FKTG OMS. Omitted packages[].declared_packaging_type defaults to BOX, preserving existing ordinary-box requests. Declare CRATE, PALLET or SKID when applicable. UPS Worldwide Express Freight requires eligible actual packaging and declared_pallet_piece_count; default BOX compatibility does not make an ordinary box eligible for Freight.
Duplicate prevention:
- The request is treated as unique by company_id + external_shipment_ref.
- Re-using the same external_shipment_ref returns 409 conflict.
Policy notes:
- packages must contain at least one package.
- items must contain at least one item.
- HS Code and origin country are optional.
- sender_ioss is optional.
- EU destinations require export_reason; EU sales to individual recipients require merchantProductId and nonStandardManufacturerProductId on every item.
- standardManufacturerProductId is optional. PID fields are strings and preserve leading zeroes.
- Unsupported carrier/service/incoterms/destination combinations return 422.
Required credential scope: shipments.write. Use an FKTG service_code from Rate. Without a code, legacy carrier + service_name remains supported. If a supplied carrier or name disagrees with the code, return 422 SERVICE_SELECTION_CONFLICT; never silently select another service. Unknown/disabled codes return 422 CARRIER_SERVICE_NOT_ACTIVE, ambiguous legacy names return 422 CARRIER_SERVICE_AMBIGUOUS, and destination/packaging restrictions still apply. Malformed code strings return 400 INVALID_REQUEST. The server calculates the selected service rate from the submitted package weights/dimensions, recipient, incoterms and declaration items under the authenticated company pricing, then saves freight and its snapshot atomically with the shipment. No client-supplied amount or quote token is required. Internal calculation requires no extra rates.read scope. Calculation failure returns 422 RATE_UNAVAILABLE before shipment creation; no zero-fare registration is accepted. This saves an estimate, not payment or release approval. Yun supports one package per shipment; multiple packages return422 CARRIER_MULTI_PIECE_UNSUPPORTED before any write. Older registration acceptance did not imply rating or label support.
요청 본문 필드
external_order_idstring · 필수external_shipment_refstring · 필수- Unique per company scope
external_order_refstring | null · 선택external_channelstring | null · 선택order_datetimestring | null · 선택carrierstring · 선택incotermsstring · 필수- FedEx DAP/DDP; UPS DAP/DDP; YUN BR DAP only, all other destinations DDP; SF US DDP only, flexible services DAP/DDP elsewhere, E-Commerce Express CD DAP only for TH/TW/HK/CN/SG/VN/MO/PH and DDP otherwise. Invalid combinations rejected; no silent payer change. Existing create compatibility: Yun non-BR and some SF-CD DAP requests normalize to DDP with explicit INCOTERMS_NORMALIZED_TO_DDP warning. Obtain payer consent and request DDP explicitly. Quotes do not normalize. PATCH rejects invalid incoterms with 422; it does not normalize DAP to DDP.
senderobject · 필수sender_iossstring | null · 선택- Optional. Useful for EU destinations.
export_reasonstring · 선택- Required for EU destinations. Use the actual purpose; missing EU purpose returns 422 INVALID_EU_EXPORT_REASON.
recipientobject · 필수packagesarray · 필수- Each final handling unit accepts declared_packaging_type: BOX (paper carton/customer packaging, MY PACKAGE), CRATE (wooden box), PALLET or SKID; explicit null is allowed. Omission defaults to BOX. PALLET/SKID requires declared_pallet_piece_count.
itemsarray · 필수memostring | null · 선택service_namestring · 선택- Legacy selection: exact Rate service_name together with carrier. Optional when service_code is provided; if supplied, it must match that code.
service_codestring · 선택- Stable opaque FKTG service identifier returned by Rate API. Not a provider-native service code. Use the returned value verbatim; do not derive it from carrier/name or an internal ID.
중첩 필드의 제약과 전체 응답 스키마는 OpenAPI 원문을 확인하세요.
요청 예제 · 합성 데이터
{
"external_order_id": "ORD-20260422-1001",
"external_shipment_ref": "ORD-20260422-1001-1",
"external_order_ref": "MALL-10000421",
"external_channel": "hugo-shop",
"order_datetime": "2026-04-22T10:20:00+09:00",
"incoterms": "DAP",
"sender": {
"company_name": "HUGO SHOP",
"name": "홍길동",
"phone": "01012345678",
"email": "ops@hugoshop.com",
"address_line1": "Seoul, Korea"
},
"sender_ioss": null,
"recipient": {
"name": "John Smith",
"phone": "+1-302-555-1234",
"email": "john@example.com",
"address_line1": "350 5th Ave",
"address_line2": "Floor 10",
"address_line3": "Suite 1001",
"city": "New York",
"state": "NY",
"postal_code": "10001",
"country": "US",
"tax_id": null
},
"packages": [
{
"package_index": 1,
"weight": 1.2,
"length": 25,
"width": 15,
"height": 10
},
{
"package_index": 2,
"weight": 2.1,
"length": 40,
"width": 20,
"height": 10
}
],
"items": [
{
"sku": "SKU-001",
"name_kr": "테스트 상품",
"name_en": "Test Product",
"quantity": 2,
"unit_price": 12.5,
"unit_weight": 0.5,
"origin_country": null,
"hs_code": null
}
],
"memo": "Gift wrap requested",
"service_code": "FKTG-SVC-0123456789ABCDEF0123456789ABCDEF"
}
성공 응답 예제 · 합성 데이터
{
"success": true,
"shipment_id": "shp_0123456789abcdef0123456789abcdef",
"fktg_awb": "483920174625",
"external_order_id": "SYNTHETIC-ORDER-1",
"external_shipment_ref": "SYNTHETIC-ORDER-1-P1",
"status": "created",
"message": "발송물이 성공적으로 생성되었습니다.",
"service_code": "FKTG-SVC-0123456789ABCDEF0123456789ABCDEF",
"estimated_rate": {
"currency": "KRW",
"total_cost": 42000,
"charged_weight": 3,
"requires_carrier_confirmation": false,
"dimensions_complete": true,
"calculated_at": "2026-11-05T00:00:00.000Z"
}
}
- 201
- Shipment created successfully
- 400
- Invalid JSON or schema validation failure
- 401
- Unauthorized
- 403
- 403 error; see error.code and correlation_id
- 404
- 404 error; see error.code and correlation_id
- 409
- Duplicate external_shipment_ref
- 422
- Unsupported carrier/service/incoterms policy or unknown carrier service
- 429
- 429 error; see error.code and correlation_id
- 500
- 500 error; see error.code and correlation_id
- 503
- 503 error; retryable=true. Honour Retry-After, then retry the same payload with backoff. See error.code for the fixed server code and correlation_id for support
