{ "openapi": "3.0.3", "info": { "title": "JSONMart Agent Commerce API", "version": "3.0.0", "description": "The first commerce API designed for AI purchasing agents. All endpoints return structured JSON — no images, no marketing copy, just data your agent can compute.\n\n## How to Call\nAll API calls use **POST** to the base URL with an `action` parameter:\n```\nPOST https://psiysvvcusfyfsfozywn.supabase.co/functions/v1/jsonmart-api\nContent-Type: application/json\n\n{ \"action\": \"search_products\", ...params }\n```\n\n## Authentication\nProtected actions (`create_order`, `get_notifications`, etc.) require the `x-api-key` header with your agent API key (`agk_...`).\n\n## Payment Methods\n- **wallet**: Instant deduction from agent wallet balance (for API agents)\n- **payapp**: Returns a PG payment URL (for Computer Use agents to open in browser)", "contact": { "name": "JSONMart Support", "email": "support@jsonmart.xyz", "url": "https://jsonmart.xyz" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://psiysvvcusfyfsfozywn.supabase.co/functions/v1/jsonmart-api", "description": "REST API (POST + action)" }, { "url": "https://psiysvvcusfyfsfozywn.supabase.co/functions/v1/mcp-unified", "description": "MCP Server (JSON-RPC 2.0, MCP/2024-11-05)" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Products", "description": "Product search, detail, and comparison" }, { "name": "Orders", "description": "Order creation and tracking (wallet/payapp payment)" }, { "name": "Promotions", "description": "Active promotions and discounts" }, { "name": "Notifications", "description": "Agent notification management" } ], "paths": { "/#search_products": { "post": { "summary": "Search products", "operationId": "searchProducts", "tags": ["Products"], "security": [], "description": "Search the product catalog by category, keyword, price, stock status, and more. Results include structured shipping and return info.\n\n```bash\ncurl -X POST 'https://psiysvvcusfyfsfozywn.supabase.co/functions/v1/jsonmart-api' \\\n -H 'Content-Type: application/json' \\\n -d '{\"action\": \"search_products\", \"category\": \"FOOD\", \"limit\": 5}'\n```", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["action"], "properties": { "action": { "type": "string", "enum": ["search_products"], "example": "search_products" }, "query": { "type": "string", "description": "Keyword search on product title (ILIKE)", "example": "tissue" }, "category": { "type": "string", "enum": ["CONSUMABLES", "MRO", "FASHION", "FOOD", "ELECTRONICS", "HOME", "OFFICE", "BEAUTY", "SPORTS", "GENERAL"], "description": "Category filter" }, "sub_category": { "type": "string", "description": "Sub-category filter" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tag array (overlaps matching)" }, "max_price": { "type": "integer", "description": "Maximum price filter (KRW)" }, "in_stock_only": { "type": "boolean", "description": "Only return in-stock products" }, "min_trust": { "type": "number", "description": "Minimum seller trust score filter" }, "seller_id": { "type": "string", "description": "Filter by specific seller" }, "limit": { "type": "integer", "default": 10, "maximum": 50, "description": "Max results to return" } } } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } }, "total": { "type": "integer", "example": 5 } } } } } } } } }, "/#get_product": { "post": { "summary": "Get product detail", "operationId": "getProduct", "tags": ["Products"], "security": [], "description": "Retrieve full product details by SKU. Includes shipping fee structure, return policy, AI-extracted data, and mandatory disclosure info.\n\n```bash\ncurl -X POST 'https://psiysvvcusfyfsfozywn.supabase.co/functions/v1/jsonmart-api' \\\n -H 'Content-Type: application/json' \\\n -d '{\"action\": \"get_product\", \"sku\": \"DOME-12345\"}'\n```", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["action", "sku"], "properties": { "action": { "type": "string", "enum": ["get_product"] }, "sku": { "type": "string", "description": "Product SKU", "example": "DOME-12345" } } } } } }, "responses": { "200": { "description": "Full product detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDetail" } } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Product not found: DOME-12345" } } } } } } } } }, "/#compare_products": { "post": { "summary": "Compare products", "operationId": "compareProducts", "tags": ["Products"], "security": [], "description": "Compare 2-4 SKUs side-by-side on price, trust score, shipping, and returns. Includes an AI-generated recommendation.\n\n```bash\ncurl -X POST 'https://psiysvvcusfyfsfozywn.supabase.co/functions/v1/jsonmart-api' \\\n -H 'Content-Type: application/json' \\\n -d '{\"action\": \"compare_products\", \"sku_list\": [\"DOME-111\", \"DOME-222\"]}'\n```", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["action", "sku_list"], "properties": { "action": { "type": "string", "enum": ["compare_products"] }, "sku_list": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 4, "description": "SKUs to compare (2-4 items)", "example": ["DOME-111", "DOME-222"] } } } } } }, "responses": { "200": { "description": "Comparison results with recommendation", "content": { "application/json": { "schema": { "type": "object", "properties": { "comparison": { "type": "array", "items": { "$ref": "#/components/schemas/ProductComparison" } }, "recommendation": { "type": "string", "description": "Recommended SKU", "example": "DOME-111" }, "reason": { "type": "string", "example": "Highest trust score (92) + best price ₩15,900" } } } } } } } } }, "/#list_promotions": { "post": { "summary": "List active promotions", "operationId": "listPromotions", "tags": ["Promotions"], "security": [], "description": "Retrieve currently active promotions. Agents can evaluate these programmatically against their purchasing policies.\n\n```bash\ncurl -X POST 'https://psiysvvcusfyfsfozywn.supabase.co/functions/v1/jsonmart-api' \\\n -H 'Content-Type: application/json' \\\n -d '{\"action\": \"list_promotions\"}'\n```", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["action"], "properties": { "action": { "type": "string", "enum": ["list_promotions"] }, "category": { "type": "string", "description": "Filter by category" } } } } } }, "responses": { "200": { "description": "Active promotions", "content": { "application/json": { "schema": { "type": "object", "properties": { "promotions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": ["percentage", "fixed_amount", "buy_x_get_y"] }, "value": { "type": "number" }, "minQty": { "type": "integer" }, "categories": { "type": "array", "items": { "type": "string" } }, "validFrom": { "type": "string", "format": "date-time" }, "validUntil": { "type": "string", "format": "date-time" } } } } } } } } } } } }, "/#create_order": { "post": { "summary": "Create order", "operationId": "createOrder", "tags": ["Orders"], "description": "Place a purchase order. Validates MOQ, options, and stock. Payment is processed via wallet (instant) or payapp (PG URL).\n\n### Wallet Payment (API Agents)\n```bash\ncurl -X POST 'https://psiysvvcusfyfsfozywn.supabase.co/functions/v1/jsonmart-api' \\\n -H 'Content-Type: application/json' \\\n -H 'x-api-key: agk_your_key' \\\n -d '{\"action\": \"create_order\", \"sku\": \"DOME-12345\", \"quantity\": 2, \"payment_method\": \"wallet\"}'\n```\n\n### PayApp PG Payment (Computer Use Agents)\n```bash\ncurl -X POST 'https://psiysvvcusfyfsfozywn.supabase.co/functions/v1/jsonmart-api' \\\n -H 'Content-Type: application/json' \\\n -H 'x-api-key: agk_your_key' \\\n -d '{\"action\": \"create_order\", \"sku\": \"DOME-12345\", \"quantity\": 2, \"payment_method\": \"payapp\"}'\n```\n\n### Domeggook-sourced Products\nDomeggook products require recipient info (`recipient_name`, `address`, `phone`). If the agent has a default shipping address configured, it will auto-fill.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["action", "sku", "quantity"], "properties": { "action": { "type": "string", "enum": ["create_order"] }, "sku": { "type": "string", "description": "Product SKU", "example": "DOME-12345" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9999, "description": "Order quantity", "example": 2 }, "payment_method": { "type": "string", "enum": ["wallet", "payapp"], "default": "payapp", "description": "wallet = instant wallet deduction, payapp = PG payment URL" }, "options": { "type": "object", "description": "Product options (required for products with options). Format: {\"option_name\": \"option_value\"}", "example": { "Color": "Black", "Size": "L" } }, "recipient_name": { "type": "string", "description": "Recipient name (required for Domeggook products)" }, "address": { "type": "string", "description": "Shipping address (required for Domeggook products)" }, "phone": { "type": "string", "description": "Recipient phone (required for Domeggook products)" }, "postal_code": { "type": "string", "description": "Postal code" }, "address_detail": { "type": "string", "description": "Address line 2" }, "delivery_note": { "type": "string", "description": "Delivery instructions" } } } } } }, "responses": { "200": { "description": "Order created", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WalletOrderResponse" }, { "$ref": "#/components/schemas/PayAppOrderResponse" } ] } } } }, "400": { "description": "Validation failed (MOQ, options, missing fields)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "BELOW_MOQ" }, "message": { "type": "string" }, "hint": { "type": "string" } } } } } }, "401": { "description": "Authentication failed (missing or invalid x-api-key)" }, "402": { "description": "Insufficient wallet balance (wallet payment only)" } } } }, "/#check_order": { "post": { "summary": "Check order status", "operationId": "checkOrder", "tags": ["Orders"], "description": "Check order status, payment status, and tracking info by order ID.\n\n```bash\ncurl -X POST 'https://psiysvvcusfyfsfozywn.supabase.co/functions/v1/jsonmart-api' \\\n -H 'Content-Type: application/json' \\\n -d '{\"action\": \"check_order\", \"order_id\": \"ORD-20260328-A1B2C\"}'\n```", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["action", "order_id"], "properties": { "action": { "type": "string", "enum": ["check_order"] }, "order_id": { "type": "string", "description": "Order ID", "example": "ORD-20260328-A1B2C" } } } } } }, "responses": { "200": { "description": "Order details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderStatus" } } } }, "404": { "description": "Order not found" } } } }, "/#get_notifications": { "post": { "summary": "Get notifications", "operationId": "getNotifications", "tags": ["Notifications"], "description": "Retrieve agent notifications — order status changes, stock alerts, etc.\n\n```bash\ncurl -X POST 'https://psiysvvcusfyfsfozywn.supabase.co/functions/v1/jsonmart-api' \\\n -H 'Content-Type: application/json' \\\n -H 'x-api-key: agk_your_key' \\\n -d '{\"action\": \"get_notifications\", \"unread_only\": true}'\n```", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["action"], "properties": { "action": { "type": "string", "enum": ["get_notifications"] }, "unread_only": { "type": "boolean", "default": false, "description": "Only return unread notifications" }, "type": { "type": "string", "description": "Filter by notification type" }, "limit": { "type": "integer", "default": 20, "description": "Max notifications to return" } } } } } }, "responses": { "200": { "description": "Notification list" }, "401": { "description": "Authentication required" } } } }, "/#mark_notification_read": { "post": { "summary": "Mark notification as read", "operationId": "markNotificationRead", "tags": ["Notifications"], "description": "Mark a specific notification as read.\n\n```bash\ncurl -X POST 'https://psiysvvcusfyfsfozywn.supabase.co/functions/v1/jsonmart-api' \\\n -H 'Content-Type: application/json' \\\n -H 'x-api-key: agk_your_key' \\\n -d '{\"action\": \"mark_notification_read\", \"notification_id\": \"uuid-here\"}'\n```", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["action", "notification_id"], "properties": { "action": { "type": "string", "enum": ["mark_notification_read"] }, "notification_id": { "type": "string", "format": "uuid", "description": "Notification ID" } } } } } }, "responses": { "200": { "description": "Marked as read" }, "401": { "description": "Authentication required" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Agent API key (agk_...)" } }, "schemas": { "ProductSummary": { "type": "object", "description": "Product summary in search results", "properties": { "sku": { "type": "string", "example": "DOME-12345" }, "title": { "type": "string", "example": "Smart LED Lighting Package" }, "description": { "type": "string" }, "category": { "type": "string", "enum": ["CONSUMABLES", "MRO", "FASHION", "FOOD", "ELECTRONICS", "HOME", "OFFICE", "BEAUTY", "SPORTS", "GENERAL"] }, "sub_category": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "brand": { "type": "string" }, "price": { "type": "integer", "description": "Price in KRW", "example": 15900 }, "currency": { "type": "string", "example": "KRW" }, "stock_status": { "type": "string", "enum": ["in_stock", "out_of_stock", "unknown"] }, "stock_qty": { "type": "integer" }, "trust_score": { "type": "number", "description": "Seller trust score (0-100)", "example": 92 }, "eta_days": { "type": "integer", "description": "Estimated delivery days", "example": 3 }, "ship_by_days": { "type": "integer", "description": "Days to ship", "example": 1 }, "moq": { "type": "integer", "description": "Minimum order quantity", "example": 1 }, "seller_id": { "type": "string" }, "seller_name": { "type": "string" }, "source": { "type": "string", "enum": ["direct", "domeggook"], "description": "Product source" }, "has_options": { "type": "boolean", "description": "Whether product requires option selection" }, "options": { "type": "array", "description": "Available options (if has_options is true)", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Color" }, "values": { "type": "array", "items": { "type": "string" }, "example": ["Black", "White"] } } } }, "shipping_info": { "$ref": "#/components/schemas/ShippingInfo" }, "return_info": { "$ref": "#/components/schemas/ReturnInfo" } } }, "ProductDetail": { "type": "object", "description": "Full product detail (get_product response)", "properties": { "sku": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "subCategory": { "type": "string" }, "domeCategoryPath": { "type": "string", "description": "Domeggook category path" }, "tags": { "type": "array", "items": { "type": "string" } }, "brand": { "type": "string" }, "gtin": { "type": "string" }, "price": { "type": "integer", "description": "Price in KRW" }, "currency": { "type": "string" }, "stockStatus": { "type": "string" }, "stockQty": { "type": "integer" }, "etaDays": { "type": "integer" }, "shipByDays": { "type": "integer" }, "returnDays": { "type": "integer" }, "returnFee": { "type": "integer" }, "aiReadinessScore": { "type": "number", "description": "AI data quality score" }, "trustScore": { "type": "number" }, "moq": { "type": "integer", "description": "Minimum order quantity" }, "sellerId": { "type": "string" }, "sellerName": { "type": "string" }, "source": { "type": "string", "enum": ["direct", "domeggook"] }, "hasOptions": { "type": "boolean" }, "deliveryFee": { "type": "object", "description": "Detailed shipping fee structure" }, "shippingInfo": { "$ref": "#/components/schemas/ShippingInfo" }, "returnInfo": { "$ref": "#/components/schemas/ReturnInfo" }, "productDetail": { "type": "object", "description": "AI-extracted product detail data" }, "aiExtracted": { "type": "boolean" }, "imageUrl": { "type": "string" }, "detailImages": { "type": "array", "items": { "type": "string" } }, "infoDuty": { "type": "object", "description": "Mandatory disclosure info (placeholder entries filtered out)" }, "attributes": { "type": "object" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ProductComparison": { "type": "object", "description": "Product comparison item", "properties": { "sku": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "brand": { "type": "string" }, "price": { "type": "integer" }, "trust_score": { "type": "number" }, "stock": { "type": "string" }, "stock_qty": { "type": "integer" }, "ship_by_days": { "type": "integer" }, "eta_days": { "type": "integer" }, "moq": { "type": "integer" }, "return_days": { "type": "integer" }, "return_fee": { "type": "integer" }, "seller_id": { "type": "string" }, "seller_name": { "type": "string" }, "shipping_info": { "$ref": "#/components/schemas/ShippingInfo" }, "return_info": { "$ref": "#/components/schemas/ReturnInfo" } } }, "ShippingInfo": { "type": "object", "description": "Structured shipping information", "properties": { "method": { "type": "string", "description": "Shipping method", "example": "Courier" }, "fee_type": { "type": "string", "description": "Free / prepaid / collect-on-delivery" }, "base_fee": { "type": "integer", "description": "Base shipping fee (KRW)" }, "jeju_extra": { "type": "integer", "description": "Jeju island surcharge (KRW)" }, "island_extra": { "type": "integer", "description": "Remote island surcharge (KRW)" }, "merge_shipping": { "type": "string", "description": "Bundle shipping availability" }, "fast_delivery": { "type": "boolean", "description": "Express delivery available" }, "ship_by_days": { "type": "integer", "description": "Days to ship" }, "eta_days": { "type": "integer", "description": "Estimated delivery days" } } }, "ReturnInfo": { "type": "object", "description": "Return and exchange policy", "properties": { "return_fee": { "type": "integer", "description": "Return shipping fee (KRW)", "example": 3000 }, "return_days": { "type": "integer", "description": "Return window (days)", "example": 7 }, "policy": { "type": "string", "example": "Returns accepted before purchase confirmation. Buyer pays return shipping for change-of-mind returns." } } }, "WalletOrderResponse": { "type": "object", "description": "Wallet payment order response (instantly confirmed)", "properties": { "orderId": { "type": "string", "example": "ORD-20260328-A1B2C" }, "status": { "type": "string", "example": "CONFIRMED" }, "paymentMethod": { "type": "string", "example": "wallet" }, "sku": { "type": "string" }, "productTitle": { "type": "string" }, "quantity": { "type": "integer" }, "unitPrice": { "type": "integer" }, "totalPrice": { "type": "integer" }, "selectedOptions": { "type": "object", "nullable": true }, "walletBalance": { "type": "integer", "description": "Remaining wallet balance after deduction" }, "procurement": { "type": "object", "nullable": true, "description": "Domeggook auto-procurement result (if applicable)" }, "message": { "type": "string" } } }, "PayAppOrderResponse": { "type": "object", "description": "PayApp PG payment order response (payment URL returned)", "properties": { "orderId": { "type": "string", "example": "ORD-20260328-A1B2C" }, "status": { "type": "string", "example": "ORDER_CREATED" }, "paymentMethod": { "type": "string", "example": "payapp" }, "sku": { "type": "string" }, "productTitle": { "type": "string" }, "quantity": { "type": "integer" }, "unitPrice": { "type": "integer" }, "totalPrice": { "type": "integer" }, "payurl": { "type": "string", "description": "Payment page URL — Computer Use agents should open this URL to complete payment", "example": "https://www.payapp.kr/oapi/pay/..." }, "mulNo": { "type": "string", "description": "PayApp transaction number" }, "paymentDeadline": { "type": "string", "format": "date-time", "description": "Payment deadline (24 hours)" }, "message": { "type": "string" }, "instructions": { "type": "object", "properties": { "computerUse": { "type": "string", "example": "open_url(payurl) → complete payment" }, "humanOperator": { "type": "string", "example": "Open payurl in browser to complete payment" } } } } }, "OrderStatus": { "type": "object", "description": "Order status response", "properties": { "orderId": { "type": "string" }, "status": { "type": "string", "enum": ["ORDER_CREATED", "CONFIRMED", "PROCESSING", "SHIPPED", "DELIVERED", "CANCELLED"], "description": "Order lifecycle status" }, "paymentStatus": { "type": "string", "enum": ["PENDING", "PAYMENT_REQUESTED", "CAPTURED", "REFUNDED"], "description": "Payment status" }, "paymentMethod": { "type": "string", "enum": ["WALLET", "PAYAPP"] }, "sku": { "type": "string" }, "productTitle": { "type": "string" }, "quantity": { "type": "integer" }, "totalPrice": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "paymentDeadline": { "type": "string", "format": "date-time", "nullable": true }, "trackingNumber": { "type": "string", "nullable": true, "description": "Shipping tracking number" }, "payurl": { "type": "string", "nullable": true, "description": "Payment URL (if unpaid)" }, "mulNo": { "type": "string", "nullable": true }, "payType": { "type": "string", "nullable": true, "description": "Payment type used" }, "payDate": { "type": "string", "nullable": true, "description": "Payment completion date" } } } } } }