{
  "openapi": "3.1.0",
  "info": {
    "title": "kalcerPOS External API",
    "version": "1.0.0",
    "summary": "Narrow API for one kalcerPOS store: sales reports, products and stock, unpaid open bills.",
    "description": "Paid add-on (Rp 50.000 per month per store), switched on by kalcerPOS admin. The store admin generates the key in Admin > Settings > External API access; the key (\"<tenantId>.<secret>\") selects the store. Conventions: dates are YYYY-MM-DD in the store's local timezone; money is integer rupiah; stock >= 999 means unlimited. Not available on purpose: payments, deletes, single-order reads, customer data. POST routes are not idempotent. Always pass explicit from/to on report routes: missing or malformed values silently become today's date in UTC. Human guide: https://docs.kalcerpos.com/docs/features/external-api. Markdown: https://docs.kalcerpos.com/docs/external-api.md"
  },
  "servers": [
    {
      "url": "https://{slug}.kalcerpos.com/api/external",
      "description": "The store's own host.",
      "variables": {
        "slug": {
          "default": "namatoko",
          "description": "Store subdomain"
        }
      }
    }
  ],
  "security": [
    {
      "bearerKey": []
    }
  ],
  "paths": {
    "/reports/summary": {
      "get": {
        "operationId": "getSalesSummary",
        "summary": "Sales summary for a date range (paid orders only)",
        "description": "grossSales = sum of (price + modifier price) x qty before discounts; refunds = refunded amounts on orders in the range (by order date); netSales = sum of order totals minus refunds; grossProfit = netSales - cogs.",
        "parameters": [
          {
            "$ref": "#/components/parameters/from"
          },
          {
            "$ref": "#/components/parameters/to"
          }
        ],
        "responses": {
          "200": {
            "description": "Summary",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Summary"
                },
                "example": {
                  "range": {
                    "from": "2026-11-01",
                    "to": "2026-11-07"
                  },
                  "orders": 182,
                  "grossSales": 5460000,
                  "refunds": 45000,
                  "netSales": 5398000,
                  "cogs": 1910000,
                  "grossProfit": 3488000
                }
              }
            }
          },
          "400": {
            "description": "Bad date: \"from must be a date as YYYY-MM-DD\" or \"from must not be after to\"",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/reports/by-item": {
      "get": {
        "operationId": "getSalesByItem",
        "summary": "Qty and gross revenue per product name (paid orders only), sorted by qty descending",
        "parameters": [
          {
            "$ref": "#/components/parameters/from"
          },
          {
            "$ref": "#/components/parameters/to"
          }
        ],
        "responses": {
          "200": {
            "description": "Per item",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "range",
                    "items"
                  ],
                  "properties": {
                    "range": {
                      "$ref": "#/components/schemas/Range"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "name",
                          "qty",
                          "revenue"
                        ],
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "qty": {
                            "type": "number"
                          },
                          "revenue": {
                            "type": "number",
                            "description": "Gross, before discounts and refunds"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "range": {
                    "from": "2026-11-01",
                    "to": "2026-11-07"
                  },
                  "items": [
                    {
                      "name": "Es Kopi Susu",
                      "qty": 64,
                      "revenue": 1408000
                    },
                    {
                      "name": "Roti Bakar",
                      "qty": 31,
                      "revenue": 558000
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad date: \"from must be a date as YYYY-MM-DD\" or \"from must not be after to\"",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/reports/by-payment": {
      "get": {
        "operationId": "getSalesByPayment",
        "summary": "Totals per payment method (paid orders only, not net of refunds)",
        "description": "Keys are lower-case method ids: cash, qris, card (EDC), store-defined m_<id>, and other for orders without a method. Methods with no sales are omitted.",
        "parameters": [
          {
            "$ref": "#/components/parameters/from"
          },
          {
            "$ref": "#/components/parameters/to"
          }
        ],
        "responses": {
          "200": {
            "description": "Per method",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "range",
                    "byMethod"
                  ],
                  "properties": {
                    "range": {
                      "$ref": "#/components/schemas/Range"
                    },
                    "byMethod": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "number"
                      }
                    }
                  }
                },
                "example": {
                  "range": {
                    "from": "2026-11-01",
                    "to": "2026-11-07"
                  },
                  "byMethod": {
                    "cash": 2150000,
                    "qris": 3020000,
                    "card": 228000
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad date: \"from must be a date as YYYY-MM-DD\" or \"from must not be after to\"",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/reports/by-hour": {
      "get": {
        "operationId": "getSalesByHour",
        "summary": "Orders and revenue per hour of day (0-23, store timezone), summed over every day in the range",
        "description": "byHour always has 24 entries. For a single day pass the same from and to. revenue = order totals, not net of refunds.",
        "parameters": [
          {
            "$ref": "#/components/parameters/from"
          },
          {
            "$ref": "#/components/parameters/to"
          }
        ],
        "responses": {
          "200": {
            "description": "Per hour",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "range",
                    "timezone",
                    "byHour"
                  ],
                  "properties": {
                    "range": {
                      "$ref": "#/components/schemas/Range"
                    },
                    "timezone": {
                      "type": "string",
                      "examples": [
                        "Asia/Jakarta"
                      ]
                    },
                    "byHour": {
                      "type": "array",
                      "minItems": 24,
                      "maxItems": 24,
                      "items": {
                        "type": "object",
                        "required": [
                          "hour",
                          "orders",
                          "revenue"
                        ],
                        "properties": {
                          "hour": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 23
                          },
                          "orders": {
                            "type": "integer"
                          },
                          "revenue": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "range": {
                    "from": "2026-11-01",
                    "to": "2026-11-07"
                  },
                  "timezone": "Asia/Jakarta",
                  "byHour": [
                    {
                      "hour": 0,
                      "orders": 0,
                      "revenue": 0
                    },
                    {
                      "hour": 12,
                      "orders": 31,
                      "revenue": 948000
                    },
                    {
                      "hour": 23,
                      "orders": 0,
                      "revenue": 0
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad date: \"from must be a date as YYYY-MM-DD\" or \"from must not be after to\"",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/products": {
      "get": {
        "operationId": "listProducts",
        "summary": "All products (no paging), including ones hidden from the cashier",
        "description": "stock >= 999 = unlimited; recipe/combo products always report 999. The active flag is not returned. Use id for PATCH /products/{id} and POST /orders.",
        "responses": {
          "200": {
            "description": "Products",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "products"
                  ],
                  "properties": {
                    "products": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ProductListItem"
                      }
                    }
                  }
                },
                "example": {
                  "products": [
                    {
                      "id": "7fQ2kLm9XbR1sT4uVw8y",
                      "sku": "KP-01",
                      "name": "Es Kopi Susu",
                      "category": "Kopi",
                      "price": 22000,
                      "stock": 40,
                      "stockThreshold": 5
                    },
                    {
                      "id": "a1B2c3D4e5F6g7H8i9J0",
                      "sku": "",
                      "name": "Paket Hemat",
                      "category": "Paket",
                      "price": 30000,
                      "stock": 999,
                      "stockThreshold": 0
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "post": {
        "operationId": "createProduct",
        "summary": "Create a product (not idempotent, no duplicate-name check)",
        "description": "Invalid or negative optional numbers fall back to their default instead of being rejected. Unknown fields are ignored. Modifiers, bulk discounts, recipes and photos cannot be set here.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProductCreate"
              },
              "example": {
                "name": "Es Kopi Susu",
                "price": 22000,
                "category": "Kopi",
                "stock": 50
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "id",
                    "product"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "id": {
                      "type": "string"
                    },
                    "product": {
                      "$ref": "#/components/schemas/Product"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "id": "Zx81LmQp0aB2cD3eF4gH",
                  "product": {
                    "id": "Zx81LmQp0aB2cD3eF4gH",
                    "name": "Es Kopi Susu",
                    "sku": "",
                    "category": "Kopi",
                    "station": "bar",
                    "price": 22000,
                    "cogs": 0,
                    "stock": 50,
                    "stockThreshold": 0,
                    "bulkQty": 0,
                    "bulkType": "percent",
                    "bulkValue": 0,
                    "swatch": "#a98558",
                    "desc": "",
                    "active": true,
                    "modifiers": [],
                    "recipe": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/products/{id}": {
      "patch": {
        "operationId": "updateProduct",
        "summary": "Update stock, price and/or stockThreshold of one product",
        "description": "stock OVERWRITES the value (read, add, then send the total). Not logged as a stock movement, no low-stock notification. Other fields and null values are ignored; at least one allowed field is required. A stock change is logged in stock movements (reason adjustment, note \"External API\"); the reply then includes stockBefore.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Product id from GET /products"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "minProperties": 1,
                "properties": {
                  "stock": {
                    "type": "number",
                    "minimum": 0
                  },
                  "price": {
                    "type": "number",
                    "minimum": 0
                  },
                  "stockThreshold": {
                    "type": "number",
                    "minimum": 0
                  }
                }
              },
              "example": {
                "stock": 40,
                "price": 23000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "id",
                    "updated"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "id": {
                      "type": "string"
                    },
                    "updated": {
                      "type": "object",
                      "description": "The fields actually saved",
                      "additionalProperties": {
                        "type": "number"
                      }
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "id": "7fQ2kLm9XbR1sT4uVw8y",
                  "updated": {
                    "stock": 40,
                    "price": 23000
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/orders": {
      "post": {
        "operationId": "createOpenBill",
        "summary": "Create an unpaid open bill and send it to the kitchen/bar (not idempotent)",
        "description": "Prices come from the current catalog. Stock is checked for the whole order (409 and nothing written if short), then decremented (recipe products consume ingredients, combos consume component products) and logged as stock movements. The order is dated today in the store timezone, stamped cashierEmail \"external-api\", appears in the cashier's Bills list and on the kitchen display, and kitchen/bar/waitress tickets are queued for printing. No modifiers, bulk discounts, vouchers or payment; a cashier takes payment in the POS. Inactive products can still be ordered. The order counts in reports only after payment.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderCreate"
              },
              "example": {
                "table": "5",
                "customer": "Rina",
                "items": [
                  {
                    "productId": "7fQ2kLm9XbR1sT4uVw8y",
                    "qty": 2,
                    "notes": "less sugar"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Open bill created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "id",
                    "shortId",
                    "total",
                    "items"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "id": {
                      "type": "string",
                      "description": "Order id"
                    },
                    "shortId": {
                      "type": "string",
                      "description": "5-character code printed on tickets and shown in the POS"
                    },
                    "total": {
                      "type": "number",
                      "description": "Bill amount in rupiah"
                    },
                    "items": {
                      "type": "integer",
                      "description": "Number of order lines"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "id": "Hk3PqR8sT1uV2wX4yZ5a",
                  "shortId": "K7MPX",
                  "total": 44000,
                  "items": 1
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Not enough stock (error insufficient stock / insufficient ingredient stock, with available and needed), or a product is inactive (error \"product not active: <name>\", code \"inactive\", productId). Nothing is written.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "available",
                    "needed"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "insufficient stock: <name> | insufficient ingredient stock: <name> | product not active: <name>"
                    },
                    "available": {
                      "type": "number"
                    },
                    "needed": {
                      "type": "number"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "inactive"
                      ]
                    },
                    "productId": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "error": "insufficient stock: Es Kopi Susu",
                  "available": 1,
                  "needed": 2
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Store API key \"<tenantId>.<64 hex chars>\" from Admin > Settings > External API access. Regenerating invalidates the old key immediately."
      }
    },
    "parameters": {
      "from": {
        "name": "from",
        "in": "query",
        "required": false,
        "description": "YYYY-MM-DD (store-local date, inclusive). Missing = today in the store timezone; malformed, impossible or from > to = 400.",
        "schema": {
          "type": "string",
          "format": "date",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        }
      },
      "to": {
        "name": "to",
        "in": "query",
        "required": false,
        "description": "YYYY-MM-DD (store-local date, inclusive). Missing = today in the store timezone; malformed, impossible or from > to = 400.",
        "schema": {
          "type": "string",
          "format": "date",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        }
      }
    },
    "schemas": {
      "Range": {
        "type": "object",
        "required": [
          "from",
          "to"
        ],
        "properties": {
          "from": {
            "type": "string",
            "format": "date"
          },
          "to": {
            "type": "string",
            "format": "date"
          }
        }
      },
      "Summary": {
        "type": "object",
        "required": [
          "range",
          "orders",
          "grossSales",
          "refunds",
          "netSales",
          "cogs",
          "grossProfit"
        ],
        "properties": {
          "range": {
            "$ref": "#/components/schemas/Range"
          },
          "orders": {
            "type": "integer",
            "description": "Paid orders"
          },
          "grossSales": {
            "type": "number"
          },
          "refunds": {
            "type": "number"
          },
          "netSales": {
            "type": "number"
          },
          "cogs": {
            "type": "number"
          },
          "grossProfit": {
            "type": "number"
          }
        }
      },
      "ProductListItem": {
        "type": "object",
        "required": [
          "id",
          "sku",
          "name",
          "category",
          "price",
          "stock",
          "stockThreshold"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "sku": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "price": {
            "type": "number"
          },
          "stock": {
            "type": "number",
            "description": ">= 999 means unlimited"
          },
          "stockThreshold": {
            "type": "number"
          }
        }
      },
      "ProductCreate": {
        "type": "object",
        "required": [
          "name",
          "price"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "price": {
            "type": "number",
            "minimum": 0
          },
          "sku": {
            "type": "string",
            "default": ""
          },
          "category": {
            "type": "string",
            "default": "Uncategorised"
          },
          "station": {
            "type": "string",
            "enum": [
              "kitchen",
              "bar"
            ],
            "default": "bar",
            "description": "Anything other than \"kitchen\" becomes \"bar\""
          },
          "cogs": {
            "type": "number",
            "minimum": 0,
            "default": 0
          },
          "stock": {
            "type": "number",
            "minimum": 0,
            "default": 999
          },
          "stockThreshold": {
            "type": "number",
            "minimum": 0,
            "default": 0
          },
          "desc": {
            "type": "string",
            "default": ""
          },
          "active": {
            "type": "boolean",
            "default": true
          }
        }
      },
      "Product": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "sku": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "station": {
            "type": "string",
            "enum": [
              "kitchen",
              "bar"
            ]
          },
          "price": {
            "type": "number"
          },
          "cogs": {
            "type": "number"
          },
          "stock": {
            "type": "number"
          },
          "stockThreshold": {
            "type": "number"
          },
          "bulkQty": {
            "type": "number"
          },
          "bulkType": {
            "type": "string"
          },
          "bulkValue": {
            "type": "number"
          },
          "swatch": {
            "type": "string"
          },
          "desc": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "modifiers": {
            "type": "array",
            "items": {}
          },
          "recipe": {
            "type": "array",
            "items": {}
          }
        }
      },
      "OrderCreate": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "table": {
            "type": [
              "string",
              "integer"
            ],
            "default": "T",
            "maxLength": 40,
            "description": "Table name or number; \"5\" and 5 are both accepted"
          },
          "customer": {
            "type": "string",
            "default": "Walk-in"
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": [
                "productId",
                "qty"
              ],
              "properties": {
                "productId": {
                  "type": "string"
                },
                "qty": {
                  "type": "number",
                  "exclusiveMinimum": 0
                },
                "notes": {
                  "type": "string",
                  "maxLength": 200,
                  "description": "Kitchen note, longer text is cut"
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "detail": {
            "type": "string",
            "description": "Only on 500"
          },
          "code": {
            "type": "string",
            "description": "\"trial_locked\" when the store's free trial has ended"
          },
          "ok": {
            "const": false
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Validation failed. Errors: \"name is required\", \"price is required and must be a non-negative number\", \"invalid stock\", \"invalid price\", \"invalid stockThreshold\", \"no valid fields to update\", \"items must be a non-empty array\", \"each item needs a productId and a positive qty\". A body that is not valid JSON gets a 400 HTML page instead.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "name is required"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, wrong or regenerated key, or the store is suspended.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "unauthorized"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Add-on not active, or (POST/PATCH only) the store's free trial has ended (code trial_locked; GET routes keep working).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "addonOff": {
                "value": {
                  "error": "External API add-on is not active for this store"
                }
              },
              "trialLocked": {
                "value": {
                  "ok": false,
                  "error": "Masa coba toko ini sudah habis. Data kamu aman, tapi toko hanya bisa dilihat sampai paket dibayar.",
                  "code": "trial_locked"
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Unknown product id, or a package/recipe refers to a deleted product or ingredient. Errors: \"product not found\", \"product not found: <id>\", \"combo component product not found: <id>\", \"ingredient not found: <id>\".",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "product not found"
            }
          }
        }
      },
      "ServerError": {
        "description": "Internal error (500, \"internal error\" + detail) or server not ready (503, \"external API not configured\"). Retry later.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "internal error",
              "detail": "..."
            }
          }
        }
      }
    }
  }
}
