{ "components": { "schemas": { "Customer": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "email": { "title": "Email", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" } }, "required": [ "id", "name", "email", "created_at" ], "title": "Customer", "type": "object" }, "Error": { "properties": { "detail": { "title": "Detail", "type": "string" } }, "required": [ "detail" ], "title": "Error", "type": "object" }, "Invoice": { "properties": { "amount": { "title": "Amount", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "issued_at": { "format": "date-time", "title": "Issued At", "type": "string" }, "order_id": { "format": "uuid", "title": "Order Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "order_id", "amount", "status", "issued_at" ], "title": "Invoice", "type": "object" }, "Order": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "currency": { "title": "Currency", "type": "string" }, "customer_id": { "format": "uuid", "title": "Customer Id", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/OrderItem" }, "title": "Items", "type": "array" }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "total": { "title": "Total", "type": "string" } }, "required": [ "id", "customer_id", "status", "items", "total", "currency", "created_at" ], "title": "Order", "type": "object" }, "OrderIn": { "properties": { "customer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Required for staff/admin; customers always order for themselves", "format": "uuid", "title": "Customer Id" }, "items": { "items": { "$ref": "#/components/schemas/OrderItemIn" }, "maxItems": 50, "minItems": 1, "title": "Items", "type": "array" } }, "required": [ "items" ], "title": "OrderIn", "type": "object" }, "OrderItem": { "properties": { "line_total": { "description": "unit_price * quantity rounded half-up to cents", "title": "Line Total", "type": "string" }, "product_id": { "format": "uuid", "title": "Product Id", "type": "string" }, "quantity": { "title": "Quantity", "type": "integer" }, "unit_price": { "title": "Unit Price", "type": "string" } }, "required": [ "product_id", "quantity", "unit_price", "line_total" ], "title": "OrderItem", "type": "object" }, "OrderItemIn": { "properties": { "product_id": { "format": "uuid", "title": "Product Id", "type": "string" }, "quantity": { "description": "Units ordered, 1..1000", "examples": [ 2 ], "title": "Quantity", "type": "integer" } }, "required": [ "product_id", "quantity" ], "title": "OrderItemIn", "type": "object" }, "OrderPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/Order" }, "title": "Items", "type": "array" }, "page": { "title": "Page", "type": "integer" }, "page_size": { "title": "Page Size", "type": "integer" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "items", "page", "page_size", "total" ], "title": "OrderPage", "type": "object" }, "OrderStatus": { "enum": [ "pending", "paid", "cancelled", "shipped" ], "title": "OrderStatus", "type": "string" }, "Product": { "properties": { "active": { "title": "Active", "type": "boolean" }, "currency": { "title": "Currency", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "price": { "description": "Unit price as a decimal string with up to 3 decimals", "examples": [ "19.99" ], "title": "Price", "type": "string" }, "sku": { "title": "Sku", "type": "string" } }, "required": [ "id", "sku", "name", "price", "currency", "active" ], "title": "Product", "type": "object" }, "ProductPatch": { "properties": { "active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Active" }, "name": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "price": { "anyOf": [ { "pattern": "^\\d{1,6}(\\.\\d{1,3})?$", "type": "string" }, { "type": "null" } ], "examples": [ "21.50" ], "title": "Price" } }, "title": "ProductPatch", "type": "object" } }, "securitySchemes": { "HTTPBearer": { "description": "Opaque role token, e.g. `Bearer tok-admin`", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Customers, products, orders, invoices and a signed payment webhook. All endpoints except /health and /webhooks/payment require `Authorization: Bearer `.", "title": "Orders and Invoicing API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/customers": { "get": { "operationId": "list_customers_customers_get", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Customer" }, "title": "Response List Customers Customers Get", "type": "array" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Role not allowed" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Customers", "tags": [ "customers" ] } }, "/customers/{customer_id}": { "get": { "operationId": "get_customer_customers__customer_id__get", "parameters": [ { "in": "path", "name": "customer_id", "required": true, "schema": { "format": "uuid", "title": "Customer Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Role not allowed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found (or not visible to the caller)" }, "422": { "description": "Validation error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Customer", "tags": [ "customers" ] } }, "/health": { "get": { "operationId": "health_health_get", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "title": "Response Health Health Get", "type": "object" } } }, "description": "Successful Response" } }, "summary": "Health", "tags": [ "meta" ] } }, "/orders": { "get": { "description": "List orders, newest first. Customers see only their own orders.", "operationId": "list_orders_orders_get", "parameters": [ { "description": "1-based page number", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "description": "1-based page number", "minimum": 1, "title": "Page", "type": "integer" } }, { "description": "Items per page, max 100", "in": "query", "name": "page_size", "required": false, "schema": { "default": 20, "description": "Items per page, max 100", "minimum": 1, "title": "Page Size", "type": "integer" } }, { "description": "Filter by status", "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by status", "enum": [ "pending", "paid", "cancelled", "shipped" ], "title": "Status" } }, { "description": "ISO 8601; naive values are UTC", "in": "query", "name": "created_from", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601; naive values are UTC", "format": "date-time", "title": "Created From" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPage" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid token" }, "422": { "description": "Validation error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Orders", "tags": [ "orders" ] }, "post": { "description": "Create an order. Customers order for themselves; staff/admin must pass customer_id.\n\nRepeating a request with the same `Idempotency-Key` returns the original order with 200.", "operationId": "create_order_orders_post", "parameters": [ { "in": "header", "name": "idempotency-key", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderIn" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "Replay of an earlier request with the same Idempotency-Key" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Role not allowed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found (or not visible to the caller)" }, "422": { "description": "Validation error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Order", "tags": [ "orders" ] } }, "/orders/{order_id}": { "get": { "operationId": "get_order_orders__order_id__get", "parameters": [ { "in": "path", "name": "order_id", "required": true, "schema": { "format": "uuid", "title": "Order Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid token" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found (or not visible to the caller)" }, "422": { "description": "Validation error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Order", "tags": [ "orders" ] } }, "/orders/{order_id}/cancel": { "post": { "description": "Cancel a pending or paid order. Owner, staff or admin.", "operationId": "cancel_order_orders__order_id__cancel_post", "parameters": [ { "in": "path", "name": "order_id", "required": true, "schema": { "format": "uuid", "title": "Order Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid token" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found (or not visible to the caller)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid state transition" }, "422": { "description": "Validation error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cancel Order", "tags": [ "orders" ] } }, "/orders/{order_id}/invoice": { "get": { "operationId": "get_order_invoice_orders__order_id__invoice_get", "parameters": [ { "in": "path", "name": "order_id", "required": true, "schema": { "format": "uuid", "title": "Order Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid token" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found (or not visible to the caller)" }, "422": { "description": "Validation error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Order Invoice", "tags": [ "invoices" ] } }, "/orders/{order_id}/ship": { "post": { "description": "Mark a paid order as shipped. Staff or admin.", "operationId": "ship_order_orders__order_id__ship_post", "parameters": [ { "in": "path", "name": "order_id", "required": true, "schema": { "format": "uuid", "title": "Order Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Role not allowed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found (or not visible to the caller)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid state transition" }, "422": { "description": "Validation error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ship Order", "tags": [ "orders" ] } }, "/products": { "get": { "operationId": "list_products_products_get", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Product" }, "title": "Response List Products Products Get", "type": "array" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid token" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Products", "tags": [ "products" ] } }, "/products/{product_id}": { "get": { "operationId": "get_product_products__product_id__get", "parameters": [ { "in": "path", "name": "product_id", "required": true, "schema": { "format": "uuid", "title": "Product Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid token" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found (or not visible to the caller)" }, "422": { "description": "Validation error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Product", "tags": [ "products" ] }, "patch": { "description": "Update a product. Admin only.", "operationId": "patch_product_products__product_id__patch", "parameters": [ { "in": "path", "name": "product_id", "required": true, "schema": { "format": "uuid", "title": "Product Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductPatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Role not allowed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found (or not visible to the caller)" }, "422": { "description": "Validation error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Patch Product", "tags": [ "products" ] } }, "/webhooks/payment": { "post": { "description": "Payment provider callback. Authenticated by `X-Signature` (HMAC-SHA256 of the raw body\nwith the shared secret), not by a bearer token. Duplicate `event_id`s are ignored.", "operationId": "payment_webhook_webhooks_payment_post", "parameters": [ { "description": "hex HMAC-SHA256 of the raw body", "in": "header", "name": "x-signature", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "hex HMAC-SHA256 of the raw body", "title": "X-Signature" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "amount": { "title": "Amount", "type": "string" }, "event_id": { "maxLength": 64, "minLength": 1, "title": "Event Id", "type": "string" }, "order_id": { "format": "uuid", "title": "Order Id", "type": "string" }, "status": { "description": "'succeeded' or 'failed'", "title": "Status", "type": "string" } }, "required": [ "event_id", "order_id", "amount", "status" ], "title": "PaymentEvent", "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "title": "Response Payment Webhook Webhooks Payment Post", "type": "object" } } }, "description": "Processed (or duplicate event ignored)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid signature" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unknown order" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Order not payable" }, "422": { "description": "Validation error" } }, "summary": "Payment Webhook", "tags": [ "webhooks" ] } } } }