## List articles (tenant:masterdata:read)

`GET /api/masterdata/products`

Module: Master data · operationId: `listProducts` · Tag: Articles · Auth: access token (`Authorization: Bearer <accessToken>`)

Returns one page of compact article rows. `q` searches article number, search term, short name, name,
manufacturer part number and EAN (case-insensitive substring). `netPrice` is the sales price (`salesPrice`),
`purchasePrice` the price of the default supplier. `incomplete` marks articles that miss a field their
type requires (see `Product`); they stay readable but must be completed before they can be saved.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string |  | Search text |
| `search` | query | string |  | Alias of `q` (used when `q` is empty) |
| `groupId` | query | string (uuid) |  | Only articles of this product group (an invalid id matches nothing) |
| `type` | query | string |  | Comma-separated article types |
| `blocked` | query | string |  | `true` only blocked, `false` only unblocked articles (one of `true`, `false`) |
| `incomplete` | query | string |  | `true` only articles missing a field their type requires (TEXT articles never are), `false` only complete ones (one of `true`, `false`) |
| `sort` | query | string |  | Sort key, prefix `-` for descending; `name` sorts by the short name. Unknown keys sort by article number. (one of `articleNumber`, `-articleNumber`, `name`, `-name`, `price`, `-price`, `purchasePrice`, `-purchasePrice`, `group`, `-group`, `updatedAt`, `-updatedAt`, `createdAt`, `-createdAt`; default `"articleNumber"`) |
| `limit` | query | integer |  | Page size 1–200; any other value is `400 invalid` (default `50`; max 200) |
| `cursor` | query | string |  | `nextCursor` of the previous page; leave out for the first page. Keep `sort` and the filters unchanged while paging: a cursor of another sort or an altered one is `400 invalid` (`field: cursor`). (max length 1024) |

### Responses

- **200** One page of articles (`application/json`)
- **400** Malformed body or query parameter (`application/json`)
- **401** Missing, invalid or expired token (empty body)
- **403** The token lacks the permission or carries no tenant (`application/json`)

Fields of the 200 answer:

- `items` (array of ProductListItem, required): One page of articles
  - `articleNumber` (string, required): Article number
  - `articleType` (string, required): Article type (one of `GOODS`, `SERVICE`, `SUBSCRIPTION`, `TEXT`, `FEE`)
  - `id` (string (uuid), required): Id of the article
  - `incomplete` (boolean, required): The article misses a field its type requires (group
  - `isBlocked` (boolean, required): Blocked article
  - `name` (string, required): Name as stored (may be empty or span lines); lists show `shortName`
  - `shortName` (string, required): Short name (Kurzbezeichnung)
  - `updatedAt` (string (date-time), required): Time of the last change
  - `version` (integer, required): Optimistic locking version
  - `ean` (string): EAN/GTIN
  - `manufacturerPartNumber` (string): Manufacturer part number (MPN)
  - `netPrice` (number): Net sales price (`salesPrice`)
  - `productGroupId` (string (uuid)): Product group
  - `productGroupName` (string): Name of the product group
  - `purchasePrice` (number): Price of the default supplier
  - `unitCode` (string): Code of `units`
- `total` (integer, required): Number of matching articles
- `nextCursor` (string): Cursor of the next page (pass it as `cursor`); missing on the last page

Example 200 answer:

```json
{
  "items": [
    {
      "articleNumber": "HW-1004",
      "articleType": "GOODS",
      "ean": "4061234500045",
      "id": "6e8a0c2e-4f6a-4b8c-8d0e-2f4a6c8e0a2c",
      "incomplete": false,
      "isBlocked": false,
      "manufacturerPartNumber": "NL-DOCKC100",
      "name": "USB-C Dockingstation 100 W",
      "netPrice": 189,
      "productGroupId": "8d0b6f3e-2c4a-4e7b-9a1d-5f3c2e1b0a97",
      "productGroupName": "Hardware",
      "purchasePrice": 139,
      "shortName": "USB-C Dockingstation 100 W",
      "unitCode": "STK",
      "updatedAt": "2026-10-07T13:12:00Z",
      "version": 4
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/masterdata/products' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
