{ "openapi": "3.1.0", "info": { "title": "BuyingMesh Procurement API", "version": "0.5.4", "description": "Structured supplier and product API for buying agents. Product discovery exposes approved merchant listings; inquiries can be sent to suppliers even when inventory needs confirmation. x402 payments and real order creation remain disabled until production settlement and fulfillment are ready. All REST responses use the JSON envelope {status, data, error}; MCP remains JSON-RPC." }, "servers": [ { "url": "https://buyingmesh.com" } ], "paths": { "/v1/support/contact": { "post": { "operationId": "contactSupport", "summary": "Send an agent support request to the BuyingMesh operator", "description": "Sends a short support request to the operator mailbox. Do not include passwords, private keys, payment secrets or other sensitive credentials.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportRequest" } } } }, "responses": { "202": { "description": "Support request accepted for email delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "description": "Support rate limit reached" }, "503": { "description": "Support email is not configured" } } } }, "/v1/merchant/applications": { "post": { "operationId": "createMerchantApplication", "summary": "Submit a merchant onboarding application", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "companyName", "workEmail", "contactName", "category", "catalogSize", "shippingOrigin", "dataAuthorizationConfirmed", "imageRightsConfirmed" ], "properties": { "companyName": { "type": "string", "maxLength": 160 }, "workEmail": { "type": "string", "format": "email" }, "category": { "type": "string", "maxLength": 160 }, "catalogSize": { "type": "string", "maxLength": 80 }, "legalName": { "type": "string", "maxLength": 200 }, "contactName": { "type": "string", "maxLength": 120 }, "contactPhone": { "type": "string", "maxLength": 40 }, "supplierType": { "type": "string", "enum": [ "manufacturer", "trading_company", "distributor" ] }, "countryRegion": { "type": "string", "maxLength": 80 }, "shippingOrigin": { "type": "string", "maxLength": 120 }, "productionCapacity": { "type": "string", "maxLength": 500 }, "qualificationSummary": { "type": "string", "maxLength": 1000 }, "qualificationEvidenceUrl": { "type": "string", "format": "uri", "pattern": "^https://" }, "fulfillmentProfile": { "type": "string", "maxLength": 1000 }, "websiteUrl": { "type": "string", "format": "uri", "pattern": "^https://" }, "description": { "type": "string", "maxLength": 1200 }, "dataAuthorizationConfirmed": { "type": "boolean", "const": true }, "imageRightsConfirmed": { "type": "boolean", "const": true } } } } } }, "responses": { "201": { "description": "Application received" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/merchant/products/import": { "post": { "operationId": "importMerchantProducts", "summary": "Import up to 5,000 private source or merchant product rows for review", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "applicationId", "products" ], "properties": { "applicationId": { "type": "string", "format": "uuid" }, "products": { "type": "array", "maxItems": 5000, "items": { "$ref": "#/components/schemas/MerchantProductImport" } }, "sourcePlatform": { "type": "string", "enum": [ "merchant" ], "description": "Only supplier-owned or supplier-authorized product data is accepted for onboarding." }, "targetCurrency": { "type": "string", "enum": [ "USD", "CNY" ], "default": "USD" }, "markupMultiplier": { "type": "number", "minimum": 0.01, "default": 2 }, "cnyToUsdRate": { "type": "number", "minimum": 0.000001, "default": 0.138 } } } } } }, "responses": { "201": { "description": "Import accepted for review" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/admin/applications": { "get": { "operationId": "listMerchantApplicationsForReview", "summary": "List merchant applications and review counts", "security": [ { "adminReviewKey": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "received", "under_review", "approved", "changes_requested", "needs_info", "rejected" ] } } ], "responses": { "200": { "description": "Review queue" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/admin/applications/{applicationId}": { "get": { "operationId": "getMerchantApplicationForReview", "summary": "Get an application and its submitted products", "security": [ { "adminReviewKey": [] } ], "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Application detail" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "reviewMerchantApplication", "summary": "Approve, reject or request changes for an application", "security": [ { "adminReviewKey": [] } ], "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Admin-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewAction" } } } }, "responses": { "200": { "description": "Review saved" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/admin/suppliers/{supplierId}": { "patch": { "operationId": "updateSupplierProfile", "summary": "Update reviewed supplier storefront metadata and credential review records", "security": [ { "adminReviewKey": [] } ], "parameters": [ { "name": "supplierId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string" }, "legalName": { "type": "string" }, "description": { "type": "string" }, "websiteUrl": { "type": "string", "format": "uri" }, "countryRegion": { "type": "string" }, "supplierType": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "credentials": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "Supplier profile updated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/admin/products": { "get": { "operationId": "listMerchantProductsForReview", "summary": "List submitted products for review", "security": [ { "adminReviewKey": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending_review", "approved", "changes_requested", "needs_info", "rejected" ] } } ], "responses": { "200": { "description": "Product review queue" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/admin/traffic": { "get": { "operationId": "getTrafficSummary", "summary": "Get site, API and agent crawler traffic", "security": [ { "adminReviewKey": [] } ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 14 } } ], "responses": { "200": { "description": "Traffic summary with agent signatures and recent edge events", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TrafficSummary" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/admin/products/{productId}": { "post": { "operationId": "reviewMerchantProduct", "summary": "Approve or request changes for a submitted product", "security": [ { "adminReviewKey": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Admin-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewAction" } } } }, "responses": { "200": { "description": "Review saved" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/products": { "get": { "operationId": "searchProducts", "summary": "Search structured products", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "sku", "in": "query", "description": "Exact SKU match", "schema": { "type": "string" } }, { "name": "gtin", "in": "query", "description": "Exact GTIN match", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string", "example": "stainless-fasteners" } }, { "name": "supplierId", "in": "query", "schema": { "type": "string" } }, { "name": "supplierSlug", "in": "query", "schema": { "type": "string" } }, { "name": "material", "in": "query", "description": "Case-insensitive partial match", "schema": { "type": "string" } }, { "name": "size", "in": "query", "description": "Case-insensitive partial match", "schema": { "type": "string" } }, { "name": "minMoq", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "maxMoq", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "minPrice", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "maxPrice", "in": "query", "schema": { "type": "number", "format": "double" } }, { "name": "currency", "in": "query", "schema": { "type": "string", "example": "USD" } }, { "name": "minInventory", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "inventoryStatus", "in": "query", "schema": { "type": "string", "enum": [ "confirmed", "unknown" ] } }, { "name": "maxLeadTimeDays", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "qualificationStatus", "in": "query", "schema": { "type": "string" } }, { "name": "verifiedOnly", "in": "query", "schema": { "type": "boolean" } }, { "name": "freshnessWithinMinutes", "in": "query", "schema": { "type": "integer", "default": 60 } }, { "name": "environment", "in": "query", "description": "Only reviewed merchant listings are returned. inventoryStatus is explicit; unknown inventory requires fresh supplier confirmation before quoting.", "schema": { "type": "string", "enum": [ "production" ], "default": "production" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Product results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiProductSearchResponse" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/suppliers": { "get": { "operationId": "searchSuppliers", "summary": "Search approved public supplier storefronts", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "countryRegion", "in": "query", "schema": { "type": "string" } }, { "name": "supplierType", "in": "query", "schema": { "type": "string" } }, { "name": "verified", "in": "query", "schema": { "type": "boolean" } }, { "name": "minProducts", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Public supplier storefronts with reviewed credentials and platform-observed performance summaries" } } } }, "/v1/suppliers/{supplierId}": { "get": { "operationId": "getSupplier", "summary": "Get a public supplier storefront by stable ID or slug", "parameters": [ { "name": "supplierId", "in": "path", "required": true, "description": "Stable supplier ID or public slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Supplier profile", "public credentials": null, "catalog counts and performance summary": null }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/suppliers/{supplierId}/performance": { "get": { "operationId": "getSupplierPerformance", "summary": "Get platform-observed supplier fulfillment performance", "parameters": [ { "name": "supplierId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Supplier performance summary with sample size and as-of timestamp" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/suppliers/{supplierId}/products": { "get": { "operationId": "listSupplierProducts", "summary": "Search the approved production catalog for one supplier", "parameters": [ { "name": "supplierId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sku", "in": "query", "description": "Exact SKU match", "schema": { "type": "string" } }, { "name": "gtin", "in": "query", "description": "Exact GTIN match", "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "material", "in": "query", "schema": { "type": "string" } }, { "name": "size", "in": "query", "schema": { "type": "string" } }, { "name": "minMoq", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "maxMoq", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "minPrice", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "maxPrice", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "minInventory", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "maxLeadTimeDays", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "verifiedOnly", "in": "query", "schema": { "type": "boolean" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Exact supplier SKU search and paginated product records" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/products/{sku}": { "get": { "operationId": "getProduct", "summary": "Get a complete product JSON-LD document", "parameters": [ { "name": "sku", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "environment", "in": "query", "description": "Only the approved merchant catalog is available; withdrawn listings return 404.", "schema": { "type": "string", "enum": [ "production" ], "default": "production" } } ], "responses": { "200": { "description": "Product detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiProductResponse" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/merchant/products": { "get": { "operationId": "listMerchantProducts", "summary": "List merchant products", "parameters": [ { "name": "X-Merchant-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product list" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "createMerchantProduct", "summary": "Create a merchant product", "parameters": [ { "name": "X-Merchant-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "responses": { "201": { "description": "Product created" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/merchant/products/{sku}": { "patch": { "operationId": "updateMerchantProduct", "summary": "Update merchant price, inventory, lead time or qualifications", "parameters": [ { "name": "sku", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Merchant-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Product updated" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/quotes": { "post": { "operationId": "createQuote", "summary": "Create a retrievable quote from SKU, quantity and destination", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } } }, "responses": { "201": { "description": "Quote result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiQuoteResponse" } } } }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/quotes/compare-suppliers": { "post": { "operationId": "compareSupplierOffers", "summary": "Compare eligible supplier offers for requested SKUs", "description": "Read-only estimate. Shipping is shown separately and requires carrier confirmation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } } }, "responses": { "200": { "description": "Supplier offer comparison" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/shipping/rates": { "post": { "operationId": "searchShippingRates", "summary": "Estimate shipping rates by destination, weight and dimensions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "destination" ], "properties": { "destination": { "type": "object" }, "origin": { "type": "object" }, "weightKg": { "type": "number" }, "quantity": { "type": "integer" }, "dimensionsCm": { "type": "object" } } } } } }, "responses": { "200": { "description": "Non-binding shipping estimates" } } } }, "/v1/tariffs/lookup": { "post": { "operationId": "lookupTariffs", "summary": "Return a preliminary HS-code and destination duty range", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hsCode", "destinationCountry" ], "properties": { "hsCode": { "type": "string" }, "destinationCountry": { "type": "string" }, "customsValue": { "type": "number" }, "currency": { "type": "string" } } } } } }, "responses": { "200": { "description": "Non-binding tariff estimate requiring broker confirmation" } } } }, "/v1/landed-cost": { "post": { "operationId": "estimateLandedCost", "summary": "Estimate total landed cost for a destination", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } } }, "responses": { "200": { "description": "Landed-cost range with assumptions" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/buyer-confirmations": { "post": { "operationId": "requestBuyerConfirmation", "summary": "Create a short-lived buyer confirmation request", "description": "No payment or order side effect. Use before createOrder.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quoteId" ], "properties": { "quoteId": { "type": "string", "pattern": "^q_" }, "buyerNote": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "201": { "description": "Confirmation request created" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/quotes/{quoteId}": { "get": { "operationId": "getQuote", "summary": "Retrieve a quote snapshot by quote ID", "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^q_" } } ], "responses": { "200": { "description": "Quote detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiQuoteResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/orders": { "post": { "operationId": "createOrder", "summary": "Create a B2B procurement order", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } } }, "responses": { "201": { "description": "Order confirmed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiOrderResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/orders/{orderId}": { "get": { "operationId": "getOrder", "summary": "Get order and latest fulfillment status", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Order detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiOrderResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/orders/{orderId}/status": { "post": { "operationId": "transitionOrder", "summary": "Advance the order state machine", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "shipped", "tracking_updated", "eta_updated", "delivered", "accepted", "released", "disputed", "cancelled" ] }, "data": { "type": "object" } } } } } }, "responses": { "200": { "description": "Status advanced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiOrderResponse" } } } }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/orders/{orderId}/cancel": { "post": { "operationId": "cancelOrder", "summary": "Cancel an order while its current state allows cancellation", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Cancelled order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiOrderResponse" } } } }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/admin/orders": { "get": { "operationId": "adminListOrders", "summary": "List persisted orders for the merchant console", "security": [ { "adminReviewKey": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Order summaries and status counts", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/admin/catalog-quality": { "get": { "operationId": "getCatalogQuality", "summary": "Read catalog quality and quote readiness metrics", "security": [ { "adminReviewKey": [] } ], "responses": { "200": { "description": "Catalog quality summary" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/admin/test-catalog/cleanup": { "post": { "operationId": "withdrawInternalTestCatalog", "summary": "Preview or withdraw historical internal test listings", "description": "Marks rows explicitly classified as internal test data as withdrawn and preserves them for audit. This operation never deletes product or merchant application records.", "security": [ { "adminReviewKey": [] } ], "parameters": [ { "name": "confirm", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "WITHDRAW_INTERNAL_TEST_CATALOG" ] } } ], "responses": { "200": { "description": "Withdrawal preview or result" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/orders/{orderId}/tracking": { "post": { "operationId": "attachTracking", "summary": "Attach tracking and trigger a tracking sync", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "carrier", "trackingNumber" ], "properties": { "carrier": { "type": "string", "enum": [ "kuaidi100", "17track", "other" ] }, "provider": { "type": "string", "description": "Provider adapter. Defaults to carrier." }, "carrierCode": { "type": "string", "description": "Optional carrier code used by the provider." }, "trackingNumber": { "type": "string" } } } } } }, "responses": { "202": { "description": "Async sync accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } } } } }, "/v1/orders/{orderId}/tracking/sync": { "post": { "operationId": "syncTracking", "summary": "Refresh shipment events and ETA from the configured carrier adapter", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Tracking sync accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/webhook-subscriptions": { "post": { "operationId": "createWebhookSubscription", "summary": "Register an order status webhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events", "secret" ], "properties": { "url": { "type": "string", "format": "uri" }, "secret": { "type": "string", "maxLength": 240, "description": "Optional HMAC-SHA256 signing secret" }, "supplierId": { "type": "string", "description": "Optional supplier scope. When set", "only orders for this supplier are delivered.": null }, "events": { "type": "array", "items": { "type": "string", "enum": [ "order.confirmed", "order.shipped", "order.tracking_updated", "order.eta_updated", "order.delivered", "order.accepted", "order.released", "order.disputed" ] } } } } } } }, "responses": { "201": { "description": "Webhook registered" } } } }, "/v1/webhook-deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "List webhook delivery records", "responses": { "200": { "description": "Webhook delivery records" } } } }, "/v1/admin/suppliers/{supplierId}/notification-channel": { "get": { "operationId": "getSupplierNotificationChannel", "summary": "Read a supplier notification channel", "security": [ { "adminReviewKey": [] } ], "parameters": [ { "name": "supplierId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Supplier notification channel" } } }, "patch": { "operationId": "updateSupplierNotificationChannel", "summary": "Configure a supplier webhook and notification email", "security": [ { "adminReviewKey": [] } ], "parameters": [ { "name": "supplierId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookUrl": { "type": "string", "format": "uri" }, "webhookSecret": { "type": "string", "minLength": 16 }, "notificationEmail": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Supplier notification channel saved" } } } }, "/v1/admin/suppliers/{supplierId}/notifications": { "get": { "operationId": "listSupplierNotifications", "summary": "List supplier order notifications", "security": [ { "adminReviewKey": [] } ], "parameters": [ { "name": "supplierId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100 } } ], "responses": { "200": { "description": "Supplier notification queue and delivery states" } } } }, "/v1/inquiries": { "post": { "operationId": "submitInquiry", "summary": "Submit a structured, non-binding supplier inquiry", "description": "Sends SKU, quantity, destination, buyer and agent context to the responsible merchant. An inquiry can be submitted while inventory is unknown; it does not create an order, reserve inventory or move money. Reuse the Idempotency-Key header to safely retry.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InquiryRequest" } } } }, "responses": { "202": { "description": "Inquiry stored and supplier notification attempted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InquiryEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/inquiries/{inquiryId}": { "get": { "operationId": "getInquiry", "summary": "Read inquiry status and supplier notification delivery", "parameters": [ { "name": "inquiryId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^inq_" } } ], "responses": { "200": { "description": "Inquiry record and notification status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InquiryEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "adminReviewKey": { "type": "apiKey", "in": "header", "name": "X-Admin-Key" } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 } }, "IdempotencyKeyOptional": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 180 } } }, "responses": { "PaymentRequired": { "description": "An x402 payment is required for this query", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Base64url-encoded x402 v2 payment required object" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "payment_required" }, "paymentRequirements": { "type": "object" } } } } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Idempotency or inventory conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Merchant authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "SuccessEnvelope": { "type": "object", "required": [ "status", "data", "error" ], "properties": { "status": { "type": "string", "const": "ok" }, "data": { "type": "object" }, "error": { "type": "null" } } }, "SupportRequest": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "minLength": 5, "maxLength": 4000 }, "subject": { "type": "string", "maxLength": 180 }, "agentName": { "type": "string", "maxLength": 180 }, "agentId": { "type": "string", "maxLength": 180 }, "replyTo": { "type": "string", "format": "email" }, "page": { "type": "string", "maxLength": 240 }, "context": { "type": "object", "additionalProperties": true } } }, "ApiProductSearchResponse": { "type": "object", "required": [ "status", "data", "error" ], "properties": { "status": { "type": "string", "const": "ok" }, "data": { "$ref": "#/components/schemas/ProductSearchResponse" }, "error": { "type": "null" } } }, "ApiProductResponse": { "type": "object", "required": [ "status", "data", "error" ], "properties": { "status": { "type": "string", "const": "ok" }, "data": { "$ref": "#/components/schemas/Product" }, "error": { "type": "null" } } }, "ApiQuoteResponse": { "type": "object", "required": [ "status", "data", "error" ], "properties": { "status": { "type": "string", "const": "ok" }, "data": { "$ref": "#/components/schemas/QuoteResponse" }, "error": { "type": "null" } } }, "ApiOrderResponse": { "type": "object", "required": [ "status", "data", "error" ], "properties": { "status": { "type": "string", "const": "ok" }, "data": { "$ref": "#/components/schemas/Order" }, "error": { "type": "null" } } }, "TrafficSummary": { "type": "object", "required": [ "periodDays", "totals", "daily", "funnel", "agents", "paths", "recent" ], "properties": { "periodDays": { "type": "integer" }, "totals": { "type": "object", "properties": { "requests": { "type": "integer" }, "agents": { "type": "integer" }, "humans": { "type": "integer" }, "apiClients": { "type": "integer" } } }, "daily": { "type": "array", "items": { "type": "object" } }, "funnel": { "type": "array", "items": { "type": "object", "properties": { "stage": { "type": "string" }, "requests": { "type": "integer" }, "last_seen": { "type": [ "string", "null" ] }, "sample": { "type": "boolean" } } } }, "agents": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "requests": { "type": "integer" }, "last_seen": { "type": "string" } } } }, "paths": { "type": "array", "items": { "type": "object" } }, "recent": { "type": "array", "items": { "type": "object" } } } }, "ReviewAction": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "received", "under_review", "approved", "changes_requested", "needs_info", "rejected", "pending_review" ] }, "note": { "type": "string", "maxLength": 1000 } } }, "Product": { "type": "object", "required": [ "sku", "name", "material", "size", "moq", "minOrderQuantity", "price", "inventory", "leadTimeDays", "supplierQualifications", "dataFreshness" ], "properties": { "@context": { "type": "string", "const": "https://schema.org" }, "@type": { "type": "string", "const": "Product" }, "sku": { "type": "string" }, "gtin": { "type": "string" }, "name": { "type": "string" }, "material": { "type": "string" }, "size": { "type": "string" }, "moq": { "type": "integer", "minimum": 100, "description": "Minimum order quantity in purchasable units" }, "minOrderQuantity": { "type": "integer", "minimum": 100, "description": "Alias of moq" }, "price": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" } } }, "inventory": { "type": [ "integer", "null" ], "minimum": 0, "description": "Null when the latest supplier snapshot has not confirmed stock" }, "inventoryStatus": { "type": "string", "enum": [ "confirmed", "unknown" ] }, "leadTimeDays": { "type": "integer", "minimum": 0 }, "supplierQualifications": { "type": "array", "items": { "type": "string" } }, "dataFreshness": { "type": "string", "format": "date-time" }, "isTestData": { "type": "boolean", "deprecated": true, "description": "Internal test-data marker. Public catalog responses only contain approved merchant records." }, "dataEnvironment": { "type": "string", "enum": [ "production" ] } } }, "ProductSearchResponse": { "type": "object", "required": [ "items", "nextCursor", "queryCost" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "nextCursor": { "type": [ "string", "null" ] }, "queryCost": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } } } } }, "MerchantProductImport": { "type": "object", "required": [ "sku", "title", "moq", "price", "price_currency", "lead_time_days", "image_url", "image_rights_confirmed" ], "properties": { "sku": { "type": "string" }, "name": { "type": "string", "description": "Canonical English product name; title is accepted for source exports" }, "title": { "type": "string", "description": "Source listing title alias" }, "material": { "type": "string" }, "材质": { "type": "string" }, "size": { "type": "string" }, "spec": { "type": "string", "description": "Source specification alias" }, "规格": { "type": "string" }, "gtin": { "type": "string" }, "moq": { "type": "integer", "minimum": 100, "description": "Minimum order quantity in purchasable units" }, "起订量": { "type": "string" }, "price_amount": { "type": "number", "minimum": 0 }, "price": { "type": [ "number", "string" ], "description": "Source CNY price alias" }, "price_currency": { "type": "string", "default": "CNY" }, "inventory": { "type": [ "integer", "null" ], "minimum": 0, "description": "Optional when inventory_status is unknown" }, "inventory_status": { "type": "string", "enum": [ "confirmed", "unknown" ], "default": "confirmed" }, "库存": { "type": "string" }, "lead_time_days": { "type": "integer", "minimum": 0 }, "交期": { "type": "string" }, "qualification_status": { "type": "string" }, "source_ref": { "type": "string" }, "image_url": { "type": "string", "description": "Public product image URL; multiple URLs may be separated by |", "pattern": "^https://" }, "imageUrl": { "type": "string" }, "images": { "type": "string" }, "category": { "type": "string" }, "variant": { "type": "string" }, "color": { "type": "string" }, "dimensions": { "type": "string" }, "unit_of_measure": { "type": "string" }, "price_unit": { "type": "string" }, "price_breaks": { "type": "array", "items": { "type": "object" } }, "shipping_origin": { "type": "string" }, "qualification_evidence": { "type": "string" }, "image_rights_confirmed": { "type": "boolean", "const": true }, "last_confirmed_at": { "type": "string", "format": "date-time" }, "packaging": { "type": "string" }, "customization": { "type": "string" }, "mixed_batch": { "type": "string" }, "fulfillment_notes": { "type": "string" } } }, "QuoteRequest": { "type": "object", "required": [ "items", "destination" ], "properties": { "environment": { "type": "string", "enum": [ "production" ], "default": "production", "description": "Only approved merchant listings with supplier-confirmed commercial fields are eligible." }, "items": { "type": "array", "items": { "type": "object", "required": [ "sku", "quantity" ], "properties": { "sku": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } } } }, "destination": { "type": "object", "required": [ "country", "postalCode" ], "properties": { "country": { "type": "string" }, "postalCode": { "type": "string" } } } } }, "QuoteResponse": { "type": "object", "properties": { "environment": { "type": "string", "enum": [ "production" ], "default": "production", "description": "Must match the eligible merchant quote. Live order creation remains disabled until settlement and fulfillment are ready." }, "quoteId": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "options": { "type": "array", "items": { "type": "object", "properties": { "supplierId": { "type": "string" }, "subtotal": { "type": "number" }, "shipping": { "type": "number" }, "total": { "type": "number" }, "leadTimeDays": { "type": "integer" } } } } } }, "CreateOrderRequest": { "type": "object", "required": [ "quoteId", "buyer", "shippingAddress" ], "properties": { "quoteId": { "type": "string" }, "buyer": { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "shippingAddress": { "type": "object" }, "agent": { "type": "object", "description": "Agent identity retained for supplier communication", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "callbackUrl": { "type": "string", "format": "uri" } } }, "payment": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "usdc_escrow", "fiat_manual" ] }, "chain": { "type": "string" } } } } }, "Order": { "type": "object", "required": [ "id", "status", "events", "payment" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "confirmed", "shipped", "tracking_updated", "eta_updated", "delivered", "accepted", "released", "disputed", "cancelled" ] }, "tracking": { "type": [ "object", "null" ] }, "supplier": { "type": "object", "properties": { "supplierId": { "type": [ "string", "null" ] }, "supplierName": { "type": [ "string", "null" ] }, "supplierSlug": { "type": [ "string", "null" ] } } }, "supplierIds": { "type": "array", "items": { "type": "string" } }, "agent": { "type": [ "object", "null" ] }, "items": { "type": "array", "items": { "type": "object" } }, "testMode": { "type": "boolean" }, "eta": { "type": [ "string", "null" ], "format": "date-time" }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" } } } }, "payment": { "type": "object", "properties": { "status": { "type": "string" }, "gross": { "type": "number" }, "platformFee": { "type": "number" }, "sellerNet": { "type": "number" }, "currency": { "type": "string" } } } } }, "Error": { "type": "object", "required": [ "status", "data", "error" ], "properties": { "status": { "type": "string", "const": "error" }, "data": { "type": "null" }, "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } } } }, "InquiryRequest": { "type": "object", "required": [ "items", "destination", "buyer" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "required": [ "sku", "quantity" ], "properties": { "sku": { "type": "string", "maxLength": 120 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000000000 }, "note": { "type": "string", "maxLength": 300 } } } }, "destination": { "type": "object", "required": [ "country" ], "properties": { "country": { "type": "string", "maxLength": 80 }, "city": { "type": "string", "maxLength": 120 }, "region": { "type": "string", "maxLength": 120 }, "postalCode": { "type": "string", "maxLength": 40 } } }, "buyer": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "company": { "type": "string", "maxLength": 200 }, "name": { "type": "string", "maxLength": 120 } } }, "agent": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 180 }, "name": { "type": "string", "maxLength": 180 }, "version": { "type": "string", "maxLength": 80 } } }, "message": { "type": "string", "maxLength": 2000 }, "idempotencyKey": { "type": "string", "maxLength": 180 } } }, "InquiryEnvelope": { "type": "object", "required": [ "status", "data", "error" ], "properties": { "status": { "type": "string", "const": "ok" }, "data": { "type": "object", "required": [ "inquiryId", "status", "items", "notifications" ], "properties": { "inquiryId": { "type": "string", "pattern": "^inq_" }, "status": { "type": "string", "const": "submitted" }, "items": { "type": "array", "items": { "type": "object" } }, "destination": { "type": "object" }, "buyer": { "type": "object" }, "agent": { "type": [ "object", "null" ] }, "notifications": { "type": "array", "items": { "type": "object" } }, "notificationStatus": { "type": "string", "enum": [ "delivered", "partial", "failed" ] }, "nextStep": { "type": "string" } } }, "error": { "type": "null" } } } } } }