## Post a goods receipt (tenant:trade:purchasing:write)

`POST /api/trade/v1/goods-receipts`

Module: Trade · operationId: `createGoodsReceipt` · Tag: Procurement · Auth: access token (`Authorization: Bearer <accessToken>`)

Receives quantities for lines of an `open` or `partially_received` purchase order; a quantity
may not exceed what is still open. The order becomes `partially_received` or `received` in the
same transaction. Publishes `trade.goodsreceipt.created`.

### Request body

`application/json` (required)

- `grNumber` (string, required): Number of the goods receipt. (max length 64)
- `lines` (array of object, required): Received lines.
  - `poLineId` (string (uuid), required): Id of the purchase order line.
  - `receivedQty` (number, required): Quantity received.
- `poId` (string (uuid), required): Purchase order the goods were received for.
- `note` (string): Free-text note. (max length 1000)
- `receivedAt` (string (date-time)): Now when empty.

Example:

```json
{
  "grNumber": "WE-2026-00052",
  "lines": [
    {
      "poLineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e01",
      "receivedQty": 1
    },
    {
      "poLineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e02",
      "receivedQty": 3
    }
  ],
  "note": "Lieferschein LS-778812 (Kabelwerk Süd GmbH), vollständig und unbeschädigt.",
  "poId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68",
  "receivedAt": "2026-11-18T10:15:00Z"
}
```

### Responses

- **201** Posted (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)
- **409** The receipt number exists already, or the purchase order is draft, closed or cancelled. (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)

Fields of the 201 answer:

- `createdAt` (string (date-time)): When the goods receipt was created.
- `grNumber` (string): Number of the goods receipt.
- `id` (string (uuid)): Id of the goods receipt.
- `lines` (array of object): Empty in lists.
  - `description` (string): Description of the line.
  - `id` (string (uuid)): Id of the line.
  - `poLineId` (string (uuid)): Id of the purchase order line.
  - `position` (integer): Position of the line.
  - `receivedQty` (number): Quantity received.
- `note` (string): Free-text note.
- `poId` (string (uuid)): Purchase order the goods were received for.
- `poNumber` (string): Number of the purchase order.
- `receivedAt` (string (date-time)): When the goods were received.
- `status` (string): Status of the goods receipt (`posted`). (one of `posted`)

Example 201 answer:

```json
{
  "createdAt": "2026-11-18T10:15:00Z",
  "grNumber": "WE-2026-00052",
  "id": "3d6e7f8a-9b0c-4d1e-8f2a-4b5c6d7e8f52",
  "lines": [
    {
      "description": "Netzwerkschrank 19 Zoll 12 HE",
      "id": "5f8a9b0c-1d2e-4f3a-8b4c-6d7e8f9a0b01",
      "poLineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e01",
      "position": 1,
      "receivedQty": 1
    },
    {
      "description": "Verlegekabel Cat.7 Simplex, 100 m",
      "id": "5f8a9b0c-1d2e-4f3a-8b4c-6d7e8f9a0b02",
      "poLineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e02",
      "position": 2,
      "receivedQty": 3
    }
  ],
  "note": "Lieferschein LS-778812 (Kabelwerk Süd GmbH), vollständig und unbeschädigt.",
  "poId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68",
  "poNumber": "BE-2026-00068",
  "receivedAt": "2026-11-18T10:15:00Z",
  "status": "posted"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/goods-receipts' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"grNumber":"WE-2026-00052","lines":[{"poLineId":"2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e01","receivedQty":1},{"poLineId":"2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e02","receivedQty":3}],"note":"Lieferschein LS-778812 (Kabelwerk Süd GmbH), vollständig und unbeschädigt.","poId":"1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68","receivedAt":"2026-11-18T10:15:00Z"}'
```
