{
    "openapi": "3.0.3",
    "info": {
        "title": "SC Order Management System API",
        "version": "1.0.0",
        "description": "API for managing products, inventory, warehouses, orders, and reservations."
    },
    "paths": {
        "/products": {
            "get": {
                "summary": "Get all products",
                "description": "Returns a list of all products available in the system.",
                "operationId": "getProducts",
                "tags": [
                    "Products"
                ],
                "responses": {
                    "200": {
                        "description": "A list of products.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/Product"
                                    }
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/orders": {
            "post": {
                "summary": "Place a new order",
                "description": "Creates a new order for specified products. For 'walk-in' orders, inventory is allocated from available inventory (inventory - reservations).",
                "operationId": "createOrder",
                "tags": [
                    "Orders"
                ],
                "requestBody": {
                    "description": "Order creation payload",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateOrderRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Order successfully created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CreateOrderResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request - Invalid input, insufficient inventory, or shipping cost too high.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/reservations": {
            "post": {
                "summary": "Check reservation feasibility",
                "description": "Checks if a reservation for specified products is feasible based on current inventory, existing reservations, and shipping cost limits. Does not create a reservation.",
                "operationId": "checkReservationFeasibility",
                "tags": [
                    "Reservations"
                ],
                "parameters": [
                    {
                        "name": "reserve",
                        "in": "query",
                        "required": true,
                        "description": "Must be 'false' to check feasibility without creating a reservation.",
                        "schema": {
                            "type": "string",
                            "enum": ["false"]
                        }
                    }
                ],
                "requestBody": {
                    "description": "Reservation check payload (same as creating an order)",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateOrderRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Reservation feasibility check successful. Inspect 'isValid' field in the response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CheckReservationResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request - Invalid input, or reservation is not feasible (e.g. insufficient inventory, shipping cost too high).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "501": {
                        "description": "Not Implemented - If 'reserve' query param is not 'false'.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Product": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid",
                        "description": "UUID of the product."
                    },
                    "name": {
                        "type": "string",
                        "description": "Name of the product."
                    },
                    "unitPriceCents": {
                        "type": "integer",
                        "description": "Unit price of the product in cents."
                    },
                    "weightGrams": {
                        "type": "integer",
                        "description": "Weight of the product in grams."
                    }
                },
                "required": [
                    "id",
                    "name",
                    "unitPriceCents",
                    "weightGrams"
                ]
            },
            "OrderShippingAddress": {
                "type": "object",
                "properties": {
                    "latitude": {
                        "type": "string",
                        "description": "Latitude of the shipping address.",
                        "example": "40.7128"
                    },
                    "longitude": {
                        "type": "string",
                        "description": "Longitude of the shipping address.",
                        "example": "-74.0060"
                    }
                },
                "required": [
                    "latitude",
                    "longitude"
                ]
            },
            "OrderRequestedProduct": {
                "type": "object",
                "properties": {
                    "productId": {
                        "type": "string",
                        "format": "uuid",
                        "description": "UUID of the product.",
                        "example": "721c711e-94a0-456b-bb53-bdf96b3c062e"
                    },
                    "quantity": {
                        "type": "integer",
                        "minimum": 1,
                        "description": "Quantity of the product requested.",
                        "example": 10
                    }
                },
                "required": [
                    "productId",
                    "quantity"
                ]
            },
            "CreateOrderRequest": {
                "type": "object",
                "properties": {
                    "shippingAddress": {
                        "$ref": "#/components/schemas/OrderShippingAddress"
                    },
                    "requestedProducts": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/OrderRequestedProduct"
                        },
                        "minItems": 1,
                        "description": "List of products to order."
                    }
                },
                "required": [
                    "shippingAddress",
                    "requestedProducts"
                ]
            },
            "CreateOrderResponse": {
                "type": "object",
                "properties": {
                    "orderId": {
                        "type": "string",
                        "format": "uuid",
                        "description": "UUID of the created order."
                    },
                    "totalPriceCents": {
                        "type": "integer",
                        "description": "Total price of products before discount, in cents."
                    },
                    "discountCents": {
                        "type": "integer",
                        "description": "Total discount applied to the products, in cents."
                    },
                    "shippingCostCents": {
                        "type": "integer",
                        "description": "Total shipping cost for the order, in cents."
                    }
                },
                "required": [
                    "orderId",
                    "totalPriceCents",
                    "discountCents",
                    "shippingCostCents"
                ]
            },
            "CheckReservationResponse": {
                "type": "object",
                "properties": {
                    "isValid": {
                        "type": "boolean",
                        "description": "Indicates if the reservation is feasible based on inventory and shipping cost limits."
                    },
                    "totalPriceCents": {
                        "type": "integer",
                        "description": "Total price of requested products before discount, in cents."
                    },
                    "discountCents": {
                        "type": "integer",
                        "description": "Total discount applicable to the requested products, in cents."
                    },
                    "shippingCostCents": {
                        "type": "integer",
                        "description": "Calculated total shipping cost for the requested products, in cents. This value is provided even if isValid is false due to inventory issues, reflecting the cost if inventory were available, or the cost that violated limits."
                    },
                    "message": {
                        "type": "string",
                        "description": "An optional message, typically present if 'isValid' is false, explaining the reason.",
                        "nullable": true
                    }
                },
                "required": [
                    "isValid",
                    "totalPriceCents",
                    "discountCents",
                    "shippingCostCents"
                ]
            },
            "ErrorResponse": {
                "type": "object",
                "properties": {
                    "message": {
                        "type": "string",
                        "description": "A human-readable error message."
                    },
                    "issues": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "path": {
                                    "type": "array",
                                    "items": {
                                        "oneOf": [
                                            { "type": "string" },
                                            { "type": "integer" }
                                        ]
                                    }
                                },
                                "message": {
                                    "type": "string"
                                }
                            }
                        },
                        "description": "Optional array of specific validation issues (e.g., from Zod)."
                    }
                },
                "required": [
                    "message"
                ]
            }
        }
    }
}