{ "openapi": "3.0.3", "info": { "title": "AllDaigou China–Korea Logistics Sandbox API", "version": "1.0.0", "description": "Customer integration pilot. Korean/Chinese operations UI; English API contract. All shipments, tariffs, tracking and reconciliation are test-only. No real customs filing, carrier connection or payment. Server-to-server integration only; do not put keys in browser apps." }, "servers": [ { "url": "/", "description": "Use the origin of this published site as the API base URL." } ], "security": [ { "BearerAuth": [] } ], "paths": { "/api/health": { "get": { "operationId": "get__api_health", "summary": "Sandbox health", "description": "", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "environment": { "type": "string" }, "version": { "type": "string" }, "carrier_connection": { "type": "string" } }, "required": [ "status", "environment", "version", "carrier_connection" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sandbox": { "post": { "operationId": "post__api_sandbox", "summary": "Create an isolated sandbox workspace", "description": "Operator key valid for 30 days. Synthetic data only. No password recovery or automatic data deletion is implemented.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 60 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "key": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "mode": { "type": "string", "enum": [ "sandbox" ] } }, "required": [ "workspace_id", "key", "expires_at", "mode" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspace": { "get": { "operationId": "get__api_v1_workspace", "summary": "Current workspace and role", "description": "", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mode": { "type": "string" }, "created_at": { "type": "string" }, "role": { "type": "string" } }, "required": [ "id", "name", "mode", "created_at", "role" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/rates": { "get": { "operationId": "get__api_v1_rates", "summary": "Read workspace sample tariff", "description": "", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rates" } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "put__api_v1_rates", "summary": "Replace sample tariff (operator)", "description": "Full replacement; sample must remain true. Null sea or air disables quoting for that service. Measured shipments retain their original quote snapshot.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rates" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rates" } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/quotes": { "post": { "operationId": "post__api_v1_quotes", "summary": "Calculate a sample freight quote", "description": "No reservation/payment. Billable weight is max(actual, L×W×H/divisor), rounded up from base_kg by step_kg. Carrier eligibility is a configurable sandbox rule, not a carrier promise. Taxes, duties, collect freight and remote-area fees are excluded.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "type": "string", "enum": [ "sea", "air" ] }, "parcel": { "$ref": "#/components/schemas/Parcel" } }, "required": [ "service", "parcel" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/shipments": { "post": { "operationId": "post__api_v1_shipments", "summary": "Create shipment idempotently", "description": "Unique seller_id + external_order_id per workspace. A normalized identical request with the same key returns 200/replayed:true. Changed content returns 409; keep the key for retries. Key namespace is the whole workspace.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,100}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "responses": { "200": { "description": "Existing shipment replay", "content": { "application/json": { "schema": { "type": "object", "properties": { "shipment": { "$ref": "#/components/schemas/Shipment" }, "replayed": { "type": "boolean" } }, "required": [ "shipment", "replayed" ], "additionalProperties": false } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "shipment": { "$ref": "#/components/schemas/Shipment" }, "replayed": { "type": "boolean" } }, "required": [ "shipment", "replayed" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "get__api_v1_shipments", "summary": "List shipments", "description": "Newest first. q is case-sensitive substring of seller ID, external order ID or shipment ID. Use the event feed for reliable synchronization instead of offset scans.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "submitted", "received", "measured", "ready", "departed", "customs", "handoff", "delivered", "exception", "cancelled" ] } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Shipment" } }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": "integer" } }, "required": [ "items", "total", "offset", "limit" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/shipments/batch": { "post": { "operationId": "post__api_v1_shipments_batch", "summary": "Submit up to 100 independent orders", "description": "HTTP 207 includes per-item success OR error; not atomic across the batch. index is zero-based. Retry unchanged items with the same idempotency key. Malformed batch envelope returns 400.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "type": "object", "properties": { "idempotency_key": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,100}$" }, "shipment": { "$ref": "#/components/schemas/Order" } }, "required": [ "idempotency_key", "shipment" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 } }, "required": [ "orders" ], "additionalProperties": false } } } }, "responses": { "207": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "shipment": { "$ref": "#/components/schemas/Shipment" }, "replayed": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "details": {} }, "required": [ "code" ], "additionalProperties": false } }, "required": [ "index" ], "additionalProperties": false } } }, "required": [ "results" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/shipments/{id}": { "get": { "operationId": "get__api_v1_shipments_id_", "summary": "Shipment detail", "description": "", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/shipments/{id}/events": { "get": { "operationId": "get__api_v1_shipments_id_events", "summary": "Shipment history", "description": "", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__api_v1_shipments_id_events", "summary": "Record warehouse or manual tracking state (operator)", "description": "Optimistic version required. submitted→received→measured→ready→departed→customs→handoff→delivered. measured requires parcel and locks a quote; handoff requires eligible carrier and tracking_number and records one simulated charge. exception resumes only its previous state. Cancellation only before departed, including early-state exceptions. Terminal delivered/cancelled cannot change. No real carrier request is made.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Update" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/events": { "get": { "operationId": "get__api_v1_events", "summary": "Poll workspace event feed", "description": "Ascending opaque global sequence, filtered by workspace. Up to 100. Persist next_cursor only after processing; deduplicate event id. If has_more=true fetch immediately, else poll every 30 seconds. Gaps are normal. No push webhooks in v1.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "next_cursor": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": [ "items", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/stats": { "get": { "operationId": "get__api_v1_stats", "summary": "Count shipments by status", "description": "", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "counts": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "status", "count" ], "additionalProperties": false } } }, "required": [ "counts" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/charges": { "get": { "operationId": "get__api_v1_charges", "summary": "Sample reconciliation statement", "description": "Up to 5,000 latest records in the UTC month. Total covers only returned rows. Not a paid invoice, tax invoice or wallet ledger. One immutable charge snapshot per handoff shipment.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "month", "in": "query", "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "description": "UTC YYYY-MM, default current month" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "month": { "type": "string" }, "currency": { "type": "string" }, "sample": { "type": "boolean" }, "total": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Charge" } }, "settlement": { "type": "string" } }, "required": [ "month", "currency", "sample", "total", "items", "settlement" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/keys": { "get": { "operationId": "get__api_v1_keys", "summary": "List key metadata (operator)", "description": "", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Key" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__api_v1_keys", "summary": "Issue partner key (operator)", "description": "30 days; full workspace read/quote/order-create access. This is a platform integration key, not seller-specific. Never distribute it to downstream sellers.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 2, "maxLength": 60 } }, "required": [ "label" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedKey" } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/keys/{id}": { "delete": { "operationId": "delete__api_v1_keys_id_", "summary": "Revoke a partner key (operator)", "description": "", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operator role required or cross-origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency, duplicate order, version or transition conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rate not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary service failure; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "adg_test_<64 hex characters>" } }, "schemas": { "Parcel": { "type": "object", "properties": { "weight_kg": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 1000 }, "length_cm": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 500 }, "width_cm": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 500 }, "height_cm": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 500 } }, "required": [ "weight_kg", "length_cm", "width_cm", "height_cm" ], "additionalProperties": false }, "Item": { "type": "object", "properties": { "name_en": { "type": "string", "minLength": 1, "maxLength": 200 }, "sku": { "type": "string", "minLength": 1, "maxLength": 200 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10000 }, "unit_value": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 1000000 }, "hs_code": { "type": "string", "pattern": "^[0-9]{6,10}$" }, "product_url": { "type": "string", "format": "uri", "maxLength": 500 } }, "required": [ "name_en", "sku", "quantity", "unit_value" ], "additionalProperties": false }, "Order": { "type": "object", "properties": { "external_order_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "seller_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "service": { "type": "string", "enum": [ "sea", "air" ] }, "port": { "type": "string", "enum": [ "incheon", "pyeongtaek" ], "description": "Air service requires incheon." }, "recipient": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "phone": { "type": "string", "pattern": "^\\+?[0-9 -]{8,20}$" }, "postcode": { "type": "string", "pattern": "^[0-9]{5}$" }, "address": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "name", "phone", "postcode", "address" ], "additionalProperties": false }, "clearance_type": { "type": "string", "enum": [ "personal", "business" ], "description": "Test classification only. No real customs filing." }, "declaration_currency": { "type": "string", "enum": [ "USD", "CNY", "KRW" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" }, "minItems": 1, "maxItems": 50 }, "parcel": { "$ref": "#/components/schemas/Parcel" }, "warehouse_reference": { "type": "string", "maxLength": 120, "default": "" }, "note": { "type": "string", "maxLength": 500, "default": "" } }, "required": [ "external_order_id", "seller_id", "service", "port", "recipient", "clearance_type", "declaration_currency", "items", "parcel" ], "additionalProperties": false }, "Rates": { "type": "object", "properties": { "version": { "type": "string", "minLength": 1, "maxLength": 200 }, "currency": { "type": "string", "enum": [ "KRW" ] }, "sample": { "type": "boolean", "enum": [ true ] }, "sea": { "type": "integer", "minimum": 0, "maximum": 10000000, "nullable": true }, "air": { "type": "integer", "minimum": 0, "maximum": 10000000, "nullable": true }, "base_kg": { "type": "number", "minimum": 0.5, "maximum": 10 }, "step_kg": { "type": "number", "enum": [ 0.5, 1 ] }, "sea_step": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "air_step": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "divisor": { "type": "number", "minimum": 1000, "maximum": 10000 }, "handling": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "oversize_cm": { "type": "number", "minimum": 1, "maximum": 2000 }, "heavy_kg": { "type": "number", "minimum": 1, "maximum": 1000 }, "oversize_fee": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "promotion_note": { "type": "string", "maxLength": 500 } }, "required": [ "version", "currency", "sample", "sea", "air", "base_kg", "step_kg", "sea_step", "air_step", "divisor", "handling", "oversize_cm", "heavy_kg", "oversize_fee", "promotion_note" ], "additionalProperties": false }, "Quote": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "KRW" ] }, "sample": { "type": "boolean" }, "rate_version": { "type": "string" }, "actual_kg": { "type": "number" }, "volumetric_kg": { "type": "number" }, "billable_kg": { "type": "number" }, "freight": { "type": "integer" }, "handling": { "type": "integer" }, "oversize_fee": { "type": "integer" }, "total": { "type": "integer" }, "oversized": { "type": "boolean" }, "exclusions": { "type": "array", "items": { "type": "string" } }, "carrier_options": { "type": "array", "items": { "type": "string", "enum": [ "cj", "hanjin", "kyungdong", "daesin" ] } } }, "required": [ "currency", "sample", "rate_version", "actual_kg", "volumetric_kg", "billable_kg", "freight", "handling", "oversize_fee", "total", "oversized", "exclusions", "carrier_options" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "request_id": { "type": "string" }, "details": { "nullable": true } }, "required": [ "code", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "Update": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "submitted", "received", "measured", "ready", "departed", "customs", "handoff", "delivered", "exception", "cancelled" ] }, "note": { "type": "string", "minLength": 1, "maxLength": 500 }, "parcel": { "$ref": "#/components/schemas/Parcel" }, "carrier": { "type": "string", "enum": [ "cj", "hanjin", "kyungdong", "daesin" ] }, "tracking_number": { "type": "string", "minLength": 5, "maxLength": 80 } }, "required": [ "version", "status", "note" ], "additionalProperties": false }, "Event": { "type": "object", "properties": { "seq": { "type": "integer" }, "id": { "type": "string" }, "shipment": { "type": "string" }, "type": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "seq", "id", "type", "data", "created_at" ], "additionalProperties": false }, "Key": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "role": { "type": "string", "enum": [ "operator", "partner" ] }, "expires_at": { "type": "string", "format": "date-time" }, "revoked": { "type": "integer", "enum": [ 0, 1 ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "label", "role", "expires_at", "revoked", "created_at" ], "additionalProperties": false }, "IssuedKey": { "type": "object", "properties": { "key": { "type": "string", "description": "Shown once. Store on your server; never expose to end users." }, "expires_at": { "type": "string", "format": "date-time" }, "role": { "type": "string", "enum": [ "partner" ] } }, "required": [ "key", "expires_at", "role" ], "additionalProperties": false }, "Charge": { "type": "object", "properties": { "id": { "type": "string" }, "tenant": { "type": "string" }, "shipment": { "type": "string" }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "data": { "$ref": "#/components/schemas/Quote" }, "created_at": { "type": "string", "format": "date-time" }, "external_id": { "type": "string" }, "seller": { "type": "string" } }, "required": [ "id", "tenant", "shipment", "amount", "currency", "data", "created_at", "external_id", "seller" ], "additionalProperties": false }, "Shipment": { "type": "object", "properties": { "external_order_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "seller_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "service": { "type": "string", "enum": [ "sea", "air" ] }, "port": { "type": "string", "enum": [ "incheon", "pyeongtaek" ], "description": "Air service requires incheon." }, "recipient": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "phone": { "type": "string", "pattern": "^\\+?[0-9 -]{8,20}$" }, "postcode": { "type": "string", "pattern": "^[0-9]{5}$" }, "address": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "name", "phone", "postcode", "address" ], "additionalProperties": false }, "clearance_type": { "type": "string", "enum": [ "personal", "business" ], "description": "Test classification only. No real customs filing." }, "declaration_currency": { "type": "string", "enum": [ "USD", "CNY", "KRW" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" }, "minItems": 1, "maxItems": 50 }, "parcel": { "$ref": "#/components/schemas/Parcel" }, "warehouse_reference": { "type": "string", "maxLength": 120, "default": "" }, "note": { "type": "string", "maxLength": 500, "default": "" }, "id": { "type": "string" }, "status": { "type": "string", "enum": [ "submitted", "received", "measured", "ready", "departed", "customs", "handoff", "delivered", "exception", "cancelled" ] }, "version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "quote": { "$ref": "#/components/schemas/Quote" }, "measured_parcel": { "$ref": "#/components/schemas/Parcel" }, "carrier": { "type": "string" }, "tracking_number": { "type": "string" }, "previous_status": { "type": "string" } }, "required": [ "external_order_id", "seller_id", "service", "port", "recipient", "clearance_type", "declaration_currency", "items", "parcel", "id", "status", "version", "created_at", "updated_at" ] } } } }