{"openapi":"3.1.0","info":{"title":"Korea Customs & Trade DX Suite","description":"TradeNPU API Suite","version":"1.0.0"},"paths":{"/v1/marketplace/tariffs":{"get":{"tags":["Marketplace Commercial API"],"summary":"Query Official Korean HS Code, Duty Rates & Exchange Rate","description":"Retrieves real-time Korean statutory customs duty rates (Basic, WTO, and bilateral FTAs like KORUS, RCEP, Korea-EU) and official Korea Customs weekly valuation exchange rates by keyword or 10-digit HS code.","operationId":"query_korea_tariffs_v1_marketplace_tariffs_get","parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","description":"Product name keyword in English/Korean, or 10-digit HS Code","examples":["electric shaver"],"title":"Query"},"description":"Product name keyword in English/Korean, or 10-digit HS Code"},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 2-letter Country code of origin (e.g. 'US', 'CN', 'VN')","examples":["US"],"default":"","title":"Country"},"description":"ISO 2-letter Country code of origin (e.g. 'US', 'CN', 'VN')"},{"name":"x-rapidapi-proxy-secret","in":"header","required":false,"schema":{"type":"string","title":"X-Rapidapi-Proxy-Secret"}},{"name":"x-zyla-proxy-secret","in":"header","required":false,"schema":{"type":"string","title":"X-Zyla-Proxy-Secret"}},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/marketplace/customs-tax/calculate":{"post":{"tags":["Marketplace Commercial API"],"summary":"Calculate Precise Korean Customs Duty, VAT & FTA Savings","description":"Computes the final CIF dutiable value, legal customs duty, 10% VAT, and preferential FTA cost savings in accordance with the Republic of Korea Customs Act. Delivers clean, definitive numerical figures for autonomous AI agents.","operationId":"calculate_korea_tax_v1_marketplace_customs_tax_calculate_post","parameters":[{"name":"x-rapidapi-proxy-secret","in":"header","required":false,"schema":{"type":"string","title":"X-Rapidapi-Proxy-Secret"}},{"name":"x-zyla-proxy-secret","in":"header","required":false,"schema":{"type":"string","title":"X-Zyla-Proxy-Secret"}},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KoreaTaxEstimateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KoreaTaxEstimateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/marketplace/tracking/unipass":{"post":{"tags":["Marketplace Commercial API"],"summary":"Track Real-time Korea Customs Clearance by B/L (Uni-Pass)","description":"Queries official Korea Customs Service (Uni-Pass) in real time to fetch clearance progress, current stage, forwarder information, and release status for any ocean/air B/L or postal EMS tracking number. Returns clean, deterministic status flags for automated logistics workflows.","operationId":"track_korea_customs_v1_marketplace_tracking_unipass_post","parameters":[{"name":"x-rapidapi-proxy-secret","in":"header","required":false,"schema":{"type":"string","title":"X-Rapidapi-Proxy-Secret"}},{"name":"x-zyla-proxy-secret","in":"header","required":false,"schema":{"type":"string","title":"X-Zyla-Proxy-Secret"}},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KoreaCargoTrackingRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KoreaCargoTrackingResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/marketplace/compliance/check":{"post":{"tags":["Marketplace Commercial API"],"summary":"Evaluate Korea Import Regulations, Statutory Certifications & Document Checklist","description":"Analyzes Korean import regulatory requirements under Article 226 of the Korea Customs Act. Queries Korea Customs (Uni-Pass) in real time to assess mandatory statutory certifications (KC Electrical Safety, RRA Radio Waves, MFDS Food Contact & Cosmetics, KATS Child Safety) by 10-digit HS Code or product keyword. Delivers comprehensive assessment including Traffic Light signals (GREEN/YELLOW/RED), statutory governing acts, lead times, essential documentary checklist, and explicit Next-Action directives for AI agents.","operationId":"check_korea_compliance_v1_marketplace_compliance_check_post","parameters":[{"name":"x-rapidapi-proxy-secret","in":"header","required":false,"schema":{"type":"string","title":"X-Rapidapi-Proxy-Secret"}},{"name":"x-zyla-proxy-secret","in":"header","required":false,"schema":{"type":"string","title":"X-Zyla-Proxy-Secret"}},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KoreaComplianceCheckRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KoreaComplianceCheckResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/marketplace/landed-cost/calculate":{"post":{"tags":["Marketplace Commercial API"],"summary":"Calculate 100% All-in Total Landed Cost (Freight + Duty + Port + Inland)","description":"Computes the comprehensive Total Landed Cost for importing cargo into South Korea. Consolidates purchase cost, ocean/air freight (by volume/weight CBM), marine insurance, statutory customs duty & 10% VAT, customs brokerage fees, terminal handling charges (THC/CFS), bonded warehouse storage, and inland trucking. Delivers complete financial transparency, unit cost, margin targets, and percentage breakdown for B2B trade planning.","operationId":"calculate_korea_landed_cost_v1_marketplace_landed_cost_calculate_post","parameters":[{"name":"x-rapidapi-proxy-secret","in":"header","required":false,"schema":{"type":"string","title":"X-Rapidapi-Proxy-Secret"}},{"name":"x-zyla-proxy-secret","in":"header","required":false,"schema":{"type":"string","title":"X-Zyla-Proxy-Secret"}},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KoreaLandedCostRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KoreaLandedCostResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/marketplace/export-incoterms/calculate":{"post":{"tags":["Marketplace Commercial API"],"summary":"Convert Factory Price (EXW) to Export Incoterms Quotes (FOB, CFR, CIF)","description":"Converts domestic factory gate price (EXW in KRW) into international export commercial terms (FOB, CFR, CIF) in USD. Automatically factors in Korean origin port handling, export customs fees, international ocean/air freight to target destination, and marine cargo insurance. Designed for instant proforma invoice (P/I) quoting by autonomous agents.","operationId":"calculate_korea_export_incoterms_v1_marketplace_export_incoterms_calculate_post","parameters":[{"name":"x-rapidapi-proxy-secret","in":"header","required":false,"schema":{"type":"string","title":"X-Rapidapi-Proxy-Secret"}},{"name":"x-zyla-proxy-secret","in":"header","required":false,"schema":{"type":"string","title":"X-Zyla-Proxy-Secret"}},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KoreaExportIncotermsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KoreaExportIncotermsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"KoreaCargoTrackingRequest":{"properties":{"hbl_no":{"type":"string","title":"Hbl No","description":"10~12 digit House B/L (Waybill) number or EMS tracking code","examples":["607512345678"]}},"type":"object","required":["hbl_no"],"title":"KoreaCargoTrackingRequest"},"KoreaCargoTrackingResponse":{"properties":{"hbl_no":{"type":"string","title":"Hbl No","description":"House B/L or EMS tracking number"},"inbound_type":{"type":"string","title":"Inbound Type","description":"'customs' (Ocean/Air Cargo) or 'ems' (Postal)"},"status":{"type":"string","title":"Status","description":"Overall clearance status: 'CLEARED', 'IN_CLEARANCE', or 'NOT_FOUND'"},"current_stage":{"type":"string","title":"Current Stage","description":"Current customs processing step description in Korean"},"cargo_name":{"type":"string","title":"Cargo Name","description":"Registered commodity description","default":""},"importer_or_agent":{"type":"string","title":"Importer Or Agent","description":"Forwarder / Shipping agent name","default":""},"is_cleared":{"type":"boolean","title":"Is Cleared","description":"True if cargo release or declaration acceptance is completed"},"timeline":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Timeline","description":"Clean chronological history of customs events (date, step, location)","default":[]}},"type":"object","required":["hbl_no","inbound_type","status","current_stage","is_cleared"],"title":"KoreaCargoTrackingResponse"},"KoreaComplianceCheckRequest":{"properties":{"query":{"type":"string","title":"Query","description":"10-digit Korean HS Code (e.g. '8517621020') or product keyword in English/Korean","examples":["8517621020"]},"product_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Name","description":"Optional English or Korean product name (e.g. 'Smart Watch', 'Wireless Bluetooth Earbuds')","default":"","examples":["Smart Watch with Bluetooth"]}},"type":"object","required":["query"],"title":"KoreaComplianceCheckRequest"},"KoreaComplianceCheckResponse":{"properties":{"hs_code":{"type":"string","title":"Hs Code","description":"Target Korean HS Code"},"item_name":{"type":"string","title":"Item Name","description":"Product description evaluated","default":""},"traffic_light":{"type":"string","title":"Traffic Light","description":"Risk signal: 'GREEN' (Exempt), 'YELLOW' (Pre-registration), 'RED' (Mandatory KC Lab Testing), or 'GRAY' (10-digit required)"},"status":{"type":"string","title":"Status","description":"Machine-readable tactical status code: 'EXEMPT', 'REGISTRATION_OR_QUARANTINE_REQUIRED', 'MANDATORY_TESTING_REQUIRED', 'NEEDS_10_DIGIT_HS'"},"status_title":{"type":"string","title":"Status Title","description":"Clear human/agent evaluation summary title in English"},"status_description":{"type":"string","title":"Status Description","description":"Comprehensive legal assessment description based on Article 226 of the Korea Customs Act"},"estimated_lead_time":{"type":"string","title":"Estimated Lead Time","description":"Estimated statutory certification lead time before customs entry"},"action_required":{"type":"string","title":"Action Required","description":"Explicit next-action directive for AI agents (e.g. 'OBTAIN_MANDATORY_KC_OR_RRA_CERTIFICATE_BEFORE_SHIPPING')"},"total_statutory_laws":{"type":"integer","title":"Total Statutory Laws","description":"Number of statutory laws governing this cargo"},"statutory_laws":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Statutory Laws","description":"Detailed governing statutory acts (RRA Radio Waves, KATS KC Safety, MFDS Food, etc.)","default":[]},"required_documents":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Required Documents","description":"Mandatory checklist of statutory documents and technical dossiers required before clearance","default":[]},"candidates":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Candidates","description":"List of 10-digit HS candidates if query was an ambiguous keyword","default":[]}},"type":"object","required":["hs_code","traffic_light","status","status_title","status_description","estimated_lead_time","action_required","total_statutory_laws"],"title":"KoreaComplianceCheckResponse"},"KoreaExportIncotermsRequest":{"properties":{"factory_price_krw":{"type":"number","minimum":0.0,"title":"Factory Price Krw","description":"Factory manufacturing unit price (EXW) in KRW","examples":[35000.0]},"qty":{"type":"integer","minimum":1.0,"title":"Qty","description":"Export batch quantity","default":500,"examples":[500]},"cbm":{"type":"number","minimum":0.01,"title":"Cbm","description":"Total export cargo volume in CBM","default":2.5,"examples":[2.5]},"dest_key":{"type":"string","title":"Dest Key","description":"Destination port code: 'US_LA', 'US_NY', 'VN_HCM', 'JP_TYO', 'DE_HAM'","default":"US_LA","examples":["US_LA"]},"transport_mode":{"type":"string","title":"Transport Mode","description":"'SEA_LCL' or 'AIR'","default":"SEA_LCL","examples":["SEA_LCL"]},"usd_rate":{"type":"number","exclusiveMinimum":0.0,"title":"Usd Rate","description":"Exchange rate (KRW per 1 USD)","default":1380.0,"examples":[1380.0]}},"type":"object","required":["factory_price_krw"],"title":"KoreaExportIncotermsRequest"},"KoreaExportIncotermsResponse":{"properties":{"qty":{"type":"integer","title":"Qty"},"cbm":{"type":"number","title":"Cbm"},"destination_name":{"type":"string","title":"Destination Name"},"transit_days":{"type":"string","title":"Transit Days"},"usd_rate":{"type":"number","title":"Usd Rate"},"unit_quotes_usd":{"additionalProperties":true,"type":"object","title":"Unit Quotes Usd","description":"Unit price per Incoterms term: {'EXW': ..., 'FOB': ..., 'CFR': ..., 'CIF': ...} in USD"},"total_quotes_usd":{"additionalProperties":true,"type":"object","title":"Total Quotes Usd","description":"Total batch quote per Incoterms term in USD"},"cost_components_krw":{"additionalProperties":true,"type":"object","title":"Cost Components Krw","description":"Detailed breakdown of factory, origin local, ocean freight, and insurance costs in KRW"}},"type":"object","required":["qty","cbm","destination_name","transit_days","usd_rate","unit_quotes_usd","total_quotes_usd","cost_components_krw"],"title":"KoreaExportIncotermsResponse"},"KoreaLandedCostRequest":{"properties":{"product_price_usd":{"type":"number","minimum":0.0,"title":"Product Price Usd","description":"Unit purchase/invoice price in USD","examples":[15.0]},"qty":{"type":"integer","minimum":1.0,"title":"Qty","description":"Order quantity","default":500,"examples":[500]},"cbm":{"type":"number","minimum":0.01,"title":"Cbm","description":"Total cargo volume in CBM","default":2.5,"examples":[2.5]},"weight_kg":{"type":"number","minimum":0.1,"title":"Weight Kg","description":"Gross cargo weight in KG","default":450.0,"examples":[450.0]},"duty_rate_pct":{"type":"number","minimum":0.0,"title":"Duty Rate Pct","description":"Applicable customs duty rate in percent (e.g. 8.0 for 8%)","default":8.0,"examples":[8.0]},"origin_key":{"type":"string","title":"Origin Key","description":"Origin port code: 'CN_SHA', 'CN_SZX', 'US_LA', 'US_NY', 'VN_HCM', 'JP_TYO', 'DE_HAM'","default":"CN_SHA","examples":["CN_SHA"]},"transport_mode":{"type":"string","title":"Transport Mode","description":"'SEA_LCL', 'AIR', 'SEA_FCL_20', 'SEA_FCL_40'","default":"SEA_LCL","examples":["SEA_LCL"]},"dest_zone":{"type":"string","title":"Dest Zone","description":"'local' (Seoul/Incheon) or 'provincial' (Other regions)","default":"local","examples":["local"]},"margin_pct":{"type":"number","exclusiveMaximum":100.0,"minimum":0.0,"title":"Margin Pct","description":"Target gross profit margin percentage","default":30.0,"examples":[30.0]},"usd_rate":{"type":"number","exclusiveMinimum":0.0,"title":"Usd Rate","description":"Exchange rate (KRW per 1 USD)","default":1380.0,"examples":[1380.0]}},"type":"object","required":["product_price_usd"],"title":"KoreaLandedCostRequest"},"KoreaLandedCostResponse":{"properties":{"qty":{"type":"integer","title":"Qty"},"cbm":{"type":"number","title":"Cbm"},"weight_kg":{"type":"number","title":"Weight Kg"},"chargeable_weight":{"type":"number","title":"Chargeable Weight"},"origin_name":{"type":"string","title":"Origin Name"},"transit_days":{"type":"string","title":"Transit Days"},"total_goods_krw":{"type":"integer","title":"Total Goods Krw"},"total_goods_usd":{"type":"number","title":"Total Goods Usd"},"freight_krw":{"type":"integer","title":"Freight Krw"},"freight_usd":{"type":"number","title":"Freight Usd"},"insurance_krw":{"type":"integer","title":"Insurance Krw"},"cif_krw":{"type":"integer","title":"Cif Krw"},"cif_usd":{"type":"number","title":"Cif Usd"},"duty_krw":{"type":"integer","title":"Duty Krw"},"vat_krw":{"type":"integer","title":"Vat Krw"},"total_tax_krw":{"type":"integer","title":"Total Tax Krw"},"broker_fee_krw":{"type":"integer","title":"Broker Fee Krw"},"port_work_krw":{"type":"integer","title":"Port Work Krw"},"wh_storage_krw":{"type":"integer","title":"Wh Storage Krw"},"inland_truck_krw":{"type":"integer","title":"Inland Truck Krw"},"total_local_krw":{"type":"integer","title":"Total Local Krw"},"total_landed_cost_krw":{"type":"integer","title":"Total Landed Cost Krw","description":"100% Complete All-in Total Landed Cost in KRW"},"total_landed_cost_usd":{"type":"number","title":"Total Landed Cost Usd","description":"100% Complete All-in Total Landed Cost in USD"},"unit_landed_cost_krw":{"type":"integer","title":"Unit Landed Cost Krw","description":"Net landed cost per unit in KRW"},"margin_pct":{"type":"number","title":"Margin Pct"},"target_selling_price_krw":{"type":"integer","title":"Target Selling Price Krw","description":"Recommended selling price based on margin in KRW"},"profit_per_unit_krw":{"type":"integer","title":"Profit Per Unit Krw","description":"Net profit per unit in KRW"},"cost_breakdown_pct":{"additionalProperties":true,"type":"object","title":"Cost Breakdown Pct","description":"Percentage share of goods, freight, tax, and local logistics"}},"type":"object","required":["qty","cbm","weight_kg","chargeable_weight","origin_name","transit_days","total_goods_krw","total_goods_usd","freight_krw","freight_usd","insurance_krw","cif_krw","cif_usd","duty_krw","vat_krw","total_tax_krw","broker_fee_krw","port_work_krw","wh_storage_krw","inland_truck_krw","total_local_krw","total_landed_cost_krw","total_landed_cost_usd","unit_landed_cost_krw","margin_pct","target_selling_price_krw","profit_per_unit_krw","cost_breakdown_pct"],"title":"KoreaLandedCostResponse"},"KoreaTaxEstimateRequest":{"properties":{"goods_price":{"type":"number","minimum":0.0,"title":"Goods Price","description":"Invoice price of goods. If FOB, freight/insurance can be added.","examples":[1500.0]},"incoterms":{"type":"string","title":"Incoterms","description":"Delivery term: 'FOB' (freight & insurance will be added to dutiable value) or 'CIF'","default":"FOB","examples":["FOB"]},"freight":{"type":"number","minimum":0.0,"title":"Freight","description":"International ocean/air freight charges (added under FOB terms)","default":0.0,"examples":[120.0]},"insurance":{"type":"number","minimum":0.0,"title":"Insurance","description":"Marine cargo insurance premium (added under FOB terms)","default":0.0,"examples":[15.0]},"exchange_rate":{"type":"number","exclusiveMinimum":0.0,"title":"Exchange Rate","description":"Korea Customs Service officially announced weekly exchange rate (KRW per 1 USD)","default":1350.0,"examples":[1385.5]},"currency":{"type":"string","title":"Currency","description":"Currency code: 'USD' or 'KRW'","default":"USD","examples":["USD"]},"applied_duty_rate":{"type":"number","minimum":0.0,"title":"Applied Duty Rate","description":"Duty rate applied (e.g. FTA rate or Basic rate in percent, 8.0 for 8%)","examples":[0.0]},"normal_duty_rate":{"type":"number","minimum":0.0,"title":"Normal Duty Rate","description":"Basic or WTO standard statutory duty rate in percent (used to calculate FTA savings)","default":8.0,"examples":[8.0]}},"type":"object","required":["goods_price","applied_duty_rate"],"title":"KoreaTaxEstimateRequest"},"KoreaTaxEstimateResponse":{"properties":{"cif_krw":{"type":"integer","title":"Cif Krw","description":"Final customs dutiable value in KRW"},"cif_usd":{"type":"number","title":"Cif Usd","description":"Final customs dutiable value in USD"},"duty_krw":{"type":"integer","title":"Duty Krw","description":"Calculated customs duty in KRW"},"duty_usd":{"type":"number","title":"Duty Usd","description":"Calculated customs duty in USD"},"vat_krw":{"type":"integer","title":"Vat Krw","description":"10% Value Added Tax in KRW"},"vat_usd":{"type":"number","title":"Vat Usd","description":"10% Value Added Tax in USD"},"total_tax_krw":{"type":"integer","title":"Total Tax Krw","description":"Final landed customs tax payable (Duty + VAT) in KRW"},"total_tax_usd":{"type":"number","title":"Total Tax Usd","description":"Final landed customs tax payable (Duty + VAT) in USD"},"standard_tax_krw":{"type":"integer","title":"Standard Tax Krw","description":"Standard non-preferential tax amount in KRW"},"fta_savings_krw":{"type":"integer","title":"Fta Savings Krw","description":"Amount saved by applying FTA preferential duty in KRW"},"fta_savings_usd":{"type":"number","title":"Fta Savings Usd","description":"Amount saved by applying FTA preferential duty in USD"}},"type":"object","required":["cif_krw","cif_usd","duty_krw","duty_usd","vat_krw","vat_usd","total_tax_krw","total_tax_usd","standard_tax_krw","fta_savings_krw","fta_savings_usd"],"title":"KoreaTaxEstimateResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}