{
    "openapi": "3.0.3",
    "info": {
        "title": "hstock Partner API",
        "version": "v1",
        "description": "Programmatic access to browse products, place bulk orders, check your wallet, keep seller stock in sync, and receive webhook notifications.",
        "contact": {
            "url": "https://hstockshop.com/support.php"
        }
    },
    "servers": [
        {
            "url": "https://hstockshop.com/api/v1"
        }
    ],
    "security": [
        {
            "ApiKeyAuth": [],
            "TimestampAuth": [],
            "NonceAuth": [],
            "SignatureAuth": []
        }
    ],
    "components": {
        "securitySchemes": {
            "ApiKeyAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "X-API-Key",
                "description": "Public key identifier."
            },
            "TimestampAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Timestamp",
                "description": "Unix timestamp in seconds, within 5 minutes of server time."
            },
            "NonceAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Nonce",
                "description": "Unique random string, never reused for this key."
            },
            "SignatureAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Signature",
                "description": "Lowercase hex HMAC-SHA256 of the canonical request. See /api-docs.php for the exact construction."
            }
        },
        "schemas": {
            "Product": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "string"
                    },
                    "slug": {
                        "type": "string"
                    },
                    "price": {
                        "type": "number",
                        "format": "float"
                    },
                    "currency": {
                        "type": "string",
                        "example": "USD"
                    },
                    "delivery_type": {
                        "type": "string",
                        "enum": [
                            "auto",
                            "manual"
                        ]
                    },
                    "stock_available": {
                        "type": "integer",
                        "description": "-1 means unlimited"
                    },
                    "product_url": {
                        "type": "string",
                        "format": "uri"
                    }
                }
            },
            "Order": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "order_number": {
                        "type": "string"
                    },
                    "external_order_id": {
                        "type": "string",
                        "nullable": true
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "processing",
                            "delivered",
                            "completed",
                            "disputed",
                            "refunded"
                        ]
                    },
                    "quantity": {
                        "type": "integer"
                    },
                    "total_amount": {
                        "type": "number",
                        "format": "float"
                    },
                    "currency": {
                        "type": "string",
                        "example": "USD"
                    },
                    "delivery_type": {
                        "type": "string"
                    }
                }
            },
            "Error": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean",
                        "example": false
                    },
                    "error": {
                        "type": "object",
                        "properties": {
                            "code": {
                                "type": "string"
                            },
                            "message": {
                                "type": "string"
                            },
                            "status": {
                                "type": "integer"
                            }
                        }
                    }
                }
            }
        }
    },
    "paths": {
        "/": {
            "get": {
                "summary": "API metadata",
                "security": [],
                "responses": {
                    "200": {
                        "description": "API name, version, and supported webhook events."
                    }
                }
            }
        },
        "/catalog.php": {
            "get": {
                "summary": "List active products",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 20,
                            "maximum": 50
                        }
                    },
                    {
                        "name": "category_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "product_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Return a single product instead of a list."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated product list.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "items": {
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#/components/schemas/Product"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/products.php": {
            "get": {
                "summary": "Full product detail",
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Full product detail.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Product"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Product unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/balance.php": {
            "get": {
                "summary": "Wallet balance",
                "responses": {
                    "200": {
                        "description": "Current balance and pending balance."
                    }
                }
            }
        },
        "/orders.php": {
            "get": {
                "summary": "List or look up orders",
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "external_order_id",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 20,
                            "maximum": 50
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Order or order list.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Order"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Order not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "summary": "Place an order (buy)",
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "product_id"
                                ],
                                "properties": {
                                    "product_id": {
                                        "type": "integer"
                                    },
                                    "quantity": {
                                        "type": "integer",
                                        "default": 1,
                                        "maximum": 100
                                    },
                                    "external_order_id": {
                                        "type": "string",
                                        "maxLength": 100
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Order created.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Order"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "Insufficient balance.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Insufficient stock, or idempotency conflict.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/stock.php": {
            "put": {
                "summary": "Update your product's stock (sellers only)",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "product_id"
                                ],
                                "properties": {
                                    "product_id": {
                                        "type": "integer"
                                    },
                                    "stock_quantity": {
                                        "type": "integer",
                                        "description": "-1 for unlimited"
                                    },
                                    "add_delivery_data": {
                                        "type": "string",
                                        "description": "Newline-separated accounts to append (auto-delivery products)."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated product."
                    }
                }
            }
        },
        "/webhooks.php": {
            "get": {
                "summary": "View your webhook configuration",
                "responses": {
                    "200": {
                        "description": "Current webhook config, if any."
                    }
                }
            },
            "post": {
                "summary": "Create or replace your webhook configuration",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "url",
                                    "events"
                                ],
                                "properties": {
                                    "url": {
                                        "type": "string",
                                        "format": "uri",
                                        "description": "Must be a public https:// URL."
                                    },
                                    "events": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Webhook secret shown once here - store it immediately."
                    }
                }
            },
            "delete": {
                "summary": "Remove your webhook configuration",
                "responses": {
                    "200": {
                        "description": "Removed."
                    }
                }
            }
        }
    }
}