{ "openapi": "3.0.0", "paths": { "/api/v1/auth/me": { "get": { "operationId": "AuthController_me", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "name": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } }, "tenantId": { "type": "string", "format": "uuid" }, "mfaEnabled": { "type": "boolean" } } } } }, "example": { "success": true, "data": { "id": "b0000000-0000-4000-a000-000000000001", "email": "admin@example.com", "name": "Sabine Weller", "roles": ["OWNER"], "tenantId": "a0000000-0000-4000-a000-000000000001", "mfaEnabled": false } } } } } }, "summary": "Verify credentials", "tags": ["Auth"], "description": "Returns the user your API key acts as, including tenant and roles. Use this as a connectivity and permission check when setting up an integration." } }, "/api/v1/categories": { "get": { "operationId": "CategoriesController_findAll", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parentId": { "nullable": true }, "sortOrder": { "type": "integer" }, "icon": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "productCount": { "type": "integer" }, "children": { "type": "array", "items": { "type": "object" }, "description": "Recursively nested — same shape as the parent object." } } } } } }, "example": { "success": true, "data": [ { "id": "50bc753b-d66f-4ae0-98b6-6a6da9168f7b", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Schmuck", "slug": "schmuck", "parentId": null, "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:03.200Z", "updatedAt": "2026-05-11T14:33:03.200Z", "productCount": 2, "children": [ { "id": "c3a1e32a-0fd8-4cc0-a2f9-26cfe4025e82", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Pandora-Schmuck", "slug": "schmuck-pandora-schmuck", "parentId": "50bc753b-d66f-4ae0-98b6-6a6da9168f7b", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:03.266Z", "updatedAt": "2026-05-11T14:33:03.266Z", "productCount": 0, "children": [ { "id": "2cb02171-b8cd-49f4-ad1f-be2c9624d5fa", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Bracelet", "slug": "schmuck-pandora-schmuck-bracelet", "parentId": "c3a1e32a-0fd8-4cc0-a2f9-26cfe4025e82", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:35:04.416Z", "updatedAt": "2026-05-11T14:35:04.416Z", "productCount": 3, "children": [] }, { "id": "eb447c55-d7be-420a-8c3d-05a128b5ee0e", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Charm", "slug": "schmuck-pandora-schmuck-charm", "parentId": "c3a1e32a-0fd8-4cc0-a2f9-26cfe4025e82", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:03.442Z", "updatedAt": "2026-05-11T14:33:03.442Z", "productCount": 385, "children": [] } ] }, { "id": "fdea1f80-8653-4bb6-874e-7b9d98b05907", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Stahlschmuck", "slug": "schmuck-stahlschmuck", "parentId": "50bc753b-d66f-4ae0-98b6-6a6da9168f7b", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:03.278Z", "updatedAt": "2026-05-11T14:33:03.278Z", "productCount": 0, "children": [ { "id": "f0878345-d7c1-408c-ab96-5a0882a0b7ee", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "SET", "slug": "schmuck-stahlschmuck-set", "parentId": "fdea1f80-8653-4bb6-874e-7b9d98b05907", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:35:04.443Z", "updatedAt": "2026-05-11T14:35:04.443Z", "productCount": 4, "children": [] }, { "id": "94201ce0-3696-4888-9924-585778b4f9ee", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Ohrstecker", "slug": "schmuck-stahlschmuck-ohrstecker", "parentId": "fdea1f80-8653-4bb6-874e-7b9d98b05907", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:03.462Z", "updatedAt": "2026-05-11T14:33:03.462Z", "productCount": 16, "children": [] } ] } ] }, { "id": "3771064f-56c3-4f7b-835b-8f4f3e78a5a9", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Allgemeine Artikel", "slug": "allgemeine-artikel", "parentId": null, "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:03.234Z", "updatedAt": "2026-05-11T14:33:03.234Z", "productCount": 0, "children": [ { "id": "6f6a5a66-2386-4bc3-b822-dc8fc9d996f2", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Diverses", "slug": "allgemeine-artikel-diverses", "parentId": "3771064f-56c3-4f7b-835b-8f4f3e78a5a9", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:03.289Z", "updatedAt": "2026-05-11T14:33:03.289Z", "productCount": 0, "children": [ { "id": "30c33426-f6ca-4cab-8424-20b369dd96a3", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Ohrlochantisept", "slug": "allgemeine-artikel-diverses-ohrlochantisept", "parentId": "6f6a5a66-2386-4bc3-b822-dc8fc9d996f2", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:03.478Z", "updatedAt": "2026-05-11T14:33:03.478Z", "productCount": 1, "children": [] }, { "id": "ec030557-4828-4b66-becc-82ac47385b16", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "SS Sets, Pakete", "slug": "allgemeine-artikel-diverses-ss-sets-pakete", "parentId": "6f6a5a66-2386-4bc3-b822-dc8fc9d996f2", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:34:04.416Z", "updatedAt": "2026-05-11T14:34:04.416Z", "productCount": 1, "children": [] } ] }, { "id": "a8fa5fe7-2d9c-4008-ae29-112b51f65963", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Lederwaren", "slug": "allgemeine-artikel-lederwaren", "parentId": "3771064f-56c3-4f7b-835b-8f4f3e78a5a9", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:03.408Z", "updatedAt": "2026-05-11T14:33:03.408Z", "productCount": 0, "children": [ { "id": "fabc9181-cc67-4fb1-91ff-afa46046393b", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Lederband", "slug": "allgemeine-artikel-lederwaren-lederband", "parentId": "a8fa5fe7-2d9c-4008-ae29-112b51f65963", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:34:57.896Z", "updatedAt": "2026-05-11T14:34:57.896Z", "productCount": 1, "children": [] }, { "id": "5543fca4-d03b-42df-a4c1-d414d7e65460", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Armband", "slug": "allgemeine-artikel-lederwaren-armband", "parentId": "a8fa5fe7-2d9c-4008-ae29-112b51f65963", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:35:04.404Z", "updatedAt": "2026-05-11T14:35:04.404Z", "productCount": 1, "children": [] } ] } ] } ] } } } } }, "summary": "List categories", "tags": ["Categories"], "description": "Returns all product categories of your tenant, including their hierarchy (parent/child relations)." }, "post": { "operationId": "CategoriesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/catalog_CreateCategoryDto" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parentId": { "nullable": true }, "sortOrder": { "type": "integer" }, "icon": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "productCount": { "type": "integer" }, "children": { "type": "array", "items": { "type": "object" } } } } } }, "example": { "success": true, "data": { "id": "8910d404-0be2-432b-8f0a-73dea5dcffcb", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Docs Example", "slug": "docs-example", "parentId": null, "sortOrder": 0, "icon": null, "createdAt": "2026-07-10T15:14:49.919Z", "updatedAt": "2026-07-10T15:14:49.919Z", "productCount": 0, "children": [] } } } } } }, "summary": "Create a category", "tags": ["Categories"], "description": "Creates a new product category. Provide a parent ID to place it inside an existing category." } }, "/api/v1/categories/{id}": { "get": { "operationId": "CategoriesController_findById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parentId": { "nullable": true }, "sortOrder": { "type": "integer" }, "icon": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "productCount": { "type": "integer" }, "children": { "type": "array", "items": { "type": "object" }, "description": "Recursively nested — same shape as the parent object." } } } } }, "example": { "success": true, "data": { "id": "50bc753b-d66f-4ae0-98b6-6a6da9168f7b", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Schmuck", "slug": "schmuck", "parentId": null, "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:03.200Z", "updatedAt": "2026-05-11T14:33:03.200Z", "productCount": 2, "children": [ { "id": "c3a1e32a-0fd8-4cc0-a2f9-26cfe4025e82", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Pandora-Schmuck", "slug": "schmuck-pandora-schmuck", "parentId": "50bc753b-d66f-4ae0-98b6-6a6da9168f7b", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:03.266Z", "updatedAt": "2026-05-11T14:33:03.266Z", "productCount": 0, "children": [ { "id": "2cb02171-b8cd-49f4-ad1f-be2c9624d5fa", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Bracelet", "slug": "schmuck-pandora-schmuck-bracelet", "parentId": "c3a1e32a-0fd8-4cc0-a2f9-26cfe4025e82", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:35:04.416Z", "updatedAt": "2026-05-11T14:35:04.416Z", "productCount": 3, "children": [] }, { "id": "eb447c55-d7be-420a-8c3d-05a128b5ee0e", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Charm", "slug": "schmuck-pandora-schmuck-charm", "parentId": "c3a1e32a-0fd8-4cc0-a2f9-26cfe4025e82", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:03.442Z", "updatedAt": "2026-05-11T14:33:03.442Z", "productCount": 385, "children": [] } ] }, { "id": "fdea1f80-8653-4bb6-874e-7b9d98b05907", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Stahlschmuck", "slug": "schmuck-stahlschmuck", "parentId": "50bc753b-d66f-4ae0-98b6-6a6da9168f7b", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:03.278Z", "updatedAt": "2026-05-11T14:33:03.278Z", "productCount": 0, "children": [ { "id": "f0878345-d7c1-408c-ab96-5a0882a0b7ee", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "SET", "slug": "schmuck-stahlschmuck-set", "parentId": "fdea1f80-8653-4bb6-874e-7b9d98b05907", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:35:04.443Z", "updatedAt": "2026-05-11T14:35:04.443Z", "productCount": 4, "children": [] }, { "id": "94201ce0-3696-4888-9924-585778b4f9ee", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Ohrstecker", "slug": "schmuck-stahlschmuck-ohrstecker", "parentId": "fdea1f80-8653-4bb6-874e-7b9d98b05907", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:03.462Z", "updatedAt": "2026-05-11T14:33:03.462Z", "productCount": 16, "children": [] } ] } ] } } } } } }, "summary": "Get a category", "tags": ["Categories"], "description": "Returns a single category by ID." }, "patch": { "operationId": "CategoriesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/catalog_UpdateCategoryDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parentId": { "nullable": true }, "sortOrder": { "type": "integer" }, "icon": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "productCount": { "type": "integer" }, "children": { "type": "array", "items": { "type": "object" } } } } } }, "example": { "success": true, "data": { "id": "8910d404-0be2-432b-8f0a-73dea5dcffcb", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Docs Example Renamed", "slug": "docs-example", "parentId": null, "sortOrder": 0, "icon": null, "createdAt": "2026-07-10T15:14:49.919Z", "updatedAt": "2026-07-10T15:14:49.958Z", "productCount": 0, "children": [] } } } } } }, "summary": "Update a category", "tags": ["Categories"], "description": "Updates a category — editable fields are name, slug, parent, sort order, and icon. Only the fields you send are changed." }, "delete": { "operationId": "CategoriesController_delete", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content — the resource was deleted." } }, "summary": "Delete a category", "tags": ["Categories"], "description": "Deletes a category. Fails with `409 Conflict` if any products or child categories are still assigned to it — reassign or remove them first." } }, "/api/v1/attributes": { "get": { "operationId": "AttributesController_findAll", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "object" } }, "required": { "type": "boolean" }, "filterable": { "type": "boolean" }, "showOnReceipt": { "type": "boolean" }, "sortOrder": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "_count": { "type": "object", "properties": { "values": { "type": "integer" } } } } } } } }, "example": { "success": true, "data": [ { "id": "9f47167f-5d46-45a6-91d8-e3adc327b6e8", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Online-Shop gültig bis", "slug": "online-shop-gueltig-bis", "type": "STRING", "options": [], "required": false, "filterable": false, "showOnReceipt": false, "sortOrder": 0, "createdAt": "2026-05-11T18:59:14.200Z", "updatedAt": "2026-05-11T18:59:14.200Z", "_count": { "values": 0 } }, { "id": "f4806f9e-b86a-4c1d-8113-e67c0bc72605", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Kernsortiment", "slug": "kernsortiment", "type": "BOOLEAN", "options": [], "required": false, "filterable": true, "showOnReceipt": false, "sortOrder": 0, "createdAt": "2026-05-11T17:55:17.843Z", "updatedAt": "2026-05-11T17:55:17.843Z", "_count": { "values": 3622 } } ] } } } } }, "summary": "List attribute definitions", "tags": ["Attributes"], "description": "Returns the attribute definitions configured for your tenant (e.g. metal, carat, ring size for jewelry). In product responses these appear as an `attributeValues` array — each entry carries the `attributeDefinitionId`, the value, and the embedded definition. Fetch this list to interpret them." } }, "/api/v1/products": { "get": { "operationId": "ProductsController_findAll", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } }, { "name": "sortBy", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "sortOrder", "required": false, "in": "query", "schema": { "$ref": "#/components/schemas/catalog_Object" } }, { "name": "categoryId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "isActive", "required": false, "in": "query", "schema": { "type": "boolean" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "brand", "required": false, "in": "query", "description": "Exact-match brand filter (case-insensitive).", "schema": { "type": "string" } }, { "name": "vatRate", "required": false, "in": "query", "description": "Filter by VAT rate code.", "schema": { "$ref": "#/components/schemas/catalog_Object" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" }, "description": "Recursively nested — same shape as the parent object." }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } }, "example": { "success": true, "data": { "data": [ { "id": "f3134101-9b40-41f5-bb4b-2618c02d467a", "tenantId": "a0000000-0000-4000-a000-000000000001", "sku": "RING-1234", "barcode": null, "name": "Trauring 1", "description": null, "imageUrl": null, "categoryId": "4d478b37-2355-47e8-ba2a-d5b442650201", "price": "2000", "price2": null, "costPrice": "1200", "vatRate": "NORMAL", "taxTreatment": "REGULAR", "marginPurchasePrice": null, "brand": null, "productType": null, "isActive": true, "sortOrder": 0, "createdAt": "2026-07-10T12:37:29.831Z", "updatedAt": "2026-07-10T12:37:29.831Z", "deletedAt": null, "category": { "id": "4d478b37-2355-47e8-ba2a-d5b442650201", "name": "RING", "slug": "schmuck-stahlschmuck-ring" }, "_count": { "attributeValues": 0 }, "discounts": [], "thumbnailUrl": null, "mediumUrl": null, "salePrice": null } ], "meta": { "page": 1, "limit": 1, "total": 3647, "totalPages": 3647 } } } } } } }, "summary": "List products", "tags": ["Products"], "description": "Returns the product catalog, paginated. Filter by `search` (name/SKU/barcode), `categoryId`, `brand`, `isActive`, or `vatRate`; sort with `sortBy`/`sortOrder`." }, "post": { "operationId": "ProductsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/catalog_CreateProductDto" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "nullable": true }, "name": { "type": "string" }, "description": { "nullable": true }, "imageUrl": { "nullable": true }, "categoryId": { "type": "string", "format": "uuid" }, "price": { "type": "string" }, "price2": { "nullable": true }, "costPrice": { "type": "string" }, "vatRate": { "type": "string" }, "taxTreatment": { "type": "string" }, "marginPurchasePrice": { "nullable": true }, "brand": { "nullable": true }, "productType": { "nullable": true }, "isActive": { "type": "boolean" }, "sortOrder": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true }, "category": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parentId": { "type": "string", "format": "uuid" }, "sortOrder": { "type": "integer" }, "icon": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "attributeValues": { "type": "array", "items": { "type": "object" } }, "thumbnailUrl": { "nullable": true }, "mediumUrl": { "nullable": true } } } } }, "example": { "success": true, "data": { "id": "f3134101-9b40-41f5-bb4b-2618c02d467a", "tenantId": "a0000000-0000-4000-a000-000000000001", "sku": "RING-1234", "barcode": null, "name": "Trauring 1", "description": null, "imageUrl": null, "categoryId": "4d478b37-2355-47e8-ba2a-d5b442650201", "price": "2000", "price2": null, "costPrice": "1200", "vatRate": "NORMAL", "taxTreatment": "REGULAR", "marginPurchasePrice": null, "brand": null, "productType": null, "isActive": true, "sortOrder": 0, "createdAt": "2026-07-10T12:37:29.831Z", "updatedAt": "2026-07-10T12:37:29.831Z", "deletedAt": null, "category": { "id": "4d478b37-2355-47e8-ba2a-d5b442650201", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "RING", "slug": "schmuck-stahlschmuck-ring", "parentId": "fdea1f80-8653-4bb6-874e-7b9d98b05907", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:04.260Z", "updatedAt": "2026-05-11T14:33:04.260Z" }, "attributeValues": [], "thumbnailUrl": null, "mediumUrl": null } } } } } }, "summary": "Create a product", "tags": ["Products"], "description": "Creates a product with master data, price, VAT rate, barcode, and industry-specific attributes. Typical entry point for catalog sync from an external system." } }, "/api/v1/products/barcode/{code}": { "get": { "operationId": "ProductsController_findByBarcode", "parameters": [ { "name": "code", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "imageUrl": { "nullable": true }, "categoryId": { "type": "string", "format": "uuid" }, "price": { "type": "string" }, "price2": { "nullable": true }, "costPrice": { "type": "string" }, "vatRate": { "type": "string" }, "taxTreatment": { "type": "string" }, "marginPurchasePrice": { "nullable": true }, "brand": { "type": "string" }, "productType": { "type": "string" }, "isActive": { "type": "boolean" }, "sortOrder": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true }, "category": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parentId": { "type": "string", "format": "uuid" }, "sortOrder": { "type": "integer" }, "icon": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "attributeValues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "attributeDefinitionId": { "type": "string", "format": "uuid" }, "value": { "type": "string" }, "definition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "object" } } } } } } }, "thumbnailUrl": { "nullable": true }, "mediumUrl": { "nullable": true } } } } }, "example": { "success": true, "data": { "id": "a6623341-135e-4393-a300-1ffffdda73c4", "tenantId": "a0000000-0000-4000-a000-000000000001", "sku": "T0634281105800", "barcode": "7611608280249", "name": "TISSOT Armbanduhr · T0634281105800", "description": "", "imageUrl": null, "categoryId": "14ab9516-0434-41bb-9dcc-60826249e4ab", "price": "845", "price2": null, "costPrice": "345", "vatRate": "NORMAL", "taxTreatment": "REGULAR", "marginPurchasePrice": null, "brand": "TISSOT", "productType": "Armbanduhr", "isActive": true, "sortOrder": 0, "createdAt": "2026-05-11T15:01:43.469Z", "updatedAt": "2026-05-11T19:29:57.284Z", "deletedAt": null, "category": { "id": "14ab9516-0434-41bb-9dcc-60826249e4ab", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Armbanduhr", "slug": "uhren-kleinuhren-armbanduhr", "parentId": "ebd8f53b-fb7c-4a4b-b7f7-6b381c05f009", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:03.656Z", "updatedAt": "2026-05-11T14:33:03.656Z" }, "attributeValues": [ { "id": "94f600c1-3310-4156-8a43-f8255c78d625", "productId": "a6623341-135e-4393-a300-1ffffdda73c4", "attributeDefinitionId": "e8e3e8a7-daf0-4c05-8374-848786950ca4", "value": "Tiss-Swatch Group Deutschland", "definition": { "id": "e8e3e8a7-daf0-4c05-8374-848786950ca4", "name": "Lieferant", "slug": "lieferant", "type": "STRING", "options": [] } }, { "id": "2069d6e1-cbb4-4cbf-b77b-f6c114be9df9", "productId": "a6623341-135e-4393-a300-1ffffdda73c4", "attributeDefinitionId": "c9fc9977-17f0-454e-9c5c-bc261c53fd9e", "value": "Swatch Group Deutschland GmbH Division Tissot", "definition": { "id": "c9fc9977-17f0-454e-9c5c-bc261c53fd9e", "name": "Letzter Lieferant", "slug": "letzter-lieferant", "type": "STRING", "options": [] } } ], "thumbnailUrl": null, "mediumUrl": null } } } } } }, "summary": "Look up by barcode or SKU", "tags": ["Products"], "description": "Resolves a scan code to a single product. Matches the product barcode (EAN/GTIN) first, then falls back to the SKU (Artikelnummer). Returns `404` only if neither matches." } }, "/api/v1/products/{id}": { "get": { "operationId": "ProductsController_findById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "nullable": true }, "name": { "type": "string" }, "description": { "nullable": true }, "imageUrl": { "nullable": true }, "categoryId": { "type": "string", "format": "uuid" }, "price": { "type": "string" }, "price2": { "nullable": true }, "costPrice": { "type": "string" }, "vatRate": { "type": "string" }, "taxTreatment": { "type": "string" }, "marginPurchasePrice": { "nullable": true }, "brand": { "nullable": true }, "productType": { "nullable": true }, "isActive": { "type": "boolean" }, "sortOrder": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true }, "category": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parentId": { "type": "string", "format": "uuid" }, "sortOrder": { "type": "integer" }, "icon": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "attributeValues": { "type": "array", "items": { "type": "object" } }, "thumbnailUrl": { "nullable": true }, "mediumUrl": { "nullable": true }, "lastPurchasePrice": { "nullable": true }, "avgPurchasePrice": { "nullable": true } } } } }, "example": { "success": true, "data": { "id": "f3134101-9b40-41f5-bb4b-2618c02d467a", "tenantId": "a0000000-0000-4000-a000-000000000001", "sku": "RING-1234", "barcode": null, "name": "Trauring 1", "description": null, "imageUrl": null, "categoryId": "4d478b37-2355-47e8-ba2a-d5b442650201", "price": "2000", "price2": null, "costPrice": "1200", "vatRate": "NORMAL", "taxTreatment": "REGULAR", "marginPurchasePrice": null, "brand": null, "productType": null, "isActive": true, "sortOrder": 0, "createdAt": "2026-07-10T12:37:29.831Z", "updatedAt": "2026-07-10T12:37:29.831Z", "deletedAt": null, "category": { "id": "4d478b37-2355-47e8-ba2a-d5b442650201", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "RING", "slug": "schmuck-stahlschmuck-ring", "parentId": "fdea1f80-8653-4bb6-874e-7b9d98b05907", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:04.260Z", "updatedAt": "2026-05-11T14:33:04.260Z" }, "attributeValues": [], "thumbnailUrl": null, "mediumUrl": null, "lastPurchasePrice": null, "avgPurchasePrice": null } } } } } }, "summary": "Get a product", "tags": ["Products"], "description": "Returns a single product with all master data, price information, and attributes." }, "patch": { "operationId": "ProductsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/catalog_UpdateProductDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "nullable": true }, "name": { "type": "string" }, "description": { "nullable": true }, "imageUrl": { "nullable": true }, "categoryId": { "type": "string", "format": "uuid" }, "price": { "type": "string" }, "price2": { "nullable": true }, "costPrice": { "type": "string" }, "vatRate": { "type": "string" }, "taxTreatment": { "type": "string" }, "marginPurchasePrice": { "nullable": true }, "brand": { "nullable": true }, "productType": { "nullable": true }, "isActive": { "type": "boolean" }, "sortOrder": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true }, "category": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parentId": { "type": "string", "format": "uuid" }, "sortOrder": { "type": "integer" }, "icon": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "attributeValues": { "type": "array", "items": { "type": "object" } }, "thumbnailUrl": { "nullable": true }, "mediumUrl": { "nullable": true } } } } }, "example": { "success": true, "data": { "id": "f3134101-9b40-41f5-bb4b-2618c02d467a", "tenantId": "a0000000-0000-4000-a000-000000000001", "sku": "RING-1234", "barcode": null, "name": "Trauring 1", "description": null, "imageUrl": null, "categoryId": "4d478b37-2355-47e8-ba2a-d5b442650201", "price": "2000", "price2": null, "costPrice": "1200", "vatRate": "NORMAL", "taxTreatment": "REGULAR", "marginPurchasePrice": null, "brand": null, "productType": null, "isActive": true, "sortOrder": 0, "createdAt": "2026-07-10T12:37:29.831Z", "updatedAt": "2026-07-10T15:16:35.944Z", "deletedAt": null, "category": { "id": "4d478b37-2355-47e8-ba2a-d5b442650201", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "RING", "slug": "schmuck-stahlschmuck-ring", "parentId": "fdea1f80-8653-4bb6-874e-7b9d98b05907", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:04.260Z", "updatedAt": "2026-05-11T14:33:04.260Z" }, "attributeValues": [], "thumbnailUrl": null, "mediumUrl": null } } } } } }, "summary": "Update a product", "tags": ["Products"], "description": "Partially updates a product — only the fields you send are changed. Note: this does not change the main selling price or cost price (those are managed in the Gemwise dashboard and are not exposed via the public API); the secondary price field `price2` can be set here." } }, "/api/v1/products/{id}/image": { "post": { "operationId": "ProductsController_uploadImage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "nullable": true }, "name": { "type": "string" }, "description": { "nullable": true }, "imageUrl": { "type": "string" }, "categoryId": { "type": "string", "format": "uuid" }, "price": { "type": "string" }, "price2": { "nullable": true }, "costPrice": { "type": "string" }, "vatRate": { "type": "string" }, "taxTreatment": { "type": "string" }, "marginPurchasePrice": { "nullable": true }, "brand": { "nullable": true }, "productType": { "nullable": true }, "isActive": { "type": "boolean" }, "sortOrder": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true }, "category": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parentId": { "type": "string", "format": "uuid" }, "sortOrder": { "type": "integer" }, "icon": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "attributeValues": { "type": "array", "items": { "type": "object" } }, "thumbnailUrl": { "nullable": true }, "mediumUrl": { "nullable": true } } } } }, "example": { "success": true, "data": { "id": "f3134101-9b40-41f5-bb4b-2618c02d467a", "tenantId": "a0000000-0000-4000-a000-000000000001", "sku": "RING-1234", "barcode": null, "name": "Trauring 1", "description": null, "imageUrl": "https://cdn.gemwise.de/tenants/a0000000/products/f3134101.webp", "categoryId": "4d478b37-2355-47e8-ba2a-d5b442650201", "price": "2000", "price2": null, "costPrice": "1200", "vatRate": "NORMAL", "taxTreatment": "REGULAR", "marginPurchasePrice": null, "brand": null, "productType": null, "isActive": true, "sortOrder": 0, "createdAt": "2026-07-10T12:37:29.831Z", "updatedAt": "2026-07-10T12:37:29.831Z", "deletedAt": null, "category": { "id": "4d478b37-2355-47e8-ba2a-d5b442650201", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "RING", "slug": "schmuck-stahlschmuck-ring", "parentId": "fdea1f80-8653-4bb6-874e-7b9d98b05907", "sortOrder": 0, "icon": null, "createdAt": "2026-05-11T14:33:04.260Z", "updatedAt": "2026-05-11T14:33:04.260Z" }, "attributeValues": [], "thumbnailUrl": null, "mediumUrl": null } } } } } }, "summary": "Upload product image", "tags": ["Products"], "description": "Uploads or replaces the product image (multipart/form-data)." }, "delete": { "operationId": "ProductsController_deleteImage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content — the resource was deleted." } }, "summary": "Remove product image", "tags": ["Products"], "description": "Removes the product image." } }, "/api/v1/inventory": { "get": { "operationId": "InventoryController_findAllStock", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } }, { "name": "warehouseId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "lowStock", "required": false, "in": "query", "schema": { "type": "boolean" } }, { "name": "sortBy", "required": false, "in": "query", "description": "quantity | reserved | reorderPoint | updatedAt — anything outside this set is ignored.", "schema": { "type": "string" } }, { "name": "sortOrder", "required": false, "in": "query", "schema": { "$ref": "#/components/schemas/inventory_Object" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" }, "description": "Recursively nested — same shape as the parent object." }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } }, "example": { "success": true, "data": { "data": [ { "id": "18de2751-b267-4fe7-aa1f-394f763fda76", "tenantId": "a0000000-0000-4000-a000-000000000001", "productId": "5423c277-c14f-445a-a45e-0303833c1218", "warehouseId": "e1000000-0000-4000-a000-000000000001", "quantity": 3, "reserved": 0, "reorderPoint": 5, "createdAt": "2026-07-10T13:46:53.305Z", "updatedAt": "2026-07-10T13:46:59.449Z", "warehouse": { "id": "e1000000-0000-4000-a000-000000000001", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Hauptlager", "isDefault": true, "createdAt": "2026-03-25T10:41:40.096Z", "updatedAt": "2026-03-25T10:41:40.096Z" } } ], "meta": { "page": 1, "limit": 1, "total": 2451, "totalPages": 2451 } } } } } } }, "summary": "List stock levels", "tags": ["Inventory"], "description": "Returns current stock per product, paginated. Filter by `warehouseId` or `lowStock` (quantity at or below the reorder point). Quantities distinguish on-hand and reserved stock." } }, "/api/v1/inventory/movements": { "get": { "operationId": "InventoryController_findMovements", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "number" } }, { "name": "productId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "warehouseId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "type", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" }, "description": "Recursively nested — same shape as the parent object." }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } }, "example": { "success": true, "data": { "data": [ { "id": "12721289-4a89-4b29-8ac9-90682cb9a468", "tenantId": "a0000000-0000-4000-a000-000000000001", "stockItemId": "64587f0a-c90e-4851-8961-b7f61716a017", "productId": "f3134101-9b40-41f5-bb4b-2618c02d467a", "warehouseId": "e1000000-0000-4000-a000-000000000001", "type": "SOLD", "quantity": -1, "quantityBefore": 1, "quantityAfter": 0, "referenceType": "deposit", "referenceId": "513a67fe-8c14-46da-859a-053b9cfe0898", "reasonCode": null, "performedBy": "b0000000-0000-4000-a000-000000000001", "notes": null, "createdAt": "2026-07-10T13:25:24.251Z" } ], "meta": { "page": 1, "limit": 1, "total": 2572, "totalPages": 2572 } } } } } } }, "summary": "List stock movements", "tags": ["Inventory"], "description": "Returns the append-only movement journal (sales, receipts, adjustments, transfers), paginated. Filter by `productId`, `warehouseId`, or movement `type`. Ideal as an incremental feed for keeping an external system in sync." } }, "/api/v1/inventory/{productId}": { "get": { "operationId": "InventoryController_findStockByProduct", "parameters": [ { "name": "productId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer" }, "reserved": { "type": "integer" }, "reorderPoint": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "warehouse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "example": { "success": true, "data": [ { "id": "64587f0a-c90e-4851-8961-b7f61716a017", "tenantId": "a0000000-0000-4000-a000-000000000001", "productId": "f3134101-9b40-41f5-bb4b-2618c02d467a", "warehouseId": "e1000000-0000-4000-a000-000000000001", "quantity": 0, "reserved": 0, "reorderPoint": 5, "createdAt": "2026-07-10T13:24:08.444Z", "updatedAt": "2026-07-10T13:25:24.246Z", "warehouse": { "id": "e1000000-0000-4000-a000-000000000001", "tenantId": "a0000000-0000-4000-a000-000000000001", "name": "Hauptlager", "isDefault": true, "createdAt": "2026-03-25T10:41:40.096Z", "updatedAt": "2026-03-25T10:41:40.096Z" } } ] } } } } }, "summary": "Get stock for a product", "tags": ["Inventory"], "description": "Returns the stock record of a single product across warehouses." } }, "/api/v1/inventory/receive": { "post": { "operationId": "InventoryController_receiveStock", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inventory_ReceiveStockDto" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "stockItemId": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "quantity": { "type": "integer" }, "quantityBefore": { "type": "integer" }, "quantityAfter": { "type": "integer" }, "referenceType": { "type": "string" }, "referenceId": { "nullable": true }, "reasonCode": { "nullable": true }, "performedBy": { "type": "string", "format": "uuid" }, "notes": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } }, "example": { "success": true, "data": { "id": "bf9fd2dd-cc4a-4bce-b4a7-c9c50064df9f", "tenantId": "a0000000-0000-4000-a000-000000000001", "stockItemId": "64587f0a-c90e-4851-8961-b7f61716a017", "productId": "f3134101-9b40-41f5-bb4b-2618c02d467a", "warehouseId": "e1000000-0000-4000-a000-000000000001", "type": "RECEIVED", "quantity": 1, "quantityBefore": 0, "quantityAfter": 1, "referenceType": "manual", "referenceId": null, "reasonCode": null, "performedBy": "b0000000-0000-4000-a000-000000000001", "notes": "Correction after recount", "createdAt": "2026-07-10T15:14:18.935Z" } } } } } }, "summary": "Receive stock", "tags": ["Inventory"], "description": "Books incoming goods: increases stock of a product in a warehouse by `quantity` and writes a movement record. Use `referenceType`/`referenceId` to link the receipt to an external document (e.g. a purchase order in your system)." } }, "/api/v1/inventory/adjust": { "post": { "operationId": "InventoryController_adjustStock", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inventory_AdjustStockDto" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "stockItemId": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "quantity": { "type": "integer" }, "quantityBefore": { "type": "integer" }, "quantityAfter": { "type": "integer" }, "referenceType": { "type": "string" }, "referenceId": { "nullable": true }, "reasonCode": { "type": "string" }, "performedBy": { "type": "string", "format": "uuid" }, "notes": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } }, "example": { "success": true, "data": { "id": "78c83c69-12e8-4180-a5e0-faceb8952395", "tenantId": "a0000000-0000-4000-a000-000000000001", "stockItemId": "64587f0a-c90e-4851-8961-b7f61716a017", "productId": "f3134101-9b40-41f5-bb4b-2618c02d467a", "warehouseId": "e1000000-0000-4000-a000-000000000001", "type": "ADJUSTED", "quantity": -1, "quantityBefore": 1, "quantityAfter": 0, "referenceType": "manual", "referenceId": null, "reasonCode": "COUNTING_ERROR", "performedBy": "b0000000-0000-4000-a000-000000000001", "notes": "Correction after recount", "createdAt": "2026-07-10T15:16:35.919Z" } } } } } }, "summary": "Adjust stock", "tags": ["Inventory"], "description": "Sets the stock of a product in a warehouse to `newQuantity` and records the variance with a mandatory `reasonCode`. Use this for corrections — regular in/out movements should use receive or transfer." } }, "/api/v1/inventory/transfer": { "post": { "operationId": "InventoryController_transferStock", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inventory_TransferStockDto" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "outMovement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "stockItemId": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "quantity": { "type": "integer" }, "quantityBefore": { "type": "integer" }, "quantityAfter": { "type": "integer" }, "referenceType": { "type": "string" }, "referenceId": { "nullable": true }, "reasonCode": { "nullable": true }, "performedBy": { "type": "string", "format": "uuid" }, "notes": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "inMovement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "stockItemId": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "quantity": { "type": "integer" }, "quantityBefore": { "type": "integer" }, "quantityAfter": { "type": "integer" }, "referenceType": { "type": "string" }, "referenceId": { "type": "string", "format": "uuid" }, "reasonCode": { "nullable": true }, "performedBy": { "type": "string", "format": "uuid" }, "notes": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } } } }, "example": { "success": true, "data": { "outMovement": { "id": "3f1c9a02-7e44-4b90-8a11-2d6b0c4e51aa", "tenantId": "a0000000-0000-4000-a000-000000000001", "stockItemId": "64587f0a-c90e-4851-8961-b7f61716a017", "productId": "f3134101-9b40-41f5-bb4b-2618c02d467a", "warehouseId": "e1000000-0000-4000-a000-000000000001", "type": "TRANSFERRED", "quantity": -1, "quantityBefore": 5, "quantityAfter": 4, "referenceType": "transfer", "referenceId": null, "reasonCode": null, "performedBy": "b0000000-0000-4000-a000-000000000001", "notes": "Transfer Hauptlager → Filiale Celle", "createdAt": "2026-07-10T15:14:18.935Z" }, "inMovement": { "id": "8b7d2e15-4c9f-4a03-91e6-fa1c7b3d09cc", "tenantId": "a0000000-0000-4000-a000-000000000001", "stockItemId": "64587f0a-c90e-4851-8961-b7f61716a017", "productId": "f3134101-9b40-41f5-bb4b-2618c02d467a", "warehouseId": "e2000000-0000-4000-a000-000000000009", "type": "TRANSFERRED", "quantity": 1, "quantityBefore": 0, "quantityAfter": 1, "referenceType": "transfer", "referenceId": "3f1c9a02-7e44-4b90-8a11-2d6b0c4e51aa", "reasonCode": null, "performedBy": "b0000000-0000-4000-a000-000000000001", "notes": "Transfer Hauptlager → Filiale Celle", "createdAt": "2026-07-10T15:14:18.935Z" } } } } } } }, "summary": "Transfer stock", "tags": ["Inventory"], "description": "Moves a quantity of a product from one warehouse to another; both sides are written to the movement journal." } }, "/api/v1/transactions": { "get": { "operationId": "TransactionController_findAll", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } }, { "name": "dateFrom", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "dateTo", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "transactionNumber", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "cashierId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "customerId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "paymentMethod", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "originalTransactionId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "registerId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" }, "description": "Recursively nested — same shape as the parent object." }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } }, "example": { "success": true, "data": { "data": [ { "id": "78f56cfc-8ce1-49c4-9b32-29e161904e5b", "tenantId": "a0000000-0000-4000-a000-000000000001", "registerId": "544897bb-6a66-41dd-919b-3f6a5b6d6525", "kassenSeriennr": "GW-A0BB0D", "sessionId": "eb2d8184-1b5f-4550-b004-08cd0db8d975", "transactionNumber": "BON-2026-479044", "idempotencyKey": null, "type": "RETURN", "status": "COMPLETED", "customerId": null, "cashierId": "b0000000-0000-4000-a000-000000000001", "subtotal": "-242.02", "taxAmount": "-45.98", "totalAmount": "-288", "discountAmount": "0", "taxBreakdown": [ { "net": -242.02, "tax": -45.98, "rate": "19%", "gross": -288, "ratePercent": 19 } ], "notes": "Return of items from BON-2026-276520", "originalTransactionId": "fa7f845b-91c1-424f-92d7-72945f228039", "tseSignature": "satQjKt44XTBn0WgbbnrEExCs+Y20zQtQodkI1C/tZ/YUneX9LPTfr7ASjadQFKFuPoXLhOkfSpHa52OeoWZNA==", "tseCounter": 309, "tseTxId": "e2d59760-dbc1-47bc-af25-44488924a24a", "tseStartTime": "2026-07-10T13:46:52.000Z", "tseFinishTime": "2026-07-10T13:46:52.000Z", "tseCertSerial": "0d5bc08b6e713e8faa7f4c6e0d2ac8769cb2b3eeb6d54205675f3ba480d1da86", "tseQrCodeData": "V0;GW-A0BB0D;Kassenbeleg-V1;Beleg^-288.00_0.00_0.00_0.00_0.00^-288.00:Unbar;98;309;2026-07-10T13:46:52.000Z;2026-07-10T13:46:52.000Z;ecdsa-plain-SHA256;unixTime;satQjKt44XTBn0WgbbnrEExCs+Y20zQtQodkI1C/tZ/YUneX9LPTfr7ASjadQFKFuPoXLhOkfSpHa52OeoWZNA==;BKWvdS77s+awjDnYEFegw/kibyxa28nsds0nm/TlS7Q3BvIY9IEFpGq3GGD0q3lymrNXW5kobPsFl5QnvpAXTw8=", "tseSignatureAlgorithm": "ecdsa-plain-SHA256", "tseStatus": "SIGNED", "createdAt": "2026-07-10T13:46:53.184Z", "items": [ { "id": "1769e956-db8c-45d4-92ac-0ee31d0e2473", "transactionId": "78f56cfc-8ce1-49c4-9b32-29e161904e5b", "productId": "5423c277-c14f-445a-a45e-0303833c1218", "productName": "Trauringe", "productSku": "SVC-CUSTOM", "quantity": -1, "unitPrice": "288", "vatRate": "NORMAL", "discountPercent": "0", "discountAmount": "0", "lineTotal": "-288", "gvTyp": null, "taxTreatment": null, "marginPurchasePrice": null, "marginBase": null, "createdAt": "2026-07-10T13:46:53.184Z" } ], "payments": [ { "id": "c77ecf74-b2f7-4be3-94d9-c98b3193bcc0", "transactionId": "78f56cfc-8ce1-49c4-9b32-29e161904e5b", "method": "VOUCHER", "amount": "-288", "reference": null, "createdAt": "2026-07-10T13:46:53.184Z" } ] } ], "meta": { "page": 1, "limit": 1, "total": 45, "totalPages": 45 } } } } } } }, "summary": "List transactions", "tags": ["Transactions"], "description": "Returns completed POS transactions including line items and payments, paginated. Filter by `dateFrom`/`dateTo`, `status`, `type`, `paymentMethod`, `customerId`, or `registerId`. This is the data source for building your own reports and dashboards — pull incrementally using the date filters." } }, "/api/v1/transactions/export/datev": { "get": { "operationId": "TransactionController_getDatevExport", "parameters": [ { "name": "dateFrom", "required": true, "in": "query", "schema": { "pattern": "/^\\d{4}-\\d{2}-\\d{2}$/", "type": "string" } }, { "name": "dateTo", "required": true, "in": "query", "schema": { "pattern": "/^\\d{4}-\\d{2}-\\d{2}$/", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/csv": { "schema": { "type": "string" }, "example": "\"EXTF\";700;21;\"Buchungsstapel\";13;20260701101500000;;\"\";\"\";\"\";1000;10001;20260101;4;20260101;20260630;\"Gemwise\";\"\";;;\n\"Umsatz (ohne Soll/Haben-Kz)\";\"Soll/Haben-Kennzeichen\";…" } } } }, "summary": "Export for DATEV", "tags": ["Transactions"], "description": "Exports transactions of a date range in DATEV-compatible CSV format for handover to accounting or a tax advisor. Requires DATEV master data (consultant and client number) to be configured in the Gemwise dashboard first — otherwise the request fails with `412 Precondition Failed`." } }, "/api/v1/transactions/{id}": { "get": { "operationId": "TransactionController_findById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "registerId": { "type": "string", "format": "uuid" }, "kassenSeriennr": { "type": "string" }, "sessionId": { "type": "string", "format": "uuid" }, "transactionNumber": { "type": "string" }, "idempotencyKey": { "nullable": true }, "type": { "type": "string" }, "status": { "type": "string" }, "customerId": { "nullable": true }, "cashierId": { "type": "string", "format": "uuid" }, "subtotal": { "type": "string" }, "taxAmount": { "type": "string" }, "totalAmount": { "type": "string" }, "discountAmount": { "type": "string" }, "taxBreakdown": { "type": "array", "items": { "type": "object", "properties": { "net": { "type": "number" }, "tax": { "type": "number" }, "rate": { "type": "string" }, "gross": { "type": "integer" }, "ratePercent": { "type": "integer" } } } }, "notes": { "type": "string" }, "originalTransactionId": { "type": "string", "format": "uuid" }, "tseSignature": { "type": "string" }, "tseCounter": { "type": "integer" }, "tseTxId": { "type": "string", "format": "uuid" }, "tseStartTime": { "type": "string", "format": "date-time" }, "tseFinishTime": { "type": "string", "format": "date-time" }, "tseCertSerial": { "type": "string" }, "tseQrCodeData": { "type": "string" }, "tseSignatureAlgorithm": { "type": "string" }, "tseStatus": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "transactionId": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "quantity": { "type": "integer" }, "unitPrice": { "type": "string" }, "vatRate": { "type": "string" }, "discountPercent": { "type": "string" }, "discountAmount": { "type": "string" }, "lineTotal": { "type": "string" }, "gvTyp": { "nullable": true }, "taxTreatment": { "nullable": true }, "marginPurchasePrice": { "nullable": true }, "marginBase": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "transactionId": { "type": "string", "format": "uuid" }, "method": { "type": "string" }, "amount": { "type": "string" }, "reference": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } }, "example": { "success": true, "data": { "id": "78f56cfc-8ce1-49c4-9b32-29e161904e5b", "tenantId": "a0000000-0000-4000-a000-000000000001", "registerId": "544897bb-6a66-41dd-919b-3f6a5b6d6525", "kassenSeriennr": "GW-A0BB0D", "sessionId": "eb2d8184-1b5f-4550-b004-08cd0db8d975", "transactionNumber": "BON-2026-479044", "idempotencyKey": null, "type": "RETURN", "status": "COMPLETED", "customerId": null, "cashierId": "b0000000-0000-4000-a000-000000000001", "subtotal": "-242.02", "taxAmount": "-45.98", "totalAmount": "-288", "discountAmount": "0", "taxBreakdown": [ { "net": -242.02, "tax": -45.98, "rate": "19%", "gross": -288, "ratePercent": 19 } ], "notes": "Return of items from BON-2026-276520", "originalTransactionId": "fa7f845b-91c1-424f-92d7-72945f228039", "tseSignature": "satQjKt44XTBn0WgbbnrEExCs+Y20zQtQodkI1C/tZ/YUneX9LPTfr7ASjadQFKFuPoXLhOkfSpHa52OeoWZNA==", "tseCounter": 309, "tseTxId": "e2d59760-dbc1-47bc-af25-44488924a24a", "tseStartTime": "2026-07-10T13:46:52.000Z", "tseFinishTime": "2026-07-10T13:46:52.000Z", "tseCertSerial": "0d5bc08b6e713e8faa7f4c6e0d2ac8769cb2b3eeb6d54205675f3ba480d1da86", "tseQrCodeData": "V0;GW-A0BB0D;Kassenbeleg-V1;Beleg^-288.00_0.00_0.00_0.00_0.00^-288.00:Unbar;98;309;2026-07-10T13:46:52.000Z;2026-07-10T13:46:52.000Z;ecdsa-plain-SHA256;unixTime;satQjKt44XTBn0WgbbnrEExCs+Y20zQtQodkI1C/tZ/YUneX9LPTfr7ASjadQFKFuPoXLhOkfSpHa52OeoWZNA==;BKWvdS77s+awjDnYEFegw/kibyxa28nsds0nm/TlS7Q3BvIY9IEFpGq3GGD0q3lymrNXW5kobPsFl5QnvpAXTw8=", "tseSignatureAlgorithm": "ecdsa-plain-SHA256", "tseStatus": "SIGNED", "createdAt": "2026-07-10T13:46:53.184Z", "items": [ { "id": "1769e956-db8c-45d4-92ac-0ee31d0e2473", "transactionId": "78f56cfc-8ce1-49c4-9b32-29e161904e5b", "productId": "5423c277-c14f-445a-a45e-0303833c1218", "productName": "Trauringe", "productSku": "SVC-CUSTOM", "quantity": -1, "unitPrice": "288", "vatRate": "NORMAL", "discountPercent": "0", "discountAmount": "0", "lineTotal": "-288", "gvTyp": null, "taxTreatment": null, "marginPurchasePrice": null, "marginBase": null, "createdAt": "2026-07-10T13:46:53.184Z" } ], "payments": [ { "id": "c77ecf74-b2f7-4be3-94d9-c98b3193bcc0", "transactionId": "78f56cfc-8ce1-49c4-9b32-29e161904e5b", "method": "VOUCHER", "amount": "-288", "reference": null, "createdAt": "2026-07-10T13:46:53.184Z" } ] } } } } } }, "summary": "Get a transaction", "tags": ["Transactions"], "description": "Returns a single transaction with line items, payments, and fiscal (TSE) signature data." } }, "/api/v1/online-sales/ingest": { "post": { "operationId": "OnlineSalesController_ingest", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sales_IngestTriggerDto" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "onlineOrderId": { "type": "string", "format": "uuid" }, "orderNumber": { "type": "string" }, "duplicate": { "type": "boolean" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "matchStatus": { "type": "string" }, "requested": { "type": "integer" }, "decremented": { "type": "integer" } } } } } } } }, "example": { "success": true, "data": { "onlineOrderId": "fe190c8b-c84a-4391-bdb2-18a23859127f", "orderNumber": "SW-10024", "duplicate": false, "lines": [ { "name": "Trauring Gelbgold 585", "matchStatus": "MATCHED", "requested": 1, "decremented": 1 }, { "name": "Geschenkverpackung", "matchStatus": "UNMATCHED", "requested": 1, "decremented": 0 } ] } } } } } }, "summary": "Ingest a paid online order", "tags": ["Online Sales"], "description": "Notifies Gemwise that an online order has been paid — pass the shop `orderId` (e.g. from a Shopware `order_transaction.state.paid` webhook). Gemwise fetches the order from the configured channel, records the sale, and decrements inventory. Safe to call repeatedly for the same order: ingestion is idempotent per order ID (the response `duplicate` flag indicates a replay). **Requires an API key with the `ONLINE_INTEGRATION` role** — this connector key is distinct from a regular staff key; ask your Gemwise administrator to provision one." } }, "/api/v1/online-sales": { "get": { "operationId": "OnlineSalesController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } }, { "name": "dateFrom", "required": false, "in": "query", "schema": { "pattern": "DATE_ONLY", "type": "string" } }, { "name": "dateTo", "required": false, "in": "query", "schema": { "pattern": "DATE_ONLY", "type": "string" } }, { "name": "source", "required": false, "in": "query", "schema": { "type": "string", "enum": ["SHOPWARE", "MAGENTO"] } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": ["RECORDED", "CANCELLED", "PARTIALLY_REFUNDED"] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" }, "description": "Recursively nested — same shape as the parent object." }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } }, "example": { "success": true, "data": { "data": [ { "id": "fe190c8b-c84a-4391-bdb2-18a23859127f", "tenantId": "a0000000-0000-4000-a000-000000000001", "source": "SHOPWARE", "externalOrderId": "0190b2e7c5e1700aa4f3b1d9c8e60202", "orderNumber": "ONL-2026-000005", "orderedAt": "2026-06-10T10:37:31.041Z", "currency": "EUR", "taxMode": "gross", "customerId": null, "customerSnapshot": { "email": "m.weber@example.com", "company": "Weber & Sohn GbR", "lastName": "Weber", "firstName": "Markus", "externalId": "c9d8e7f60190b2e7c5e1700aa4f3b202", "billingAddress": { "zip": "29683", "city": "Bad Fallingbostel", "street": "Marktplatz 3", "country": "DE" }, "customerNumber": "SW-1004" }, "subtotal": "1998", "taxAmount": "319.01", "totalAmount": "1998", "discountAmount": "0", "shippingAmount": "0", "taxBreakdown": [ { "tax": 319.01, "price": 1998, "taxRate": 19 } ], "status": "RECORDED", "rawPayload": { "note": "original shop payload (stored verbatim)" }, "createdAt": "2026-06-10T10:55:17.927Z", "items": [ { "id": "c216a6f1-c096-4095-a1a8-1157c1dc95cf", "onlineOrderId": "fe190c8b-c84a-4391-bdb2-18a23859127f", "productId": "8b014411-83e8-4e49-af3d-09284be95a1d", "externalSku": "0,10ct. Brill.-3", "externalEan": "41056800", "productName": "Breuning Solitär · 0,10ct. Brill.", "quantity": 2, "unitPrice": "999", "discountAmount": "0", "lineTotal": "1998", "taxRate": "19", "matchStatus": "MATCHED", "createdAt": "2026-06-10T10:55:17.927Z" } ], "payments": [ { "id": "317dbb27-f040-4fe3-9b25-4fb4fbf41c12", "onlineOrderId": "fe190c8b-c84a-4391-bdb2-18a23859127f", "method": "CARD_ONLINE", "methodRaw": "credit_card", "amount": "1998", "reference": null, "createdAt": "2026-06-10T10:55:17.927Z" } ] } ], "meta": { "page": 1, "limit": 1, "total": 5, "totalPages": 5 } } } } } } }, "summary": "List ingested online orders", "tags": ["Online Sales"], "description": "Returns online orders that were ingested into Gemwise, paginated, with their processing status." } }, "/api/v1/online-sales/exceptions": { "get": { "operationId": "OnlineSalesController_listExceptions", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": ["OPEN", "RESOLVED"] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" }, "description": "Recursively nested — same shape as the parent object." }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } }, "example": { "success": true, "data": { "data": [ { "id": "d65aab54-e051-4bbc-8498-42d00017a14b", "tenantId": "a0000000-0000-4000-a000-000000000001", "onlineOrderId": "fe190c8b-c84a-4391-bdb2-18a23859127f", "kind": "SHORT_STOCK", "detail": { "productId": "8b014411-83e8-4e49-af3d-09284be95a1d", "requested": 2, "decremented": 1, "productName": "Breuning Solitär · 0,10ct. Brill." }, "status": "OPEN", "createdAt": "2026-06-10T10:55:17.982Z", "resolvedAt": null, "resolvedBy": null } ], "meta": { "page": 1, "limit": 1, "total": 4, "totalPages": 4 } } } } } } }, "summary": "List ingest exceptions", "tags": ["Online Sales"], "description": "Returns orders that could not be ingested (e.g. unknown SKU, missing stock), with the failure reason. This is a back-office monitoring endpoint — it requires an `OWNER` or `MANAGER` key, not the `ONLINE_INTEGRATION` ingest key." } }, "/api/v1/online-sales/exceptions/{id}/resolve": { "post": { "operationId": "OnlineSalesController_resolveException", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "onlineOrderId": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "detail": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid" }, "requested": { "type": "integer" }, "decremented": { "type": "integer" }, "productName": { "type": "string" } } }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": "string", "format": "date-time" }, "resolvedBy": { "type": "string", "format": "uuid" } } } } }, "example": { "success": true, "data": { "id": "d65aab54-e051-4bbc-8498-42d00017a14b", "tenantId": "a0000000-0000-4000-a000-000000000001", "onlineOrderId": "fe190c8b-c84a-4391-bdb2-18a23859127f", "kind": "SHORT_STOCK", "detail": { "productId": "8b014411-83e8-4e49-af3d-09284be95a1d", "requested": 2, "decremented": 1, "productName": "Breuning Solitär · 0,10ct. Brill." }, "status": "RESOLVED", "createdAt": "2026-06-10T10:55:17.982Z", "resolvedAt": "2026-07-10T15:16:35.965Z", "resolvedBy": "b0000000-0000-4000-a000-000000000001" } } } } } }, "summary": "Resolve an ingest exception", "tags": ["Online Sales"], "description": "Marks an ingest exception as handled after you fixed the underlying problem (and, if applicable, re-triggered ingestion). Requires an `OWNER` or `MANAGER` key." } }, "/api/v1/online-sales/config/{source}": { "get": { "operationId": "OnlineSalesController_getConfig", "parameters": [ { "name": "source", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "source": { "type": "string" }, "active": { "type": "boolean" }, "warehouseId": { "type": "string", "format": "uuid" }, "adminApiUrl": { "type": "string" }, "accessKeyId": { "type": "string" }, "hasSecret": { "type": "boolean" }, "lastReconcileAt": { "nullable": true } } } } }, "example": { "success": true, "data": { "source": "SHOPWARE", "active": false, "warehouseId": "e1000000-0000-4000-a000-000000000001", "adminApiUrl": "https://mock-shopware.local", "accessKeyId": "SWIADEMOKEY", "hasSecret": true, "lastReconcileAt": null } } } } } }, "summary": "Get channel configuration", "tags": ["Online Sales"], "description": "Returns the configuration of an online channel (`SHOPWARE` or `MAGENTO`). Requires an `OWNER` or `MANAGER` key. Channel configuration is managed in the Gemwise dashboard." } }, "/api/v1/online-sales/{id}": { "get": { "operationId": "OnlineSalesController_findById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "externalOrderId": { "type": "string" }, "orderNumber": { "type": "string" }, "orderedAt": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "taxMode": { "type": "string" }, "customerId": { "nullable": true }, "customerSnapshot": { "type": "object", "properties": { "email": { "type": "string" }, "company": { "type": "string" }, "lastName": { "type": "string" }, "firstName": { "type": "string" }, "externalId": { "type": "string" }, "billingAddress": { "type": "object", "properties": { "zip": { "type": "string" }, "city": { "type": "string" }, "street": { "type": "string" }, "country": { "type": "string" } } }, "customerNumber": { "type": "string" } } }, "subtotal": { "type": "string" }, "taxAmount": { "type": "string" }, "totalAmount": { "type": "string" }, "discountAmount": { "type": "string" }, "shippingAmount": { "type": "string" }, "taxBreakdown": { "type": "array", "items": { "type": "object", "properties": { "tax": { "type": "number" }, "price": { "type": "integer" }, "taxRate": { "type": "integer" } } } }, "status": { "type": "string" }, "rawPayload": { "type": "object", "properties": { "note": { "type": "string" } } }, "createdAt": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "onlineOrderId": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "externalSku": { "type": "string" }, "externalEan": { "type": "string" }, "productName": { "type": "string" }, "quantity": { "type": "integer" }, "unitPrice": { "type": "string" }, "discountAmount": { "type": "string" }, "lineTotal": { "type": "string" }, "taxRate": { "type": "string" }, "matchStatus": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "onlineOrderId": { "type": "string", "format": "uuid" }, "method": { "type": "string" }, "methodRaw": { "type": "string" }, "amount": { "type": "string" }, "reference": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } }, "example": { "success": true, "data": { "id": "fe190c8b-c84a-4391-bdb2-18a23859127f", "tenantId": "a0000000-0000-4000-a000-000000000001", "source": "SHOPWARE", "externalOrderId": "0190b2e7c5e1700aa4f3b1d9c8e60202", "orderNumber": "ONL-2026-000005", "orderedAt": "2026-06-10T10:37:31.041Z", "currency": "EUR", "taxMode": "gross", "customerId": null, "customerSnapshot": { "email": "m.weber@example.com", "company": "Weber & Sohn GbR", "lastName": "Weber", "firstName": "Markus", "externalId": "c9d8e7f60190b2e7c5e1700aa4f3b202", "billingAddress": { "zip": "29683", "city": "Bad Fallingbostel", "street": "Marktplatz 3", "country": "DE" }, "customerNumber": "SW-1004" }, "subtotal": "1998", "taxAmount": "319.01", "totalAmount": "1998", "discountAmount": "0", "shippingAmount": "0", "taxBreakdown": [ { "tax": 319.01, "price": 1998, "taxRate": 19 } ], "status": "RECORDED", "rawPayload": { "note": "original shop payload (stored verbatim)" }, "createdAt": "2026-06-10T10:55:17.927Z", "items": [ { "id": "c216a6f1-c096-4095-a1a8-1157c1dc95cf", "onlineOrderId": "fe190c8b-c84a-4391-bdb2-18a23859127f", "productId": "8b014411-83e8-4e49-af3d-09284be95a1d", "externalSku": "0,10ct. Brill.-3", "externalEan": "41056800", "productName": "Breuning Solitär · 0,10ct. Brill.", "quantity": 2, "unitPrice": "999", "discountAmount": "0", "lineTotal": "1998", "taxRate": "19", "matchStatus": "MATCHED", "createdAt": "2026-06-10T10:55:17.927Z" } ], "payments": [ { "id": "317dbb27-f040-4fe3-9b25-4fb4fbf41c12", "onlineOrderId": "fe190c8b-c84a-4391-bdb2-18a23859127f", "method": "CARD_ONLINE", "methodRaw": "credit_card", "amount": "1998", "reference": null, "createdAt": "2026-06-10T10:55:17.927Z" } ] } } } } } }, "summary": "Get an ingested order", "tags": ["Online Sales"], "description": "Returns a single ingested online order including the recorded sale reference." } }, "/api/v1/customers": { "get": { "operationId": "CustomerController_findAll", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "isActive", "required": false, "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" }, "description": "Recursively nested — same shape as the parent object." }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } }, "example": { "success": true, "data": { "data": [ { "id": "edeb3f5a-2be3-4fdf-9ca9-2a8ba1438556", "tenantId": "a0000000-0000-4000-a000-000000000001", "customerNumber": "K-0001", "firstName": "Saed", "lastName": "Abed", "email": "saed@flownova.de", "phone": null, "street": null, "city": null, "postalCode": null, "notes": null, "tags": [], "isActive": true, "createdAt": "2026-07-03T16:35:16.053Z", "updatedAt": "2026-07-03T16:35:16.053Z" } ], "meta": { "page": 1, "limit": 1, "total": 1, "totalPages": 1 } } } } } } }, "summary": "List customers", "tags": ["Customers"], "description": "Returns customer master data, paginated. Supports text search via the `search` parameter." }, "post": { "operationId": "CustomerController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sales_CreateCustomerDto" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "customerNumber": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phone": { "nullable": true }, "street": { "nullable": true }, "city": { "nullable": true }, "postalCode": { "nullable": true }, "notes": { "nullable": true }, "tags": { "type": "array", "items": { "type": "object" } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "example": { "success": true, "data": { "id": "fcb25626-c85c-4959-8c74-8f3c519773e9", "tenantId": "a0000000-0000-4000-a000-000000000001", "customerNumber": "K-0002", "firstName": "Docs", "lastName": "Example", "email": "docs-example@example.com", "phone": null, "street": null, "city": null, "postalCode": null, "notes": null, "tags": [], "isActive": true, "createdAt": "2026-07-10T15:16:35.758Z", "updatedAt": "2026-07-10T15:16:35.758Z" } } } } } }, "summary": "Create a customer", "tags": ["Customers"], "description": "Creates a customer record with contact data. Typical entry point for CRM or shop-account sync." } }, "/api/v1/customers/{id}": { "get": { "operationId": "CustomerController_findById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "customerNumber": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phone": { "nullable": true }, "street": { "nullable": true }, "city": { "nullable": true }, "postalCode": { "nullable": true }, "notes": { "nullable": true }, "tags": { "type": "array", "items": { "type": "object" } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "example": { "success": true, "data": { "id": "edeb3f5a-2be3-4fdf-9ca9-2a8ba1438556", "tenantId": "a0000000-0000-4000-a000-000000000001", "customerNumber": "K-0001", "firstName": "Saed", "lastName": "Abed", "email": "saed@flownova.de", "phone": null, "street": null, "city": null, "postalCode": null, "notes": null, "tags": [], "isActive": true, "createdAt": "2026-07-03T16:35:16.053Z", "updatedAt": "2026-07-03T16:35:16.053Z" } } } } } }, "summary": "Get a customer", "tags": ["Customers"], "description": "Returns a single customer by ID." }, "patch": { "operationId": "CustomerController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sales_UpdateCustomerDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "customerNumber": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "street": { "nullable": true }, "city": { "nullable": true }, "postalCode": { "nullable": true }, "notes": { "nullable": true }, "tags": { "type": "array", "items": { "type": "object" } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "example": { "success": true, "data": { "id": "edeb3f5a-2be3-4fdf-9ca9-2a8ba1438556", "tenantId": "a0000000-0000-4000-a000-000000000001", "customerNumber": "K-0001", "firstName": "Saed", "lastName": "Abed", "email": "saed@flownova.de", "phone": "+49 5161 480000", "street": null, "city": null, "postalCode": null, "notes": null, "tags": [], "isActive": true, "createdAt": "2026-07-03T16:35:16.053Z", "updatedAt": "2026-07-10T15:17:16.956Z" } } } } } }, "summary": "Update a customer", "tags": ["Customers"], "description": "Partially updates customer master data — only the fields you send are changed." }, "delete": { "operationId": "CustomerController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "customerNumber": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phone": { "nullable": true }, "street": { "nullable": true }, "city": { "nullable": true }, "postalCode": { "nullable": true }, "notes": { "nullable": true }, "tags": { "type": "array", "items": { "type": "object" } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "example": { "success": true, "data": { "id": "edeb3f5a-2be3-4fdf-9ca9-2a8ba1438556", "tenantId": "a0000000-0000-4000-a000-000000000001", "customerNumber": "K-0001", "firstName": "Saed", "lastName": "Abed", "email": "saed@flownova.de", "phone": null, "street": null, "city": null, "postalCode": null, "notes": null, "tags": [], "isActive": false, "createdAt": "2026-07-03T16:35:16.053Z", "updatedAt": "2026-07-03T16:35:16.053Z" } } } } } }, "summary": "Deactivate a customer", "tags": ["Customers"], "description": "Soft-deletes a customer by setting `isActive` to false. The record and its data are retained (fiscal/GDPR-record-keeping), and past transactions keep their customer link. This is a deactivation, not a hard erasure." } }, "/api/v1/customers/{id}/transactions": { "get": { "operationId": "CustomerController_getTransactions", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "page", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" }, "description": "Recursively nested — same shape as the parent object." }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } }, "example": { "success": true, "data": { "data": [ { "id": "ceaae752-2494-40d3-a809-524ec747f220", "tenantId": "a0000000-0000-4000-a000-000000000001", "registerId": "544897bb-6a66-41dd-919b-3f6a5b6d6525", "kassenSeriennr": "GW-A0BB0D", "sessionId": null, "transactionNumber": "BON-2026-882491", "idempotencyKey": null, "type": "DEPOSIT_SETTLEMENT", "status": "COMPLETED", "customerId": "edeb3f5a-2be3-4fdf-9ca9-2a8ba1438556", "cashierId": "b0000000-0000-4000-a000-000000000001", "subtotal": "840.33", "taxAmount": "159.66", "totalAmount": "1000", "discountAmount": "0", "taxBreakdown": [ { "net": 840.33, "tax": 159.66, "rate": "19%", "gross": 1000, "ratePercent": 19 } ], "notes": "Schlussrechnung ANZ-2026-0005", "originalTransactionId": null, "tseSignature": "Sa44n8tqAm+0Ww9uxebSlhGJSETUBY+OmDEsjNuG1hz5jW6oHNpF51UEWweI7fWqMbF+UBZfYy7rinQNGvwhGw==", "tseCounter": 307, "tseTxId": null, "tseStartTime": "2026-07-10T13:25:23.000Z", "tseFinishTime": "2026-07-10T13:25:23.000Z", "tseCertSerial": "0d5bc08b6e713e8faa7f4c6e0d2ac8769cb2b3eeb6d54205675f3ba480d1da86", "tseQrCodeData": "V0;GW-A0BB0D;Kassenbeleg-V1;Beleg^1000.00_0.00_0.00_0.00_0.00^1000.00:Bar;97;307;2026-07-10T13:25:23.000Z;2026-07-10T13:25:23.000Z;ecdsa-plain-SHA256;unixTime;Sa44n8tqAm+0Ww9uxebSlhGJSETUBY+OmDEsjNuG1hz5jW6oHNpF51UEWweI7fWqMbF+UBZfYy7rinQNGvwhGw==;BKWvdS77s+awjDnYEFegw/kibyxa28nsds0nm/TlS7Q3BvIY9IEFpGq3GGD0q3lymrNXW5kobPsFl5QnvpAXTw8=", "tseSignatureAlgorithm": "ecdsa-plain-SHA256", "tseStatus": "SIGNED", "createdAt": "2026-07-10T13:25:24.188Z", "items": [ { "id": "357ccb7c-e612-4f75-b46a-e228e1a8c6ed", "transactionId": "ceaae752-2494-40d3-a809-524ec747f220", "productId": "54e34767-55d7-49cb-a5ec-f1236dae2171", "productName": "Trauringe", "productSku": "SVC-CUSTOM", "quantity": 1, "unitPrice": "2000", "vatRate": "NORMAL", "discountPercent": "0", "discountAmount": "0", "lineTotal": "2000", "gvTyp": null, "taxTreatment": null, "marginPurchasePrice": null, "marginBase": null, "createdAt": "2026-07-10T13:25:24.188Z" }, { "id": "7f9f50d3-123f-4326-9988-a4e8af2c37c4", "transactionId": "ceaae752-2494-40d3-a809-524ec747f220", "productId": "c56f120d-a1a1-49b2-aca0-879d6aef5dd4", "productName": "Anzahlungsverrechnung ANZ-2026-0005 (19%)", "productSku": "ANZAHLUNG", "quantity": 1, "unitPrice": "-1000", "vatRate": "NORMAL", "discountPercent": "0", "discountAmount": "0", "lineTotal": "-1000", "gvTyp": "Anzahlungsaufloesung", "taxTreatment": null, "marginPurchasePrice": null, "marginBase": null, "createdAt": "2026-07-10T13:25:24.188Z" } ], "payments": [ { "id": "e913d1b4-d68b-4f03-9677-104f5ccbb07d", "transactionId": "ceaae752-2494-40d3-a809-524ec747f220", "method": "CASH", "amount": "1000", "reference": "a27279cb-c1ad-4727-a4a0-39e4020bdce4", "createdAt": "2026-07-10T13:25:24.188Z" } ] } ], "meta": { "page": 1, "limit": 1, "total": 7, "totalPages": 7 } } } } } } }, "summary": "List customer purchases", "tags": ["Customers"], "description": "Returns the purchase history of a customer as a paginated list of transactions." } }, "/api/v1/repairs/track/{jobNumber}": { "get": { "operationId": "TrackingController_getStatus", "parameters": [ { "name": "jobNumber", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "t", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "t", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Tracking token printed on the intake receipt / repair slip." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "jobNumber": { "type": "string" }, "status": { "type": "string" }, "itemDescription": { "type": "string" }, "customerName": { "nullable": true }, "intakeAt": { "type": "string", "format": "date-time" }, "estimatedCompletionAt": { "nullable": true }, "completedAt": { "type": "string", "format": "date-time" }, "returnedAt": { "type": "string", "format": "date-time" }, "timeline": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "date": { "type": "string", "format": "date-time" } } } }, "quote": { "nullable": true } } } } }, "example": { "success": true, "data": { "jobNumber": "REP-0017", "status": "ABGEHOLT", "itemDescription": "Goldring", "customerName": null, "intakeAt": "2026-07-10T12:22:26.539Z", "estimatedCompletionAt": null, "completedAt": "2026-07-10T12:22:45.014Z", "returnedAt": "2026-07-10T12:22:57.095Z", "timeline": [ { "status": "FERTIG", "date": "2026-07-10T12:22:45.031Z" }, { "status": "ABGEHOLT", "date": "2026-07-10T12:22:57.107Z" } ], "quote": null } } } } } }, "summary": "Track a repair (public)", "tags": ["Track"], "description": "Returns the public status of a repair job by its job number — the same data shown on the customer tracking page. Requires the tracking token from the intake receipt as query parameter `t`. No authentication required; responses are rate-limited per IP.", "security": [] } }, "/api/v1/webhooks/event-types": { "get": { "operationId": "WebhooksController_eventTypes", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "source": { "type": "string" } } } } } }, "example": { "success": true, "data": [ { "type": "transaction.completed", "label": "Verkauf abgeschlossen", "description": "Wird ausgelöst, sobald ein Kassiervorgang abgeschlossen und TSE-signiert wurde.", "source": "sales-service" }, { "type": "transaction.voided", "label": "Verkauf storniert", "description": "Wird ausgelöst, wenn eine Transaktion storniert wurde (Storno-Beleg).", "source": "sales-service" } ] } } } } }, "summary": "List subscribable events", "tags": ["Webhooks"], "description": "Returns the catalog of event types you can subscribe to (e.g. `transaction.completed`, `inventory.low_stock`, `repair.status_changed`). Each entry carries `type`, a human `label`, a `description`, and the emitting `source`." } }, "/api/v1/webhooks/endpoints": { "post": { "operationId": "WebhooksController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook_CreateWebhookEndpointDto" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "description": { "nullable": true }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "secretMasked": { "type": "string" }, "isActive": { "type": "boolean" }, "failureCount": { "type": "integer" }, "disabledAt": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string" } } } } }, "example": { "success": true, "data": { "id": "9596451b-ebec-46b1-bc33-b4e92a78594f", "url": "https://example.com/gemwise-docs", "description": null, "eventTypes": ["transaction.completed"], "secretMasked": "••••mple", "isActive": true, "failureCount": 0, "disabledAt": null, "createdAt": "2026-07-10T15:16:35.832Z", "updatedAt": "2026-07-10T15:16:35.832Z", "secret": "whsec_9f2c4e1a8b7d_example" } } } } } }, "summary": "Create a webhook endpoint", "tags": ["Webhooks"], "description": "Registers an HTTPS URL for a set of event types. The response contains the signing secret **exactly once** — store it securely; it cannot be retrieved again (only rotated)." }, "get": { "operationId": "WebhooksController_findAll", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" }, "description": "Recursively nested — same shape as the parent object." }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } }, "example": { "success": true, "data": { "data": [ { "id": "a681592d-73e6-40ff-961f-f1e024d1ab0c", "url": "https://webhook.site/03d45402-1e7f-40f4-94c0-99960ea1d047", "description": "Kholeta", "eventTypes": ["transaction.completed", "repair.status_changed"], "secretMasked": "••••mple", "isActive": false, "failureCount": 18, "disabledAt": "2026-07-02T16:10:22.818Z", "createdAt": "2026-06-08T15:22:09.665Z", "updatedAt": "2026-07-02T16:14:57.007Z" } ], "meta": { "page": 1, "limit": 1, "total": 2, "totalPages": 2 } } } } } } }, "summary": "List webhook endpoints", "tags": ["Webhooks"], "description": "Returns your registered webhook endpoints with their subscribed event types and status, paginated." } }, "/api/v1/webhooks/endpoints/{id}": { "get": { "operationId": "WebhooksController_findById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "description": { "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "secretMasked": { "type": "string" }, "isActive": { "type": "boolean" }, "failureCount": { "type": "integer" }, "disabledAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "example": { "success": true, "data": { "id": "a681592d-73e6-40ff-961f-f1e024d1ab0c", "url": "https://webhook.site/03d45402-1e7f-40f4-94c0-99960ea1d047", "description": "Kholeta", "eventTypes": ["transaction.completed", "repair.status_changed"], "secretMasked": "••••mple", "isActive": false, "failureCount": 18, "disabledAt": "2026-07-02T16:10:22.818Z", "createdAt": "2026-06-08T15:22:09.665Z", "updatedAt": "2026-07-02T16:14:57.007Z" } } } } } }, "summary": "Get a webhook endpoint", "tags": ["Webhooks"], "description": "Returns a single webhook endpoint. The signing secret is never included." }, "patch": { "operationId": "WebhooksController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook_UpdateWebhookEndpointDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "description": { "nullable": true }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "secretMasked": { "type": "string" }, "isActive": { "type": "boolean" }, "failureCount": { "type": "integer" }, "disabledAt": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "example": { "success": true, "data": { "id": "9596451b-ebec-46b1-bc33-b4e92a78594f", "url": "https://example.com/gemwise-docs", "description": null, "eventTypes": ["transaction.completed"], "secretMasked": "••••mple", "isActive": false, "failureCount": 0, "disabledAt": null, "createdAt": "2026-07-10T15:16:35.832Z", "updatedAt": "2026-07-10T15:16:35.867Z" } } } } } }, "summary": "Update a webhook endpoint", "tags": ["Webhooks"], "description": "Updates URL, subscribed event types, or active state. Endpoints that failed repeatedly are disabled automatically (circuit breaker) and can be re-enabled here via `isActive`." }, "delete": { "operationId": "WebhooksController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } } } } }, "example": { "success": true, "data": { "id": "a681592d-73e6-40ff-961f-f1e024d1ab0c" } } } } } }, "summary": "Delete a webhook endpoint", "tags": ["Webhooks"], "description": "Removes the endpoint; deliveries to it stop immediately." } }, "/api/v1/webhooks/endpoints/{id}/rotate-secret": { "post": { "operationId": "WebhooksController_rotateSecret", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "description": { "nullable": true }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "secretMasked": { "type": "string" }, "isActive": { "type": "boolean" }, "failureCount": { "type": "integer" }, "disabledAt": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string" } } } } }, "example": { "success": true, "data": { "id": "9596451b-ebec-46b1-bc33-b4e92a78594f", "url": "https://example.com/gemwise-docs", "description": null, "eventTypes": ["transaction.completed"], "secretMasked": "••••mple", "isActive": true, "failureCount": 0, "disabledAt": null, "createdAt": "2026-07-10T15:16:35.832Z", "updatedAt": "2026-07-10T15:16:35.852Z", "secret": "whsec_9f2c4e1a8b7d_example" } } } } } }, "summary": "Rotate signing secret", "tags": ["Webhooks"], "description": "Generates a new signing secret and returns it once. Update your receiver before rotating — deliveries are signed with the new secret immediately." } }, "/api/v1/webhooks/endpoints/{id}/deliveries": { "get": { "operationId": "WebhooksController_deliveries", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "number" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": ["PENDING", "SUCCESS", "FAILED", "EXHAUSTED"] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" }, "description": "Recursively nested — same shape as the parent object." }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } }, "example": { "success": true, "data": { "data": [ { "id": "a2a34d39-be19-4015-b3ee-fed512ffc8b7", "endpointId": "a681592d-73e6-40ff-961f-f1e024d1ab0c", "eventId": "0d78a68c-1fb2-4625-90e9-f48a1a8ac7e1", "eventType": "transaction.completed", "status": "EXHAUSTED", "attempts": 6, "lastStatusCode": 404, "lastError": "HTTP 404", "nextRetryAt": null, "deliveredAt": null, "createdAt": "2026-07-02T16:07:11.317Z" } ], "meta": { "page": 1, "limit": 1, "total": 42, "totalPages": 42 } } } } } } }, "summary": "List deliveries", "tags": ["Webhooks"], "description": "Returns the delivery log of an endpoint (event, HTTP status, attempts, timestamps), paginated. Use it to debug a receiver." } }, "/api/v1/webhooks/deliveries/{id}/redeliver": { "post": { "operationId": "WebhooksController_redeliver", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "endpointId": { "type": "string", "format": "uuid" }, "eventId": { "type": "string", "format": "uuid" }, "eventType": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "lastStatusCode": { "nullable": true }, "lastError": { "nullable": true }, "nextRetryAt": { "nullable": true }, "deliveredAt": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } } }, "example": { "success": true, "data": { "id": "a2a34d39-be19-4015-b3ee-fed512ffc8b7", "endpointId": "a681592d-73e6-40ff-961f-f1e024d1ab0c", "eventId": "0d78a68c-1fb2-4625-90e9-f48a1a8ac7e1", "eventType": "transaction.completed", "status": "PENDING", "attempts": 0, "lastStatusCode": null, "lastError": null, "nextRetryAt": null, "deliveredAt": null, "createdAt": "2026-07-02T16:07:11.317Z" } } } } } }, "summary": "Redeliver an event", "tags": ["Webhooks"], "description": "Replays a delivery to your endpoint, e.g. after fixing a receiver bug. The payload is re-signed with the current secret." } } }, "info": { "title": "Gemwise API", "version": "1.0.0", "description": "The Gemwise API gives you programmatic access to your point-of-sale data: products, categories, customers, stock levels, transactions, and online-order ingestion.\n\n## Base URL\n\nAll requests go through your tenant-specific gateway:\n\n```\nhttps://{tenant}.api.gemwise.de/api/v1\n```\n\nReplace `{tenant}` with your Gemwise tenant subdomain.\n\n## Authentication\n\nAll requests are authenticated with an **API key**: send your integration key in the `x-api-key` header.\n\n```\nx-api-key: hpos_live_xxxxxxxxxxxx\n```\n\nAPI keys are created in the Gemwise dashboard under _Settings → API Keys_ and carry the roles of the user they were issued for — a key can never do more than its owner. Keys can be given an expiry date and revoked at any time.\n\nTo verify your key, call `GET /auth/me` — it returns the user your key acts as.\n\nThe only exception is repair tracking (`GET /repairs/track/{jobNumber}`), which is public and needs no authentication.\n\n## Response format\n\nEvery endpoint returns a consistent envelope. A single resource is returned directly under `data`:\n\n```json\n{ \"success\": true, \"data\": { \"id\": \"…\", \"name\": \"…\" } }\n```\n\nPaginated list endpoints nest the array and the pagination block **inside** `data` — the page metadata is at `data.meta`, not at the top level:\n\n```json\n{ \"success\": true, \"data\": { \"data\": [ … ], \"meta\": { \"page\": 1, \"limit\": 50, \"total\": 120, \"totalPages\": 3 } } }\n```\n\nA few flat reads (e.g. categories, attributes) return `data` as a plain array with no `meta`.\n\nErrors return `success: false` with an `error` object containing `code`, `message`, and optional `details`.\n\n## Pagination\n\nList endpoints accept `page` and `limit` query parameters, and return the pagination block at `data.meta`. The maximum `limit` is **100** — requests above that are rejected with `400 Bad Request`.\n\n## Webhooks\n\nInstead of polling, you can subscribe to domain events (see `GET /webhooks/event-types` for the catalog). Create an endpoint with `POST /webhooks/endpoints` — the signing secret is returned **once** on creation. Every delivery is signed: verify the `X-Gemwise-Signature` header (`sha256=`, HMAC-SHA256 over `` `${X-Gemwise-Timestamp}.${rawBody}` ``) before trusting a payload. Failed deliveries can be inspected via `GET /webhooks/endpoints/{id}/deliveries` and replayed with `POST /webhooks/deliveries/{id}/redeliver`.\n\n## Fiscal integrity\n\nCompleted transactions are fiscally signed (KassenSichV/TSE) and immutable. The API therefore exposes transactions **read-only**; corrections happen exclusively through the POS as reversal records.\n" }, "tags": [ { "name": "Auth", "description": "Verify your API credentials." }, { "name": "Categories", "description": "Product categories — the hierarchical grouping used in POS and shop." }, { "name": "Attributes", "description": "Attribute definitions describing industry-specific product fields (e.g. metal, carat, ring size)." }, { "name": "Products", "description": "The product catalog: master data, prices, barcodes, and images." }, { "name": "Inventory", "description": "Stock levels per product and warehouse, the movement audit trail, and stock-changing operations." }, { "name": "Transactions", "description": "Completed POS sales. Read-only: transactions are fiscally signed (TSE) and immutable — corrections happen at the register as reversal records." }, { "name": "Online Sales", "description": "Ingestion of paid online-shop orders (e.g. Shopware) into Gemwise: sale recording, inventory decrement, and exception handling." }, { "name": "Customers", "description": "Customer master data and purchase history." }, { "name": "Track", "description": "Public repair-status tracking — no authentication required." }, { "name": "Webhooks", "description": "Event subscriptions: get notified via signed HTTP POST instead of polling." } ], "servers": [ { "url": "https://{tenant}.api.gemwise.de", "description": "Production", "variables": { "tenant": { "default": "demo", "description": "Your Gemwise tenant subdomain" } } } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Integration key created in the Gemwise dashboard under Settings → API Keys. Keys carry the roles of the user they were issued for." } }, "schemas": { "catalog_CreateCategoryDto": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "parentId": { "type": "string", "format": "uuid" }, "sortOrder": { "type": "number", "minimum": 0 }, "icon": { "type": "string" } }, "required": ["name", "slug"] }, "catalog_UpdateCategoryDto": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "parentId": { "type": "string", "nullable": true, "format": "uuid" }, "sortOrder": { "type": "number", "minimum": 0 }, "icon": { "type": "string" } } }, "catalog_Object": { "type": "object", "properties": {} }, "catalog_ProductAttributeDto": { "type": "object", "properties": { "attributeDefinitionId": { "type": "string", "format": "uuid" }, "value": { "type": "string" } }, "required": ["attributeDefinitionId", "value"] }, "catalog_CreateProductDto": { "type": "object", "properties": { "name": { "type": "string" }, "sku": { "type": "string" }, "barcode": { "type": "string" }, "categoryId": { "type": "string", "format": "uuid" }, "price": { "type": "number", "minimum": 0 }, "costPrice": { "type": "number", "minimum": 0 }, "price2": { "type": "number", "minimum": 0 }, "vatRate": { "type": "object" }, "taxTreatment": { "type": "object" }, "marginPurchasePrice": { "type": "number", "minimum": 0 }, "brand": { "type": "string" }, "productType": { "type": "string" }, "description": { "type": "string" }, "imageUrl": { "type": "string" }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/catalog_ProductAttributeDto" } } }, "required": ["name", "sku", "categoryId", "price", "costPrice"] }, "catalog_UpdateProductDto": { "type": "object", "properties": { "name": { "type": "string" }, "sku": { "type": "string" }, "barcode": { "type": "string", "nullable": true }, "categoryId": { "type": "string", "format": "uuid" }, "vatRate": { "type": "object" }, "taxTreatment": { "type": "object" }, "marginPurchasePrice": { "type": "number", "minimum": 0 }, "description": { "type": "string" }, "imageUrl": { "type": "string" }, "isActive": { "type": "boolean" }, "sortOrder": { "type": "number", "minimum": 0 }, "price2": { "type": "number", "minimum": 0 }, "brand": { "type": "string" }, "productType": { "type": "string" }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/catalog_ProductAttributeDto" } } } }, "inventory_Object": { "type": "object", "properties": {} }, "inventory_ReceiveStockDto": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "quantity": { "type": "number", "minimum": 1 }, "performedBy": { "type": "string", "format": "uuid" }, "notes": { "type": "string" }, "referenceType": { "type": "string" }, "referenceId": { "type": "string" } }, "required": ["productId", "warehouseId", "quantity", "performedBy"] }, "inventory_AdjustStockDto": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "newQuantity": { "type": "number", "minimum": 0 }, "performedBy": { "type": "string", "format": "uuid" }, "reasonCode": { "type": "string", "enum": [ "DAMAGE", "SHRINKAGE", "COUNTING_ERROR", "DATA_ENTRY", "FOUND_STOCK", "WRONG_LOCATION", "OTHER" ] }, "note": { "type": "string" } }, "required": ["productId", "warehouseId", "newQuantity", "performedBy", "reasonCode"] }, "inventory_TransferStockDto": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid" }, "fromWarehouseId": { "type": "string", "format": "uuid" }, "toWarehouseId": { "type": "string", "format": "uuid" }, "quantity": { "type": "number", "minimum": 1 }, "performedBy": { "type": "string", "format": "uuid" }, "notes": { "type": "string" } }, "required": ["productId", "fromWarehouseId", "toWarehouseId", "quantity", "performedBy"] }, "sales_IngestTriggerDto": { "type": "object", "properties": { "orderId": { "type": "string", "description": "The paid order id in the source shop (e.g. Shopware).", "pattern": "/^[0-9a-f]{32}$/i" }, "source": { "type": "string", "description": "Source channel of the order. Defaults to the tenant’s configured channel.", "enum": ["shopware"] } }, "required": ["orderId"] }, "sales_CreateCustomerDto": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 100 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 100 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "maxLength": 30 }, "street": { "type": "string", "maxLength": 200 }, "city": { "type": "string", "maxLength": 100 }, "postalCode": { "type": "string", "maxLength": 10 }, "notes": { "type": "string", "maxLength": 1000 }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": ["firstName", "lastName"] }, "sales_UpdateCustomerDto": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 100 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 100 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "maxLength": 30 }, "street": { "type": "string", "maxLength": 200 }, "city": { "type": "string", "maxLength": 100 }, "postalCode": { "type": "string", "maxLength": 10 }, "notes": { "type": "string", "maxLength": 1000 }, "tags": { "type": "array", "items": { "type": "string" } }, "isActive": { "type": "boolean" } } }, "webhook_CreateWebhookEndpointDto": { "type": "object", "properties": { "url": { "type": "string", "description": "Publicly reachable HTTPS endpoint that will receive events. Private, loopback, and internal addresses are rejected.", "maxLength": 2048, "format": "uri" }, "description": { "type": "string", "maxLength": 200 }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "transaction.completed", "transaction.voided", "transaction.returned", "closing.completed", "repair.status_changed", "repair.completed", "inventory.low_stock", "online_sale.recorded", "online_sale.exception" ] }, "minItems": 1, "description": "One or more event types to subscribe to." } }, "required": ["url", "eventTypes"] }, "webhook_UpdateWebhookEndpointDto": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "description": { "type": "string", "maxLength": 200 }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "transaction.completed", "transaction.voided", "transaction.returned", "closing.completed", "repair.status_changed", "repair.completed", "inventory.low_stock", "online_sale.recorded", "online_sale.exception" ] }, "minItems": 1, "description": "One or more event types to subscribe to." }, "isActive": { "type": "boolean" } } } } }, "security": [ { "apiKey": [] } ] }